The Basics of Custom Modules
This walkthrough will cover creating a custom module through the HubSpot design manager, and not the CLI option.
Create a New Module
Basic Module Features
Module admin elements
The area to the right of the window has the administrative elements of your module.
The top section is where you name the module The file name is the actual name of the module in the HubSpot file area. If you change the name, you may need to update instances of the module used in your templates. The label is what a page editor will see when selecting the modules for the page. This may be changed anytime and not damage any module paths in templates. Clicking the icon will also allow you to change the icon the page editors will see. You may browse from hundreds of icons HubSpot has included, or upload your own SVG file. This can be useful to more easily find your module at a glance when it's in a list of all of the other modules.
The fields section is probably the most used area of your module. Fields are data elements you are giving the page editor to change when they add your module to a page. HubSpot now has dozens of different field elements available for you, each with their own unique features and elements. I’ll cover a few of the most common/useful ones.
A few elements that are common to all fields.
- Name: the label the page editor sees when entering content into your module. This should be as descriptive as possible, but it is just a label.
- HubL variable name: the HubL variable you will use to refer to this object in your module.html area. This will not be seen by the page editor, and must be unique to your module. It will be defaulted based on your field’s name, but can be changed. Keep in mind if this changes, any references to the name in your module will also need to be updated.
Content Options will have the content fields unique to the field type available for data. Most of these are related to the default values you want populated in the module when a new instance is created. However, there are some additional fields that aren’t directly displayed but allow you to manage the options the page editor has when using the module. This will range from the default values you may want to pre-populate in your module, to image controls, to restrictions placed on the page editor when entering data into your field.
Editor Options will allow you to put some limits on and give page editors some additional information when they are dealing with a specific module field.
- Make this field required will require a page editor to have a value for this field.
- Prevent editing in content editors will lock this field for the page editors; your default value will be used.
- Tooltip help text will be a popup next to the field’s label for the page editor.
- Inline help text will appear below the field’s label for the page editor.
Display Conditions will allow you to hide this field from page editors based on other field values in the module. For instance, if you want a text field and its label to be hidden from the page editor if they haven't entered a value in another field, the conditions will allow you to manage that restriction.
Repeater Conditions allow you to specify that the field should have multiple instances in the module. We will cover this in a separate blog post in the future.
Common Field Types
- Rich Text: The standard HubSpot rich text editor. Gives the page editor the full WYSIWYG toolset including fonts/styles/colors, links, images, etc.
- Text: A single line of text. Useful if you want to give a user a header field or hyperlink text and not allow them access to style it in the rich text editor.
- Link: A variable that will contain a link to something. You are able to restrict the page editor to specific types of links (internal pages, external links, files, etc.)
- Image: An image in the HubSpot file library.
- Icon: A FontAwesome icon; sometimes it can be easier for a page editor to pick an icon rather than an image.
- CTA: Select a HubSpot call to action.
- Form: Select a HubSpot form. Also allows the page editor to override the thank you message or page.
- Blog: Select a blog in your HubSpot instance.
- HubDB table and HubDB row: Select a HubDB table or a specific row in a HubDB table.
- Boolean/Choice: Give a page editor a boolean checkbox or a limited set of options. The can be directly output to the screen, but are usually used to manage other fields in your module.
Each field has an actions menu for quick access to some key field elements. The two most critical elements are the copy features.
The Copy Snippet will put the HubSpot default HubL code to display this field on your clipboard. You may then paste this code into the module.html area to display the field. This is the best way to display some elements, such as the Rich Text, Fields and Image field types, as it will create default code for some of the field’s critical elements if the object is a complex HubL dictionary (has sub-elements under the parent variable.) Sometimes, the HubL code will have multiple lines with it to ensure all of the field elements are covered (such as image sizing or adding support code for the link element if an email option is specified. But, this default HubL code can be modified at your discretion.
The Copy Value Only will only grab the variable name for the clipboard. With most elements, it’s not enough to display this (if the field consists of a HubL dictionary with multiple sub-elements.) But, you can output the field variable to see all of it’s dictionary elements (especially when using the pprint “pretty print” filter on the variable. Or, you can use the variable name in any HubL logic code you have (