Create Your Own Elements

The Bricks child theme, which you can download from your account includes a simple custom element for demonstration purposes. The article below explains in more detail how to create your own elements.

Creating your own elements with Bricks follows a pattern similar to how you create WordPress widgets. You start by extending the \Bricks\Element class and populate the required properties and methods for your element.

First, create a new file element-test.php in the root folder of your child theme.

Blank element class

<?php 
// element-test.php
if ( ! defined( 'ABSPATH' ) ) exit; // Exit if accessed directly

class Prefix_Element_Test extends \Bricks\Element {
  // Element properties
  public $category     = '';
  public $name         = '';
  public $icon         = '';
  public $css_selector = '';
  public $scripts      = [];

  // Methods: Builder-specific
  public function get_label() {}
  public function set_control_groups() {}
  public function set_controls() {}

  // Methods: Frontend-specific
  public function enqueue_scripts() {}
  public function render() {}
}

Let's walk through the element builder properties and methods:

$category Category name (all lowercase, no spaces). Use any of the predefined element categories: general, media, social, header, wordpress and post. Or assign your own element category. When setting your own category make sure to provide a translatable category string for the builder using the filter: bricks/builder/i18n
$name Unique element identifier (all lowercase, no spaces). To avoid any conflicts with other elements please prefix your element name, e.g.: prefix-element-test.
$icon Icon font CSS class. Bricks includes the following icon fonts. Use any icon font CSS class to represent your element in the builder panel:
$css_selector By default all CSS control settings are applied to the element wrapper:  .bricks-element-wrapper. If you want the default CSS selector to target a child HTML element, set this selector here.
$scripts An array of JavaScript scripts that run when an element is rendered on the frontend or updated in the builder. The Counter element, for example, uses a script named "bricksCounter" (defined in frontend.min.css).
To load this script we use: public $scripts = ['bricksCounter'];
Please prefix all your scripts. E.g.: prefixElementTest
get_label() Return localized element label.
set_control_groups() By default, all element controls show ungrouped in the builder panel under the "Content" tab. Define custom control groups for your element controls by setting the following properties for each control group: 
  • title - Localized control group title
  • tab - Set to either "content" or "style"
set_controls() Define element controls. For an overview of all available controls and their settings visit: Element Controls
enqueue_scripts()
Load element-specific scripts and styles. Those are loaded only on pages where this element is used. Results in better performance. Example: wp_enqueue_script( 'prefix-element-test', get_template_directory_uri() . '/js/custom.js', ['jquery'], '1.0', true );
render() Renders element HTML. Define HTML attributes via  $this->set_attribute() and output them via $this->render_attribute()
set_attribute( $key, $attribute, $value ) Helper function to set HTML attributes for any HTML tag. $key serves as the unique identifier for this HTML tag. $attribute is the HTML attribute name. $value is a string or array which holds the attribute value(s).
render_attributes( $key ) Helper function to render HTML attributes defined via $this->set_attribute(). $key serves as the unique identifier for this HTML tag.

Let's populate our element properties and methods with some data:

<?php 
// element-test.php

if ( ! defined( 'ABSPATH' ) ) exit; // Exit if accessed directly

class Prefix_Element_Test extends \Bricks\Element {
  // Element properties
  public $category     = 'general'; // Use predefined element category 'general'
  public $name         = 'prefix-test'; // Make sure to prefix your elements
  public $icon         = 'ti-bolt-alt'; // Themify icon font class
  public $css_selector = '.prefix-test-wrapper'; // Default CSS selector
  public $scripts      = ['prefixElementTest']; // Script(s) run when element is rendered on frontend or updated in builder

  // Return localized element label
  public function get_label() {
    return esc_html__( 'Test element', 'bricks' );
  }

  // Set builder control groups
  public function set_control_groups() {
    $this->controls['text'] = [ // Unique group identifier (lowercase, no spaces)
      'title' => esc_html__( 'Text', 'bricks' ), // Localized control group title
      'tab' => 'content', // Set to either "content" or "style"
    ];

    $this->control_groups['settings'] = [
      'title' => esc_html__( 'Settings', 'bricks' ),
      'tab' => 'content',
    ];
  }
 
  // Set builder controls
  public function set_controls() {
    $this->controls['content'] = [ // Unique control identifier (lowercase, no spaces)
      'tab' => 'content', // Control tab: content/style
      'group' => 'text', // Show under control group
      'label' => esc_html__( 'Content', 'bricks' ), // Control label
      'type' => 'text', // Control type 
      'default' => esc_html__( 'Content goes here ..', 'bricks' ), // Default setting
    ];
    
    $this->controls['type'] = [
      'tab' => 'content',
      'group' => 'settings',
      'label' => esc_html__( 'Type', 'bricks' ),
      'type' => 'select',
      'options' => [
        ['info' => esc_html__( 'Info', 'bricks' )],
        ['success' => esc_html__( 'Success', 'bricks' )],
        ['warning' => esc_html__( 'Warning', 'bricks' )],
        ['danger' => esc_html__( 'Danger', 'bricks' )],
        ['muted' => esc_html__( 'Muted', 'bricks' )],
      ],
      'inline' => true,
      'clearable' => false,
      'pasteStyles' => false,
      'default' => 'info',
    ];
  }

  // Enqueue element styles and scripts
  public function enqueue_scripts() {
    wp_enqueue_script( 'prefix-test-script' );
  }

  // Render element HTML
  public function render() {
    // Set element attributes
    $wrapper_classes[] = 'prefix-test-wrapper';

    if ( isset( $this->settings['type'] ) ) {
      $wrapper_classes[] = 'color-' . $this->settings['type'];
    }

    // Set attribute tag for 'wrapper'
    $this->set_attribute( 'wrapper', 'class', $wrapper_classes );

    // Render element HTML
    echo '<div ' . $this->render_attributes( 'wrapper' ) . '>'; // 'wrapper' attributes
      if ( isset( $this->settings['content'] ) ) {
        echo '<div>' . $this->settings['content'] . '</div>';
      }
    echo '</div>';
  }
}
All element settings are stored in $this->settings. To get an overview of all element settings for development simply dump them on the screen like so: var_dump( $this->settings ); in the render() function.

Load and register your element

After creating your custom element there is only one thing left to do: load and register your element. Open up functions.php of your Bricks child theme and copy & paster the following code:

/**
 * Register custom elements
 */
add_action( 'init', function() {
  $element_files = [
    __DIR__ . '/element-test.php',
  ];

  foreach ( $element_files as $file ) {
    \Bricks\Elements::register_element( $file );
  }
} );