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 BricksElement 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 BricksElement {
  // 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:

$categoryCategory 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
$nameUnique element identifier (all lowercase, no spaces). To avoid any conflicts with other elements please prefix your element name, e.g.: prefix-element-test.
$iconIcon font CSS class. Bricks includes the following icon fonts. Use any icon font CSS class to represent your element in the builder panel:

 

$css_selectorBy 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.
$scriptsAn 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 BricksElement {
  // 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>';
  }
}

You can view all element controls over at: https://academy.bricksbuilder.io/topic/controls/

All element settings are stored in $this->settings. To view of element settings you can print them on the screen like so: var_dump( $this->settings ); in the render() function.

Load and register your element

After creating your custom element you need to load and register your element. Open up functions.php of your Bricks child theme and copy & paste the following code:

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

  foreach ( $element_files as $file ) {
    BricksElements::register_element( $file );
  }
} );