Getting started with modules

In this tutorial, you'll use the HubSpot CMS boilerplate theme to learn how to create a module and walk through how you can use it in templates and pages as part of a theme. By the end of the tutorial, you'll have created a testimonial module that includes an image field, a text field, and a rich text field. 

If you want to jump ahead, you can preview the finished project files. Because the CMS boilerplate theme's code may change over time, only the most critical files that developers will need to create or edit during the tutorial are included. These files include:

1. Testimonial.module: the folder containing the files that make up the custom module you'll build as part of the tutorial.
2. homepage.html: the template that you'll be editing to include our custom module.
3. images: the folder containing the profile pictures you'll use in the Testimonial module. 

Before getting started with this tutorial:

• Set up a HubSpot CMS Developer Sandbox. You can use your existing account instead, but the sandbox will allow you to develop without impacting assets in your main account.
• Install Node.js, which enables HubSpot's local development tools. Versions 10 or higher are supported.

During this tutorial, you'll be developing the module locally. To interact with HubSpot in your command line interface, you'll need to install the HubSpot CLI and configure it to access your account.

• In the terminal, run npm install -g @hubspot/cli to install the CLI globally. To install the CLI only in your current directory instead, run npm install @hubspot/cli.
• In the directory where you'll be storing your theme files, run hs init.
• Press Enter to open the personal access key page in your browser.
• Select the account that you want to deploy to, then click Continue with this account. You’ll then be redirected to the personal access key page of the account.
• Next to Personal Access Key, click Show to reveal your key. Then click Copy to copy it to your clipboard.
• Paste the copied key into the terminal, then press Enter.
• Enter a unique name for the account. This name will only be seen and used by you when running commands. Then, press Enter.To connect the local development tools to your account:

You'll then see a success message confirming that the hubspot.config.yml file was created.

• In the terminal, run hs create website-theme my-theme. A theme folder will then be created in your working directory containing the boilerplate assets.
• Upload the files to your account by running hs upload <src> <destination>. 
  • <src> is the path to your local files relative to your current working directory
  • <destination> is the destination path in your HubSpot account. The destination can be a new folder.
  • For example, hs upload my-theme my-new-theme would upload the my-theme folder from your machine to a my-new-theme folder in HubSpot.

• At any time, you can manually upload saved changes to HubSpot by running hs upload. But you can also run hs watch <src> <destination> to automatically upload local changes on save. To stop watching, you can press Control-C.

• Log in to your HubSpot account, then navigate to the design manager by navigating to Marketing > Files and Templates > Design Tools.
• In the left sidebar of the design manager, open the theme folder that you just uploaded. 
• In the theme folder, open the modules folder.
• In the upper left, click File > New file to create a new module in this folder.
• In the dialog box, click the dropdown menu, then select Module, then click Next.
  
• Select the Pages checkbox to make the module available for website and landing pages.
• Enter a file name for the module, then click Create.

Next, you'll add three fields to the module:

• A text field to store the name of the customer giving the testimonial.
• An image field that will store the customer's profile picture.
• A rich text field that will store the customer's testimonial.

To add these fields:

• In the right sidebar, click the Add field dropdown menu, then select Text.
  
• Next to the pencil icon in the upper right, n the text field, enter Customer Name. You'll then see the HubL variable name change to customer_name.
• Set the Default text to Sally.

• In the right sidebar, click the breadcrumb icon to return to the main module menu.
• Add another field using the same method, this time selecting the Image field type.
• Label the image field Profile Picture, then set the HubL variable name to profile_pic.
• Under Default image, select the profile picture provided for sally in the images folder of the completed project files.
• Set the Alt text to Customer Profile Picture.

• Add another field using the same method, this time selecting the Rich text field type.
• Label the rich text field Testimonial.
• Click the Default rich text box, then enter "I've had nothing but wonderful experiences with this company."

So far, you've added data into several module fields. Even though these fields have data, the module itself won't display the data yet, because you haven't added the fields to the module's HTML. This is reflected in the module.html field being empty at this point. 

To add HubL to the module, copy and paste the following code into the module.html file:

In the above code, dot notation is used to access various field data:

• The module variable represents the module itself, while the customer_name field represents the variable name that you assigned to the text field in the previous step. Put together, module.customer_name looks up the customer name text within the module.
• The module.profile_pic.src value accesses the module's profile_pic field and look up the src value, which is the image's URL. However, even though the HubL variable contains the image URL, you still need to place it within an image HTML tag to render it on the page.

With the HubL added to your module, you can click Preview in the upper right to see what the module looks like so far.

Finally, in the upper right of the design manager, click Publish changes. 

With your module now built out, you'll now pull it down to your local environment to copy it to your theme folder. It's important to note that you can build modules from scratch locally, too, but for the purposes of this tutorial it's heplful to see the HubSpot process along with the local process. 

To pull your module to your local environment:

• In the terminal, run the following command: hs fetch <hs_src> <destination>:
  • <hs_src> represents the module's filepath in HubSpot. To get the filepath, you can right-click the module in the left sidebar in the design manager, then select Copy path. 
    
  • <destination> represents the path to the local directory where your theme lives. If omitted, the command will default to the current working directory.

For the purposes of this tutorial, you should pull down the module to the “src/modules” folder in the “my-theme” directory you created in Step 1. Learn more about the fetch command.

In your preferred code editor, navigate to the module folder you’ve just pulled down from your HubSpot account. Within your module folder, you will see five different files:

You can find more detailed information in our documentation about the module file structure, especially concerning the fields.json and meta.json files. In this tutorial, we’ll focus on the fields.json, module.css, and module.html files and how they are generated by, downloaded from, and uploaded to the module editor in the Design Manager.

Open the module's fields.json file. Aside from some of the id numbers, the src attribute of the image field, and potentially the order of fields, the file should contain a JSON object similar to the following:

The values for the following fields will match the values you added in step 3:

• name: the name of the field.
• label: the field's label.
• default: the field's default value.  

To illustrate the relationship between these fields and their data:

• In your local environment, change the default value of the Testimonial rich text field to the following: “I would 100% recommend it to my colleagues and friends.”
• Save your file. We’ll return to this in Step 10.

The module.html file should contain the HubL and HTML that you wrote in the HubL + HTML module editor in Step 4.

To make this code more interesting, copy and paste the following code into the file:

The module.css file should be empty at this point. To add styling, copy and paste the following code into the file:

After adding the code, save the file.

After making your changes to the module locally, you'll push them back into your HubSpot account.

• Navigate to your terminal and ensure that you're in the correct directory.
• Run the watch command to push changes to HubSpot on save: hs watch <src> <destination>. 
  • <src> is the path to your local files relative to your current working directory
  • <destination> is the destination path in your HubSpot account. The destination can be a new folder.
  • For example, hs upload my-theme my-new-theme would upload the my-theme folder from your machine to a my-new-theme folder in HubSpot.

• In your HubSpot account, navigate to Marketing > Files and Templates > Design Tools.
• In the left sidebar, navigate to the theme you've created, then open the module folder and select the Testimonial module.
• With the module open, you should now see your changes in the module.html and module.css panes.
• In the upper right, click Preview. A new tab will open to display the module preview. 

To recap this tutorial so far, you have:

• Created a module in HubSpot.
• Pulled that module down to your local environment.
• Made changes to the HubL + HTML and CSS using your local development tools.
• Uploaded your changes to your HubSpot account using the CLI watch command (Step 10).

But this is only one of many methods available for creating a module. For example, you could also:

1. Create a module in the Design Manager.
2. Pull that module down from our HubSpot account.
3. Before making any edits, run the watch command. With the watch command running, you can edit your module locally and see the changes immediately appear in your HubSpot account.  

When developing on HubSpot, experiment with your workflow to find what works best for you.

In the next part of this tutorial, learn how to use the module in a template.

Part 2: Using the module in a template

In your code editor, navigate to the my-theme directory you created in step 1 when initially downloading the HubSpot CMS boilerplate theme.

For this part of the tutorial, you'll be working mostly with the modules and templates folders. 

By their most basic definition, modules are editable areas of HubSpot templates and pages. You can insert modules into templates in HubSpot by using the design manager, but here we’ll be using HubL to add modules to a template in our local environment.   

• In your code editor, open the templates folder, then open the home.html file. 
• In the home.html file, navigate to the final dnd_section, which should start around line 28. You'll be adding your new module to this section.
  
• Within this dnd_section above the other dnd_modules, copy and paste the following HubL module tag:

This tag references your new module by its relative file path. In the next step, you'll add other optional parameters to the tag.

• If you haven’t kept the watch command running to track your work automatically, run hs watch <src> <dest> again in your terminal to upload your changes. Make sure that this command keeps running, as you complete the next steps. 
• In your HubSpot account, navigate to the design manager (Marketing > Files and Templates > Design Tools.
• In the left sidebar of the design manager, select the homepage.html file.
• In the upper right, click Preview, then select Live preview with display options to open the template preview in a new window.

• In the new tab, open your preview, which should contain your newly added testimonial module.

To make the homepage template more interesting:

• Navigate back to your code editor, then open the homepage.html file.
• Add the following parameters to the testimonial module tag:

The above parameters override the default values that you originally assigned to the three fields. Each parameter uses the HubL variable name that you assigned to each field in step 3:

• customer_name: this parameter passes the name Mary to the customer name field.
• profile_pic: this parameter is an object that contains two properties. The src property uses the get_asset_url HubL function to retrieve the URL for Mary's profile picture. Not that the image's file path is relative to your working directory. The alt property assigns the image's alt text.
• testimonial: this parameter passes new text into the testimonial field.

Alternatively for the rich text field, you could use HubL block syntax to write a large block of HTML or text:

Learn more about module block syntax.

If you’ve kept the watch command running in your terminal, save your changes to send them to HubSpot. You can then navigate back to the design manager to preview the template.

n this step, you'll add two more testimonial modules to the template using the same steps as before:

• Navigate to your code editor, then open the home.html file.
• Under the testimonial module you previous added, add another instance of the module by copying and pasting that module's code. In the new testimonial module, specify the following details using the same steps as above:
  • The customer's name is Ollie.
  • Ollie's testimonial reads: "I can't believe that I ever conducted business without the use of this product!"
  • For Ollie's picture, add the relative file path for the file within the images folder. Then give Ollie's image the alt attribute of "Ollie Profile Picture."
• Underneath the second testimonial module, add a third with the following details:
  • The customer's name is Erin.
  • Erin's testimony reads: "My business has nearly tripled since I began to use this product! Don't wait, start now!"
  • For Erin's picture, add the relative file path for the file within the images folder. Then give Erin's image the alt attribute of "Erin Profile Picture."
• Save your changes.

If you’ve kept the watch command running in your terminal, you can navigate back to the Design Manager to preview your changes to the template. The template preview should now contain all three testimonial modules.

In the next part of this tutorial, you'll build a HubSpot page using this template.

Part 3: Using the custom template in a HubSpot page

Before you can create a page with the homepage template you just modified, you'll need to make one final change in your local environment by modifying the theme.json file. In this file, you'll designate this directory as a theme that is accessible across different HubSpot products.  

In your code editor, open the theme.json file, then paste the following JSON object into the file (without the //theme.json comment):

After adding that code, save your changes so that the watch command sends your changes to HubSpot.

To create a page:

• In HubSpot, navigate to Marketing > Website > Website pages.
• In the upper right, click Create, then select Website page. Assign your page a name, then click Create page.
• On the Choose a template screen, select your My Custom Theme using the theme selector dropdown menu. 
  
  • If you're not currently seeing the correct theme, select Change theme in the theme selector dropdown menu.

• In your theme, click the Home template. In the upper right, click Select template.

In the page editor, you should see all the changes you've made throughout this tutorial.

To customize the page:

• In the left sidebar, use the Add tab to choose from default and custom modules. To add a module to the page, click and drag it into the page body in the center pane of the editor.
• In the left sidebar, use the Contents tab to review the page's current modules.
• In the left sidebar, use the Design tab to review the theme styles available for the page. 
• In the center pane where you page content displays, you can click modules to edit their contents.
• You can preview your changes at any time by click Preview in the upper right. Learn more about creating and editing pages.

The final step before publishing is to edit the page's settings:

• At the top of the editor, click the Settings tab to access the page's settings.
• Click the Page title field to add a title to the page. This title will display in the browser tab when a visitor accesses the page.
• Under Page URL, click the Content slug field to set the page's URL. You can also click the Domains dropdown menu to select from any of your connected domains.

• To publish your page, in the upper right, click Publish. Once published, the page will be live at the specified URL. 

• Getting started with themes
• Getting started with serverless functions
• Creating an efficient developer workflow
• Getting started with accessibility
• How to use JavaScript frameworks on CMS Hub
• How to use web components in custom modules
• How to build a code block web component based module