Add/Remove builder elements

Function Reference: themeblvd_add_builder_element

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

This function is one of the more complicated out of the different API functions available in the framework. It requires that you setup an array of options for your new element, as well as setup a callback function for how the element will be displayed on the frontend of your website.

Usage
themeblvd_add_builder_element( $element_id, $element_name, $query_type, $options, $function_to_display );
Parameters

[param id=”element_id” type=”string” required=”true” description=”ID of the new element.” default=””]

[param id=”element_name” type=”string” required=”true” description=”Name of the new element.” default=””]

[param id=”query_type” type=”string” required=”true” description=”This is the type of query the element requires – none (no posts are displayed), secondary (the element uses get_posts), or primary (the element uses WP_Query, query_posts, etc.). This is necessary for the layout builder to work properly because a single layout can never have two elements that both have a primary query (i.e. pagination taking place with displaying of posts).” default=””]

[param id=”options” type=”array” required=”true” description=”The array of options to be use for the element by the end-user in the layout builder.” default=””]

[param id=”function_to_display” type=”callback” required=”true” description=”The callback function to actually display element on the frontend of the website when a custom layout using it is displayed.” default=””]

Examples

Since this is one of the more complicated functions of the framework’s API, let’s setup a very simple element to add onto the Layout Builder. 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'
	)
);
themeblvd_add_builder_element( 'my_new_element', 'My New Element', 'none', $options, 'display_my_new_element' );
Note: For more information on how options work specifically, see the article, Formatting Options.

In the last parameter of the themeblvd_add_builder_element function we just used above, we set our callback function as display_my_new_element. So now we need to actually create this function. When the user adds this element to their custom layout, this is what will show up when that layout gets displayed on the frontend of the website.

In this function you need to pass in three parameters that are available for you to use:

  • $id – The unique ID assigned to this element.
  • $options – The options saved for the element.
  • $location – Where this element is set to display (“featured” or “primary”).

Depending on how complex or simple your element is, you may or may not require these three parameters; however you must pass in all three, none the less. In our example, our element is extremely simple and so we don’t actually need all three of those parameters, but we must pass them in anyway as shown below.

// Display "My New Element"
function display_my_new_element( $id, $options, $location ) {
	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.

Function Reference: themeblvd_remove_builder_element

This function will remove an element currently being used within the layout builder.

I’ve learned as I’ve created more themes based on this framework, it is a pretty daunting task to make sure every element in the layout builder is styled to look right in every theoretical situation it could get placed in. So it’s understandable that, in creating a child theme for you client, you wouldn’t necessarily need to include all of the layout builder’s element available to be used for your client.

Usage
themeblvd_remove_builder_element( $element_id );
Parameters

[param id=”element_id” type=”string” required=”true” description=”The ID for the element to be removed.” default=””]

Examples

Let’s say you don’t want the Post List Slider or the Post Grid Slider to be available for the end-user to use within the layout builder. Here’s how you could quickly get rid of them.

themeblvd_remove_builder_element( 'post_list_slider' );
themeblvd_remove_builder_element( 'post_grid_slider' );
Note: In order to remove any of the framework’s default elements, you’ll need to know the ID for the element. You can find these ID’s by viewing the article, Default Framework Elements.