CMS Developer Tools

Table of contents
Close

Local Development Tooling [BETA]: Develop Modules Locally

⚠️ This is a beta pre-release not intended for mission-critical usage. During the beta period expect lots of changes to commands, configuration structure, and capabilities. For support with this tooling, please join the #local-dev room of the Designers and Developers Slack. Please refer to our developer beta terms. ⚠️

This outlines the available attributes and field markup for developing modules locally.  For all available commands, see the Local Development Reference. For a walkthrough of these new tools, see the Getting Started Guide.

ℹ️ Did you know you can use free CMS developer sandbox accounts as development environments? Create one now by clicking "Create an Account", selecting your user, and opting to "Create a new, fresh account" here.  ℹ️

Local Module File Structure

Local modules are formatted in a series of files, each specifying various components of a module. These files are stored in a .module directory. You can scaffold out an entire module using the create command

For email compatible modules, module.css and module.js will be disabled.

File Name Contents
module.html The HTML and HubL of your module.
module.css The CSS of your module.
module.js The JavaScript of your module.
meta.json (required) A JSON object which contains meta information about the module. 
fields.json (required) A JSON object which contains the module fields. 
_locales A folder containing language local subfolders, each with a messages.json file, containing module field translations.

meta.json

The meta.json file contains information about your module's placement, attached assets, and available functionality.

Name Data type Description Default
css_assets list

 Ordered list of CSS asset objects that are used in the module and will be copied along with the module when distributed through the marketplace.

null
external_js list

A list of external JS files added to the module.

null
global boolean

Boolean; when set to true, indicates that this module is categorized as a global module in the design tools.

false
host_template_types list

A list of host template types. Defaults to "ANY", meaning that the module can be used for emails, blogs, and pages.

[ "ANY", "PAGE", "BLOG_POST", "BLOG_LISTING", "EMAIL" ]
js_assets list

Ordered list of JavaScript asset objects be copied along with the module when distributed through the marketplace.

null
other_assets list

Similar to js and css assets. Used to include file manager assets with a module for distribution.

null
smart_type string

String; determines if the module has been created with 'smart' capability. Can only be set to "NOT_SMART" in a non-global module.

"NOT_SMART"
tags list

A list of tags used to categorize modules within the template editor and the marketplace.

null
is_available_for_new_content boolean

The value for the toggle in the top right corner of the module editor in HubSpot. Determines if the module can be used in content.

false

fields.json

Module fields, which generate editable fields for content creators within the content editor, are set within the fields.json file of a module. 

Attributes for all module fields

The following attributes are available on all module fields.

Attribute name Data type Description Default value
type string The type of field, in code name. See field types below for documentation on all field types.  
id string Unique id for a field. This is generated by HubSpot. Not required when developing locally.
label string Label of the field. This will appear in the content editors. Rich text field, Date field, etc.
locked boolean Determines if the field is editable in the content editor. If "true", the field will not appear in the content editor. false
helptext string Text that will appear in the editor to assist the content creator. none
name string Variable name for the field value. Accessible in your HTML, CSS, and Javascript sections using module.name. richtext_field, date_field, etc.
required boolean Determines if the field can be left blank in the editor. If true, content will not be allowed to publish without filling out this field. false
visibility array Determines the display conditions for a field.  
default varies The default value of a field. See fields schema below.  

Using Repeaters

To use Repeater Options on a locally developed field, include the occurrence attribute.

Attribute name Data type Description Default Value
min number

Minimum number of occurrences for a repeated field.

null
max number

Maximum number of occurrences for a repeated field.

null
sorting_label_field string

In a field group with repeater options, this determines the field value that displays in the editor.

null
default number

The default number of times a field appears when first adding the module to content.

null

Below is an example of the occurrence attribute.

 "occurrence" : {
    "min" : 1,
    "max" : 5,
    "sorting_label_field" : null,
    "default" : null
  }

Field Types

Date

"date"

Select a calendar date.


{
     "name" : "date_field",
     "label" : "Date field",
     "help_text" : "Select a date.",
     "sortable" : false,
     "required" : false,
     "locked" : false,
     "step" : 1,
     "type" : "date",
     "default" : 1566360000000
}

Date and Time

"datetime"

Select a calendar date and time.

Attribute name Data type Description Default value
step number

Default interval for toggling time forward and backward in minutes.

30

{

       "name" : "datetime_field",

       "label" : "Date and time field",

       "sortable" : false,

       "required" : false,

       "locked" : false,

       "step" : 30,

       "type" : "datetime",

       "default" : 1566360000000

}

Link

"link"

Generates a link in an <a> tag.

Attribute name Data type Description Default value
supported_types list

Determines the type of link that can be added from the content editor. By default, all types are enabled- remove a type from the list to disable it.

"EXTERNAL", "CONTENT", "FILE", "EMAIL_ADDRESS", "BLOG"

{

       "name" : "link_field",

       "label" : "Link field",

       "sortable" : false,

       "required" : false,

       "locked" : false,

       "supported_types" : [ "EXTERNAL", "CONTENT", "FILE", "EMAIL_ADDRESS", "BLOG" ],

       "type" : "link",

       "default" : {

            "url" : {

                 "type" : "EXTERNAL",

                 "href" : "www.hubspot.com",

                 "content_id" : null

             },

            "open_in_new_tab" : false,

            "no_follow" : false

       }


}

Number

"number"

Adds the ability to select a number.

Attribute name Data type Description Default value
min number

Sets the minimum value for the field.

none
max number

Sets the maximum value for the field.

none
default number

Sets the default value for the field.

none
step number

Determines the interval the value is changed when clicking the up and down buttons.

none

{

     "name" : "number_field",

     "label" : "Number field",

     "sortable" : false,

     "required" : false,

     "locked" : false,

     "display" : "text",

     "min" : 1,

     "max" : 5,

     "step" : 1,

     "type" : "number",

     "default" : 1

}

Rich text

"richtext"

A rich text WYSIWYG area. Unlike the text field, the rich text field can contain a variety of text styles, and the options to insert various forms of content (CTAs, images, videos, etc).


{
      "default": "<h1>Hello, world!</h1>",
     "label": "Rich text field",
     "locked": false,
     "name": "text",
     "required": false,
     "sortable": false,
     "type": "richtext",
}

Simple Menu

"simplemenu"

Allows creating a menu from scratch within the content editor.


{

     "name" : "simplemenu_field",

     "label" : "Simple menu field",

     "sortable" : false,

     "required" : false,

     "locked" : false,

     "type" : "simplemenu",

     "default" : [ {

       "isPublished" : true,

       "pageLinkId" : 123456789,

       "pageLinkName" : "My page",

       "isDeleted" : false,

       "categoryId" : 1,

       "subCategory" : "site_page",

       "contentType" : "site_page",

       "state" : "PUBLISHED_OR_SCHEDULED",

       "linkLabel" : "This is a page",

       "linkUrl" : null,

       "linkParams" : null,

       "linkTarget" : null,

       "type" : "PAGE_LINK",

       "children" : [ ]

     } ]

}

Text

"text"

A simple text input.

Attribute name Data type Description Default value
placeholder string

Text that will appear in this field in the editor for your content creator, but not appear printed on the page.

none
allow_new_line boolean

Determines if a new line can be added in the text field input.

false
show_emoji_picker boolean

Determines if an emoji picker appears in the rich text toolbar in-app.

false

}
       "name" : "text_field",
      "label" : "Text field",
      "sortable" : false,
      "required" : false,
      "locked" : false,
      "validation_regex" : "",
      "placeholder" : "isn't it neat",
      "allow_new_line" : false,
      "show_emoji_picker" : false,
      "type" : "text",
      "default" : "This is default text"
}

URL

"url"

Generates a complete URL, outside of an <a> tag.

Attribute name Data type Description Default value
supported_types list

Determines the type of link that can be added from the content editor. By default, all types are enabled- remove a type from the list to disable it.

"EXTERNAL", "CONTENT", "FILE", "EMAIL_ADDRESS", "BLOG"

{

     "name" : "url_field",

     "label" : "URL field",

     "sortable" : false,

     "required" : false,

     "locked" : false,

     "supported_types" : [ "EXTERNAL", "CONTENT", "FILE", "EMAIL_ADDRESS", "BLOG" ],

     "type" : "url",

     "default" : {

       "type" : "CONTENT",

       "href" : null,

       "content_id" : 123456789

     }

}

Boolean

"boolean"

A true or false toggle. The default for the boolean field is false.


{
     "name" : "boolean_field",
     "label" : "Boolean field",
     "sortable" : false,
     "required" : false,
     "locked" : false,
     "type" : "boolean",
     "default" : false
}

Choice

"choice"

A field where the content editor may select one of a series of options.

Attribute name Data type Description Default value
display string

May be "select" or "radio". Determines how the choice field appears in the module editor. "Select" will be a dropdown menu, while "radio" is a radio select option.

select
choices list

Series of values and labels that populate the field options. The label may contain HTML markup.

[ [ "value 1", "Label 1" ], [ "value 2", "Label 2" ] ]

{
      "name" : "choice_field",
     "label" : "Choice field",
     "sortable" : false,
     "required" : false,
     "locked" : false,
     "display" : "select",
     "choices" : [ [ "value 1", "Label 1" ], [ "value 2", "Label 2" ] ],
     "type" : "choice",
     "default" : "value 2"
}

Blog

"blog"

Select a blog in your account. This field generates a blog id.


{
      "name" : "blog_field",
     "label" : "Blog field",
     "sortable" : false,
     "required" : false,
     "locked" : false,
     "type" : "blog",
     "default" : 1234567890
}

Color

"color"

Select a color. This returns a hex code and an opacity value.


{
      "name" : "color_field",
     "label" : "Color field",
     "sortable" : false,
     "required" : false,
     "locked" : false,
     "type" : "color",
     "default" : {
        "color" : "#ffffff",
        "opacity" : 100
     }
}

CTA

"cta"

Select a call to action. Returns a call to action guid.


{
      "name" : "cta_field",
     "label" : "CTA field",
     "sortable" : false,
     "required" : false,
     "locked" : false,
     "type" : "cta",
     "default" : "fb9c0055-6beb-489d-8dda-3e1222458750"
}

Email Address

"email"

Select the email address of a user in your account.


{
     "name" : "email_field",
     "label" : "Email address field",
     "sortable" : false,
     "required" : false,
     "locked" : false,
     "type" : "email",
     "default" : [ "develop@hubspot.com", "design@hubspot.com" ]
}

File

"file"

Select a file from the HubSpot File Manager.

Attribute name Data type Description Default value
picker string

The type of file to select. Options are "file", "image",  or "document".

file

{
     "picker" : "file",
     "name" : "file_field",
     "label" : "File field",
     "sortable" : false,
     "required" : false,
     "locked" : false,
     "type" : "file",
     "default" : "https://cdn2.hubspot.net/hubfs/file.pdf"
}

Followup Email

"followupemail"

Select a followup email from your portal. This field is particularly helpful for rendering a full form in a custom module.


{
     "name" : "followupemail_field",
     "label" : "Followup email field",
     "sortable" : false,
     "required" : false,
     "locked" : false,
     "type" : "followupemail",
     "default" : 1234567890
}

Font

font

Select a google font for use in your module.


{
     "name" : "font_field",
     "label" : "Font field",
     "sortable" : false,
     "required" : false,
     "locked" : false,
     "load_external_fonts" : true,
     "type" : "font",
     "default" : {
        "size" : 12,
        "size_unit" : "px",
        "color" : "#000",
        "styles" :{
            "text-decoration" : "underline"
        },
       "font" : "Alegreya",
       "fallback" : "serif",
       "variant" : "regular",
       "font_set" : "GOOGLE"
     }
}

Form

"form"

Select a form in your HubSpot account.


{
     "name" : "form_field",
     "label" : "Form field",
     "sortable" : false,
     "required" : false,
     "locked" : false,
     "type" : "form",
     "default" : {
        "form_id" : "9aa2e5f3-a46d-4774-897e-0bc37478521c",
        "response_type" : "redirect",
        "redirect_url" : "http://www.hubspot.com",
        "redirect_id" : null,
        "gotowebinar_webinar_key" : null,
        "form_type" : "HUBSPOT"
     }
}

HubDB Table

"hubdbtable"

Select a HubDB table in your HubSpot account. Returns the table id.


[
{
"default": "<h1>Hello, world!</h1>",
"label": "Rich text field",
"locked": false,
"name": "text",
"required": false,
"sortable": false,
"type": "richtext",
"validation_regex": ""
}
]

Icon

"icon"

Select a FontAwesome icon.


{
     "name" : "icon_field",
     "label" : "Icon field",
     "sortable" : false,
     "required" : false,
     "locked" : false,
     "type" : "icon",
     "default" : {
        "name" : "align-center",
        "unicode" : "f037",
        "type" : "SOLID"
     }
}

Image

"image"

Select an image from the HubSpot File Manager.

Attribute name Data type Description Default value
responsive boolean

Determines if the options for responsive sizing appear in the content editor.

false
resizable boolean

Determines if size controls for the image appear in the HubSpot editor.

true

{
     "name" : "image_field",
     "label" : "Image field",
     "sortable" : false,
     "required" : false,
     "locked" : false,
     "responsive" : false,
     "resizable" : true,
     "type" : "image",
     "default" : {
        "src" : "https://cdn2.hubspot.net/hubfs/image.jpeg",
        "alt" : "an_image",
        "width" : 100,
        "height" : 100
     }
}

Logo

"logo"

Renders the logo from your Settings. You can also override the default logo in each instance of the field.


{
     "name" : "logo_field",
     "label" : "Logo field",
     "sortable" : false,
     "required" : false,
     "locked" : false,
     "resizable" : true,
     "type" : "logo",
     "default" : {
        "override_inherited_src" : true,
        "src" : "https://cdn2.hubspot.net/hubfs/logo.png",
        "alt" : "best_logo_ever",
        "width" : 100,
        "height" : 100
}
}

Meeting

"meeting"

Select a HubSpot meetings link. To add this field to a module, you must have sales permissions in your HubSpot account.


{
     "name" : "meeting_field",
     "label" : "Meeting field",
     "sortable" : false,
     "required" : false,
     "locked" : false,
     "type" : "meeting",
     "default" : "https://app.hubspot.com/meetings/developers-r-kewl"
}

Menu

"menu"

Select a menu built in Settings > Website > Navigation.


{
     "name" : "menu_field",
     "label" : "Menu field",
     "sortable" : false,
     "required" : false,
     "locked" : false,
     "type" : "menu",
     "default" : 123456789
}

Page

"page"

Select a website or landing page in your HubSpot account.


{
     "name" : "page_field",
     "label" : "Page field",
     "sortable" : false,
     "required" : false,
     "locked" : false,
     "type" : "page",
     "default" : 1234567890
}

Salesforce Campaign

"salesforcecampaign"

Select a salesforce campaign. This field can be used to duplicate the functionality of the default form module. This field will only be available if your HubSpot account has a Salesforce Integration.


{
     "name" : "salesforcecampaign_field",
     "label" : "Salesforce campaign field",
     "sortable" : false,
     "required" : false,
     "locked" : false,
     "type" : "salesforcecampaign",
     "default" : "7016A0000005S0tQAE"
}

Tag

"tag"

Select a HubSpot blog tag.

Attribute name Data type Description Default value
tag_value string

Select a value return type for the tag selector. Options are "ID" or "Name".

Name

{
     "name" : "tag_field",
     "label" : "Tag field",
     "sortable" : false,
     "required" : false,
     "locked" : false,
     "tag_value" : "ID",
     "type" : "tag",
     "default" : 1234567890
}

For more examples of local module development, check out the HubSpot CMS Boilerplate modules here.