Drupal Development

Drupal 8 Visual Content Layout Module explained

Visual Content Layout is a Drupal 8 Module developed to manage text filters HTML content layout and visual elements like iconography, accordions, tabs, non-table columns, images, list, CTA’s, etc.

This module provides a visual help that enable you to create HTML and bootstrap elements via forms and sort those element dragging and dropping them. You can even insert one or more elements inside another if it's enable to do it.

You can download the module at https://www.drupal.org/project/vcl

Prepare the module for use

Once Visual Content Layout and Swaps are already installed as any other Drupa 8 Module, you need to add a new text format in “admin/config/content/formats”.
Or you can simply enable the filter in other format already created.

IMPORTANT: Make sure you select "None" on the Text editor select box.

If you do all this step correctly, when you are creating a content and you select the format you create for the VCL, you will see a button to enable the visual help.


Using the module

To use the module you can manually write the structure of every swap in the textarea by including the id of the swap and all attributes (use the examples in the tips section if you want to do this) or can enable the visual help in by clicking on the button on the top of the text area for an easy control of the elements.

Here is a visual help for every button you will see in the editor:

New Swap iconCreate a new swap element

Edit swap iconUpdate the attributes of the swap.

Duplicate Swap iconDuplicate the swap

Delete Swap iconDelete the swap (If you delete an element that contain other elements, it will be deleted too.)

Drag and drop iconMove the visual elements to organize them.


Style Options

If you experience problems with HTML or bootstrap elements output when the content is saved, you can go the  Visual Content Layout module settings located in “admin/config/vcl/vclSettings”  and disable the bootstrap library provide by the module. That way you can use your own styles inside your custom theme or module. Although it is important for you to knwo that this module output is based on boostrap visual elements.

Creating new swaps

The module Visual Content Layout works with the Swaps submodule that contains all the functionality to process all attributes and generete the output.

This submodule is divided in two important parts: the swap plugin and the form. You can create a custom module that use this two parts (swap plugin & form) to create your own specifics swaps elements


Plugin

The plugin contain all the functionality to specify the attributes for he output.
The next section will explain all the elements of the plugin and all its characteristics.  

  1. Annotations

    Annotations have specifics elements that represent the functionality of every swap.

    • Id: the swap id start with “swap” and the name or abbreviation of that swap.
    • Name: is the full name of the swap.
    • Description: a short explanation of the plugin.
    • Children: make the swap enable to contain only certain swaps. (This not negate the possibility to manually insert a swap inside other by drag and drop, but cause that only certain swaps can be displayed in the swap select form) Write the id of the swap that you like to enable to insert in this swap.
    • Container: this option enables the swap to contain other swaps. The value must be true or false.
    • Tip: here you can create an example of how to write a swap manually and what attributes have the swap.
  2. Methods

    To create a swap plugin, the module have a swap base with default methods that make all the job easier, the plugin class of the swap that you like to create needs to extend it:

    • info: this method return an array with all the attributes of the swap.
    • processCallback: this method receive by parameters an array with all the attributes ($attr) and the text that you insert in the swap ($text). Here you can call other methods to get, edit or set attributes, also you can create your own validations for some attributes.  
    • setAttrs: use this method for validate if the attributes exists or is null and set a default value. The method receive an array with the default values ($pairs) and other array with all the attributes ($attrs).
    • addClass: concatenated all attributes that represent the attributes "class". Here you can add other class by default.
    • getStyle: this method get all attributes that represent the style of the swap. You can also pass an array with others attributes for the style of the swap.
    • theme: here you receive all the attributes ($attrs) and the text ($text) and placed in the string that you create with the structure HTML.
  3. Form

    The form contains all controls that you should use to enable the user to insert the respective values for the attributes of the swap. In this form you can use the controls textfield, radio button, checkbox, textarea, select and colorpicker.

    The controls of the form are divided in two parts own and default attributes.

  4. Own Attributes 

    For this type of controls, is IMPORTANT  to use the name convention (swap_”swapID”_”controlName”) for the correct function of the visual help.

    The form are designed for enclose some controls in tabs, for this reason you need to create a unique tab container (vertical_tabs control) to contain all controls and we recommend to create a specific tab (details control) to wrap the "own attributes".     

  5. Default Attributes 

    The attributes of the default controls are managed by the SwapDefaultAttributes class, be sure to include this on the form class. The class has some methods that help you to manage controls:

    • getDefaultFormElements: receive by parameters the form and insert in it all the controls for the default attributes, if your swap don't use the default attributes can avoid this method. Remember to create the tab container for those controls.
    • getButtonsElements: this method include in the form the accept and cancel buttons. Receive by parameters the form.
    • getDefaultFormElementsValues: this method is used to get the information of the default attributes when you are creating the response. Receive by parameters an array where you store the values ($settings) the values that the user input in the form ($input) and a string with the id of the swap plugin that belongs this form (“swap_id”).
    • cancelAjaxResponse: method that create an ajax response that return to the select swap form. Use it in the method ajaxCancelSubmit that respond to the cancel button submit. 
  6. Form Returns

    There are two methods that returns information to the site:

    • ajaxSubmit: here you can use your own logic for get all the user input information in the own attributes and need to use the method getDefaultFormElementsValues to get the values in the default attributes.
    • ajaxCancelSubmit: in this method you can call cancelAjaxResponse for create the ajaxRespond and return it. If you need to do something before return the ajaxRespond can do it here.

    * Those method are required in the form.
     

PD: if need more information use the swaps_example module to guide you.