Custom Modules provide a powerful arsenal for developers to control the granularity of the modules they design as they allow the developers to create them from scratch and manage almost every aspect of it. A multitude of fields can be set ranging from simple text fields to complex fields like images, videos, URLs, CTAs and much more. Knowing about these fields and using them effectively can help developers bring out the powerful potential of custom made modules.
Hi! I am Sumeet Hande, a front-end engineer at Addend Analytics and in this blog, we will dive into some tips and tricks to effectively use logic fields in custom modules.
To create a custom module, we first navigate to the Design Manager by clicking on the Marketing Tab, hovering over Files and Templates and selecting Design Tools from the menu. Once in the Design Manager, we can click on the “File” link which is located on the left most section (The Finder). Select the New File option and from the drop down menu select custom module. Choose the appropriate settings which you want for the module, give it a name and hit create.
This opens up the module editor where on the center, the editor space gets divided into three sections namely, module.html, module.css and module.js. On the right hand side, i.e. on the Inspector section, we can manage all the fields which are present in the module code. Fields are just variables which can hold data. When you click on the “Add field” button, a dialog box pops up. Fields are categorized into three sections, Content, Logic and Selectors. Most of these fields are self-explanatory. In this demonstration, we will look closely on how we can use Logic fields. There are two logic fields, Boolean and Choice.
Boolean Logic Field
A Boolean variable or field can contain only two values ‘true’ or ‘false’. We can use a boolean field to display certain HTML markup according to requirement. Let us select the Boolean field from the drop down menu. This opens up the newly created boolean field in the Inspector where we can tweak options for it. This is what the inspector will look like,
As seen in the illustration, At the top (Boolean with a pencil icon next to it) we can give this field a name. This will only act as a label to distinguish it from other fields in the Inspector section. Notice that as you start typing in this name field for the first time, the HubL variable name just below it also changes simultaneously with whatever you type. HubSpot encourages developers to use such a convention to keep the same label name and HubL variable name to minimize confusion. Note that HubL variable names always start with a small alphabet. This HubL variable name is the name which will appear in the code and represent this variable. There are other important options which can be tweaked as well and are shown in the illustration above. Content Options help you set the default values for the variable. Editor options lets you choose whether the content editor should be allowed to change the default values of the variable or not. It also provides developers with a facility to write short notes so that content editors can understand the usage of the fields in a better manner. Display conditions lets the developers choose if they want a particular variable to be shown in the content editor or not. Repeater options, which is a newer and an advanced feature, allows the developer to choose if they want to repeat the occurrence of a particular field. You can refer to a previous blog which covers the usage of repeater options in detail.
Now let us expand the content options for the variable. As you can see, we can decide if we want this boolean to have a default value of either true or false. If we “Check by Default” this sets the value to true. If the checkbox is unchecked, the value for the variable remains false.
Now let us consider a use case where we have a HTML button. However, the editor wants the functionality to create and display this button on requirement. In such a scenario we can use this Boolean logic field. Consider this piece of code shown below,
Now, since we have checked the “Check by default” in the content options for the buttonrequired field, the field’s value is set to true and this code which is inside the if block, i.e BUTTON will be displayed on the screen as output. In an actual functioning module, this if block will have real HTML mark-up to render a button. The output is shown below,
(Default state set by developer)
(No button displayed when unchecked)
In this manner, by using the Boolean logic field we can set any on/off or display/do not display functionality as per requirement. When there are multiple choices to be made we make use of the Choice logic field.
Choice Logic Field
For use case scenarios where multiple choices have to be made, we use the choice field. Choice field allows developers to create multiple choices unlike the boolean field which can have only two choices. For instance, if you want to create a module which has multiple variants, where each variant displays the content in a different way, using the choice field is the best choice! Click on the Add field and select “Choice” from the menu. Just like boolean, we can set a label and a variable name for this field. However, the content options slightly differ and look something like this:
Here as you can see, there are labels and values. Each label has a value which is a string. There is an option to add more choices. Let’s create three more choices and give them names and labels as following,
We can also select a default choice. When the content editor first opens up the module for filling content, the default choice which we select will appear first before the content editor starts editing. A placeholder text can also be set. This text gets displayed when no choice is selected. Ensure that each label and choice is a unique value. Now after setting up the choice field, this is how we can use it in the mark-up,
In this way using HubL, we can set up an else-if ladder for choices. For the content editor, a drop down menu will appear and according to the choice made, the specific mark-up written in it’s block will be rendered on the screen. Following illustration shows the output,
In this way, we can add required logic to our modules to render HTML mark-up. Using such logic can increase the effectiveness and scope of our custom designed modules as we can provide more functionality to them.
Sumeet Hande
Front-end Engineer
Addend Analytics