Add Custom Layout Builder Element

Applies to: Theme Blvd Framework 2.5+

Function Reference: themeblvd_add_builder_element

This function will add an element to be used within the layout builder.

Usage
$args = array(
	'id'		=> '',
	'name'		=> '',
	'options'	=> array(),
	'callback'	=> ''
);

themeblvd_add_builder_element( $args );
Parameters
$args
(array) (required) Arguments for your custom element
Default: None
  • ‘id’
    (string) A unique ID of the new element.
  • ‘name’
    (string) Name of the new element.
  • ‘options’
    (array) The array of options to be used for the element by the end-user in the layout builder. For more on formatting an array of options, see Formatting Options. Also, this is not required; your element doesn’t need to have user options.
  • ‘callback’
    (string) The name of the callback function to display the element on the frontend of the website.
Example

In this example, we’ll add a basic element that outputs a title and a chunk of text. This isn’t very useful other than just showing you how the different pieces get put together.

So, first let’s actually add the element to the layout builder and make it available to the user.

$options = array(
    array(
        'name'      => 'Title',
        'desc'      => 'Enter in your title.',
        'id'        => 'title',
        'type'      => 'text'
    ),
    array(
        'name'      => 'Content',
        'desc'      => 'Enter in your content.',
        'id'        => 'content',
        'type'      => 'textarea'
    )
);

$args = array(
    'id'        => 'my_new_element',
    'name'      => 'My New Element',
    'options'   => $options,
    'callback'  => 'display_my_new_element'
);

themeblvd_add_builder_element( $args );
Note: For more information on formatting your array of options, see the article, Formatting Options.

In the last argument of our $args array we just set up above, we set our callback function as display_my_new_element. So now we need to actually create this function, which is what’s going to display the element on the frontend of the website, if the user adds it to a custom layout. And this function needs to be setup to accept the following parameters.

  • $id – The unique ID assigned to this element.
  • $options – The options saved for the element.

Depending on how complex or simple your element is, you may or may not require these two parameters, but you must set up your function to accept them, anyway. Here’s a basic example, where we’re utilizing the options setup by the user, to output some content.

/**
 * Display my new element.
 */
function display_my_new_element( $id, $options ) {
    echo '<h3>' . $options['title'] . '</h3>';
    echo '<p>' . $options['content'] . '</p>';
}
Note: This process takes care of adding your new element to the Layout Builder and how its HTML markup gets displayed on the frontend of your website, but if your element requires any additional javascript or CSS, these will obviously need to be added outside of this process.