Version:
Cohesiondx.com

    How to create a custom element

    If you are a developer you can create your own elements. Custom elements can have a form and output defined by the developer. Once created, they will be available as elements under the "Custom elements" section within the Sidebar browser.

    Use the "DX8 example custom element" to understand how custom elements are used and then follow the guide below which walks through the process of creating your own Custom element.

    Use the "DX8 example custom element"

    The "DX8 example custom element" module is an example of how a developer can create a custom element.  To enable it:

    1. Navigate to Extend and search for "DX8 example custom element"
    2. Enable the DX8 example custom element module
    3. Navigate to a page which includes the Layout canvas
    4. Open the sidebar browser, and scroll down to the Custom elements section. Drag "Example element" on to your layout canvas
    5. Double check to edit the Example element
    6. Fill out the form and click Save
    7. Save the template/page and view the output.

    Creating your own element

    The steps below explain how you can take the example module and create your own element that integrates seamlessly with DX8.

    Each element inside DX8 has two parts:

    • the form - this is the element form which contains the defined fields
    • the template - the rendered output of the custom element.

    Data the user or site builder adds to the form is fed to a twig template to render the output. For internal DX8 elements, these templates exist on the DX8 API and are combined to make a single aggregated template that is used to drive the output of entire nodes, pages, views, etc.

    Your custom element is a bit different as it will be rendered at runtime instead of aggregated on the API.

    You will need to create a form definition and instead of a DX8 template, you will create a render function that will render the output of the form at runtime. That render function can use a .twig template file to render the output but this is not a requirement. As an example, DX8 example custom element module uses a local .twig template file for the output.

    1. Creating your form. 

    DX8 uses a custom form definition format that is not related to the Drupal form system. You have several field types you can use and these will be displayed to the site builder in the "Settings" tab of the element.

    Create a new module and add a class under the CustomElement plugin namespace, e.g. [module_path]/src/Plugin/CustomElement/Generic.php

    The plugin class must extend Drupal\cohesion_elements\CustomElementPluginBase and be annotated with CustomElement, for example:

    namespace Drupal\module_name\Plugin\CustomElement;
     
    use Drupal\cohesion_elements\CustomElementPluginBase;
      
    /**
     * Generic HTML element plugin for DX8.
     *
     * @CustomElement(
     *   id = "generic_html_tag",
     *   label = @Translation("Generic HTML tag with text content")
     * )
     */
    class Generic extends CustomElementPluginBase {
    

    The label key is the name of your custom element, this is what will appear within the sidebar browser, both id and label are required.

    The class must implement both getFields() and render() methods. render() is discussed below in step #2.

    getFields() function returns an array defining the form structure of the custom element. Each entry should be a keyed array in the following format:

    public function getFields() {
      return [
        'tag' => [
          'htmlClass' => 'col-xs-12',
          'type' => 'select',
          'title' => 'HTML tag',
          'nullOption' => false,
          'options' => [
            'p' => 'p',
            'span' => 'span',
            'div' => 'div',
          ]
        ],
        'text' => [
          'htmlClass' => 'col-xs-12',
          'title' => 'Text content',
          'type' => 'textfield',
          'placeholder' => 'e.g. DX8 is great',
        ],
      ];
    }
    

    The available field types that can be used in a custom element are:

    • textfield
    • select
    • checkbox
    • image
    • textarea
    • wysiwyg

    Below is an example of how to use each type of field within the getFields() function:

    public function getFields() {
      return [
        // This is an example text field.
        'mytextfield' => [
          'htmlClass' => 'col-xs-12',
          'title' => 'Text content',
          'type' => 'textfield',
          'placeholder' => 'e.g. DX8 is great',
        ],
        // This is an example select field.
        'myselectfield' => [
          'htmlClass' => 'col-xs-12',
          'type' => 'select',
          'title' => 'HTML tag',
          'nullOption' => false,
          'options' => [
            'p' => 'p',
            'span' => 'span',
            'div' => 'div',
          ]
        ],
        // This is an example checkbox field.
        'mycheckboxfield' => [
          'htmlClass' => 'col-xs-6',
          'type' => 'checkbox',
          'title' => 'Title of my checkbox field',
          // These fields are specific to this form field type.
          'notitle' => false,
          'defaultValue' => true,
        ],
        // This is an example image field.
        'myimagefield' => [
          'htmlClass' => 'col-xs-12',
           'title' => 'Title of my image field',
          'type' => 'image',
          // This field is specific to this form field type.
          'buttonText' => 'Some button',
        ],
        // This is an example text area field.
        'mytextareafield' => [
          'htmlClass' => 'col-xs-12',
          'type' => 'textarea',
           'title' => 'Title of my text area field.',
        ],
        // This is an example WYSIWYG field.
        'mywysiwygfield' => [
          'htmlClass' => 'col-xs-12',
          'type' => 'wysiwyg',
          'title' => 'Title of my WYSIWYG field.',
          'defaultValue' => [
                'text' => '<p>This is some default content.</p>',
                'textFormat' => 'cohesion'
            ]
         ],
       ];
    }
    

    Depending on the type of field you select, you will be required to add additional fields.

    See the examples in src/Plugin/CustomElement/Example.php for further details.

    2. Creating your render method. 

    Your render method is passed three parameters and should return a render array: 

     public function render($settings, $markup, $class) {
      return [
        '#theme' => 'generic_element',
        '#settings' => $settings,
        '#markup' => $markup,
        '#class' => $class,
      ];
    }
    

    $settings is an array containing the form data input by the user/site builder along with the element name.

    Note, the element name is provided as a convenience in case you want to use the same render function for multiple elements.

     (  
       "element" => "module_example_1",
       "mycheckboxfield" => true,
       "myothercheckboxfield" => true,
       "mytextfield" => "Test 'data'.",
       "myselectfield" => "option2",
       "mytextareafield" => "Test data 2.",
       "mywysiwygfield"= > "<p>Test data 3.</p>n"
    )
    

    $markup is an array containing data added to the "Markup" tab within the custom element
    Here is an example of that markup data:

    (
      [attributes] => Array
        (
          [0] => Array
            (
              [attribute] => "data-something"
              [value] => "somevalue"
            )
        )
      [prefix] => "someprefix"
      [suffix] => "somesuffix"
    )
    

    $class is an string containing the class that targets your element. Anything added to the style stab will be build into the DX8 stylesheets and available under this class name.

    It has the format: 'coh-ce-xxxxxxx' with NO preceding dot/period character.

    Your function should return a renderable array. An example of this (using a .twig template) can be found on the Drupal.org theming documentation.

    The DX8 Example Custom element module is a good starting point to look at when creating your own custom element. Another example of a custom element is the AddToAny DX8 integration module which is available on Drupal.org. 

    Cohesion DX8 Help center

    Launch our Help center to raise a support ticket or search our knowledge base of common questions and answers.

    DX8 knowledge base icon

    Knowledge base

    Get instant answers to common questions. Available online 24/7.

    Find answers

    Raise a ticket icon

    Raise a support ticket

    Log in to the Help center to raise an issue. Available Monday - Friday, 09:00 - 17:00 GMT.

    Raise ticket