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 appear as options within the "Custom element" available within the Sidebar browser.

    Use the DX8 example custom element to understand how they 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 /admin/modules
    2. Enable the DX8 example custom element
    3. Go to a page which includes the Layout canvas
    4. At the bottom of the Sidebar browser, you will see an element called Custom. Drag this on to your layout canvas
    5.  Open the settings for the Custom element
    6.  Select Example element from the Element drop-down and the field as defined by the module will appear
    7.  Fill out the form and click Save 
    8.  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 components: the form and the template. 

    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 our 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'll need to create a form definition and instead of a DX8 template, you'll 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 (this example_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 what will appear in the "Element" select list on the Custom element form. Both id and label are required. 

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

    getFields() returns an array defining the form structure. 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',
        ],
      ];
    }
    

    Available field types are: 

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

    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 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. 

    Example: 

    (
      [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 tot he 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 that (using a .twig template) can be found here:

    https://www.drupal.org/docs/8/theming/twig/create-custom-twig-templates-from-custom-module

    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