Elements API: Add custom elements to Forge

Learn to create custom elements for the Forge page builder.
← Back to Developers

Forge is designed so that you can easily add custom elements to the page builder. This is done through WordPress filters, and the way you implement them is very similar to how WordPress shortcodes work.

Basically, if you have a code snippet that adds a custom shortcode, you already know how to create a new Forge element.

This is an example of a basic element with a single attribute. Take a moment to see how these two functions work:

function myplugin_custom_element($atts, $content = null){
    $attributes = extract(shortcode_atts(array(
    'color' => '',
    ), 
    $atts));
    
    $output = '<div class="myplugin-element" style="color:'.$color.';">'.$content.'</div>';        
    return $output;
}


add_filter('forge_elements', 'myplugin_custom_element_metadata');
function myplugin_custom_element_metadata($data){
    $data['myplugin-element'] = array(
    'title' => __('My Element', 'myplugin'),
    'description' => __('Element description', 'myplugin'),
    'featured' => 30,
    'group' => 'layout',
    'callback' => 'myplugin_custom_element',
    'fields' => array(
        array(
        'name' => 'color',
        'label' => __('Color', 'myplugin'),
        'description' => __('Element Color', 'myplugin'),
        'type' => 'text',
        'default' => '#666666',
        'live' => array(
            'selector' => '.myplugin-element',
            'property' => 'css',
            'attribute' => 'color',
        )),
    ));
    
    return $data;
}

The basic premise is that you need to create two PHP functions: one to define the output of the element (which uses the same overall structure as shortcodes), and another to declare it as a page builder element. This second function will tell Forge how the element should behave, what fields it has, and so on.

Element Configuration

Not every element behaves the same. There are special elements that can be nested, while others might be restricted to only having specific parents.

Forge provides a large amount of settings so that you can configure the behavior of each element to your liking. The page builder takes into consideration that complex elements– such as sliders– have special needs.

Here you can find an example of a custom implementation:

$data['myplugin-element'] = array(
'title' => __('My Element', 'myplugin'),
'description' => __('Element description', 'myplugin'),
'featured' => 30,
'group' => 'layout',
'callback' => 'myplugin_custom_element',
'hierarchical' => true,
'parent' => 'row',
'children' => array('column', 'column'),
'children_draggable' => true,
'classes' => 'forge-col',
'fields' => array(
    array(
    'name' => 'color',
    'label' => __('Color', 'myplugin'),
    'description' => __('Element Color', 'myplugin'),
    'type' => 'text',
    'default' => '#666666',
    'live' => array(
        'selector' => '.myplugin-element',
        'property' => 'css',
        'attribute' => 'color',
    )),
));

Name of the Element: This should be declared as the key of the array. This name must be unique among the collection of elements in the builder, so you should add your own textdomain as a prefix.

title: Defines the title of the element in the collection. This affects how the element can be searched for, so try to be specific.

description: Defines the small description underneath the title. Keep it short, descriptive, and sweet.

featured: Elements can be moved to the top and marked as featured. This property takes a number that tells the builder in which order the featured elements should appear. A lower number means appearing higher in the list.

callback: The name of your element function. When displaying this element, Forge will call this function to render its markup.

hierarchical: Defines whether this element can have other elements inside of it. One example of hierarchical element is the Row. When an element is declared as hierarchical, the second argument of the shortcode function will hold all its contents. You can then organize your markup however you need, but remember to also include the $content variable to display children elements.

parent: Indicates that the element is restricted to a specific element as its parent. This will hide the element from the collection, since it would not be possible to drag such an element around. This option is useful for creating complex elements such as slideshows, which have multiple children (slides) in an organized manner.

children: Indicates a series of elements that the element should start with. This should be an array of all the element types that you want to automatically add upon creating. One example of this are Rows– they have two child columns right at the start. Keep in mind that this property only creates the elements in one go, and does not lock them to their parent.

fields: An array of all the settings you want the element to have. More on that below.

Element fields

In addition to its general configuration, each element in Forge has a number of settings fields. These fields are what the user will be able to use to change the element’s attributes in the interface. To generate these, you will need to populate the fields property with any number of field. Here you can see the basic structure for an individual field:

'name' => 'color',
'label' => __('Color', 'myplugin'),
'description' => __('Element Color', 'myplugin'),
'type' => 'text',
'default' => '#666666',
'placeholder' => 'string',
'choices' => array(),
'live' => array(
    'selector' => '.myplugin-element',
    'property' => 'css',
    'attribute' => 'color',
)),

Each one of these field arrays is key-less, meaning you don’t need to assign an array key.

name: The identifying name of the field. This value must be unique within the entire list of fields, and is also the name of the attribute that the element will have.

title: The title of the field that will appear in the settings panel when editing an element. It is optional.

description: A descriptive text that will be shown as a tooltip in the settings panel. You should use this to explain how the field works, as well as any considerations. This is optional.

type: the type of the field, which influences the kind of additional data you need to specify. By default, it will be a text field.

default: The starting value assigned to the element when it is initially created. Useful for setting sane defaults.

placeholder: A placeholder text for text-related fields. Useful for indicating formats.

Field types

Since each element field is unique in its own way, Forge provides you with a large list of field types that you can use. For example, the most basic one is the text field for simple strings, while a more advanced one is the border field for defining CSS-syntax borders.

Here is a list of all the possible field types available. It is up to you which one to use, depending on how you want the user to interact with your custom element:

Under construction.

Live editing

An important part of Forge is the ability to display changes immediately while editing an element, without saving. This functionality is called live editing, and is highly recommended for any custom element.

With live editing, the page builder will display changes as the user edits the settings of an element, providing an accurate, real-time preview of the element.

Live editing can be implemented by following the instructions here:

Under construction.

 

Share on FacebookShare on Google+Tweet about this on TwitterShare on LinkedInShare on TumblrBuffer this pageEmail this to someone

Error: Please enter a valid email address

Error: Invalid email

Error: Please enter your first name

Error: Please enter your last name

Error: Please enter a username

Error: Please enter a password

Error: Please confirm your password

Error: Password and password confirmation do not match