Adding a custom element to the Enfold Avia Builder

In the very popular Enfold theme, the author created an easy to use layout builder called Avia Advanced Layout Builder. Because it’s so popular, I am constantly encounter it in the projects I work on for clients.

Most times I work on adding a new feature I prefer extending the builder. From a plugin or a child theme, this allows users to keep the theme up to date.

The Enfold custom element

In order to keep things simple we’re going to create a custom text element. And of course, I’m using the existing “Text block” element as reference & starting point.

Adding the new element is an easy 3-step process:

1. Copy the existing class file to your child theme ( or plugin ), in this case /wp-content/themes/enfold/config-templatebuilder/avia-shortcodes/textblock.php. Don’t forget to include it.
2. Change the name of the class if you don’t want to override the existing element.
   Before:

   class avia_sc_text extends aviaShortcodeTemplate {

   After:

   class custom_text_element extends aviaShortcodeTemplate {

3. Customize by changing the values in the function “shortcode_insert_button”. You’ll notice a few properties:

   $this->config['name']         = __('Text Block', 'avia_framework' );
   $this->config['tab']         = __('Content Elements', 'avia_framework' );
   $this->config['icon']        = AviaBuilder::$path['imagesURL']."sc-text_block.png";
   $this->config['order']       = 100;
   $this->config['target']          = 'avia-target-insert';
   $this->config['shortcode']        = 'av_textblock';
   $this->config['tinyMCE']       = array('disable' => true);
   $this->config['tooltip']       = __('Creates a simple text block', 'avia_framework' );
   $this->config['preview']      = "large";

Customizing your new component

From the properties above I think you should focus on a few:

• “name” – I think it’s obvious, this is the name of the block which is displayed in the builder
• “tab” – this is the tab of elements, by default you have 3 tabs in the builder to group similar elements. You can even create a new tab.
• “icon” – obvious, you can see they also have a nice helper function so you can check out the path at /wp-content/themes/enfold/config-templatebuilder/avia-template-builder/images for other icons available, or use custom one from your child theme/plugin.
• “order” – a number used to order the elements, you can look at the other elements to figure out where to place it. It works similarly to the WordPress custom menu item order.
• “shortcode” – the most important option which I highly encourage you to change if you don’t want to override an existing element. Use a prefix to make sure you don’t override an existing shortcode.
• “tooltip” – this is the text displayed when you hover over the element in the builder.

Adding new options

The reason you created a new element is to add custom options, right? This can be done from the “popup_elements” function which contains an array of arrays defining each field.

Listing all the available fields and their options would require a separate, long, article. I usually just go through other components and look at what fields are available and copy them over to my custom element.

Using the new options

The good news is that once you define a new element in this array it will automatically be added to the shortcode. This means that if you add, for example, a new text input for a caption, or a subtitle, you can use it directly. Take this code as example:

array(
   'name'            => esc_html__( 'Subtitle', 'm_text' ),
   'id'              => 'subtitle',
   'container_class' => 'avia-element-fullwidth',
   'std'             => esc_html__( 'What are you thinking?', 'm_text' ),
   'type'            => 'input',
)

This will create a new property, “subtitle”, in the generated shortcode, which means you can go ahead in the “shortcode_handler” function.

You can use it by calling:

$atts['subtitle'];

Use that in the generated html. That’s all!

A few tips

There are some special elements used for layouts – you’ll notice this:

array(
      "type"     => "tab_container", 'nodescription' => true
   ),
   
array(
      "type"     => "tab",
      "name"  => __("Content" , 'avia_framework'),
      'nodescription' => true
   ),

Very useful to have the elements clearly separated.

Another one I wanted to point out is the “linkpicker”. If you’re familiar with ACF, it works similarly to the “relationship” field. The tabs are also used similarly to ACF as you just list them and when a new one is added it creates a new tab.

Photo by Ant Rozetsky on Unsplash