Sections

Last updated:

The outermost container in a drag and drop area is called a section. Sections can't be nested within any other dnd element but can contain modules, rows, and columns.  Sections can be modified, and drag and dropped in the page editor by content creators. Sections can be styled with backgrounds, and padding of their own.

screenshot of section in cms page editor

They can be created in the content editor by a content creator or built by a developer into a dnd_area, with the dnd_section tag. The styling options available in the editor, are available when coding a template as well.

HubL
<main class="body-container-wrapper">
  {% dnd_area 'dnd_area'
    label='Main section',
  %}
    {% dnd_section
      background_image={
        'backgroundPosition': 'MIDDLE_CENTER',
        'backgroundSize': 'cover',
        'imageUrl': 'https://example.com/path/to/image.jpg'
      },
      margin={
        'top': 32,
        'bottom': 32
      },
      padding={
        'top': '1em',
        'bottom': '1em',
        'left': '1em',
        'right': '1em'
      },
      max_width=1200,
      vertical_alignment='MIDDLE'
    %}
    
    {% end_dnd_section %}

  {% end_dnd_area %}
</main>

See dnd_area tags for a full reference of all of the available drag and drop element parameters and usage examples.

Reusable sections

You can build preconfigured reusable sections that content creators can drag and drop onto the page inside of a drag and drop area - from the page editor. These preconfigured sections are coded using the same syntax as you would use inside of a dnd_area, but they exist in their own file, a section template. 

You can control everything that you can with a normal drag and drop section, but offer it in a reusable way for content creators to make use of as a starting point.

These preconfigured sections can be used within your templates or just be made available to content creators in the editor. Similar to template partials where you can use the HubL include tag, to inject their content into a template - sections have their own function. To reference a preconfigured section use include_dnd_partial providing a path attribute pointing to the section file. include_dnd_partial is only usable inside of dnd_area.

HubL
{% dnd_area 'dnd_area' class='body-container body-container--home-page', label='Main section' %}
   {# Banner Section #}
   {% include_dnd_partial path='../sections/banner.html' context={} %}
   {# End Banner Section #}
{% end_dnd_area %}

Notice the context argument in the include_dnd_partial tag. This allows you to pass instance specific variables from the page template to the section, overriding the default values in the section file. See section context for more information.

You can use these sections to quickly scaffold out templates that are easy to read. Since you are only specifying in context where the template specific instances are different you can still go back and modify that section template. All of the instances of that section in all of your templates in your theme will be updated. 

Note - pages previously created with a template that had an included section in it will not get updated. This prevents accidentally making breaking changes. If a content creator wanted though they could get the most recent version of the section by adding it through the page editor and deleting the old version.

Section templates

Section templates are coded developer defined reusable sections.

Section templates are denoted with templateType: section in their template annotation. The full list of template annotations specific to sections is below.

HTML
<!--
 templateType: section
 label: Banner
 description: "A banner typically used at the top of a page highlighting a product or main topic."
 isAvailableForNewContent: true
 screenshotPath: ../images/section-previews/banner.png
-->
Section Template Annotations
ParameterTypeDescription Value
templateType
String

Sets the template type used to determine where the template can be used and what data is available to it.

section
label
String

Used in the page editor to provide a human readable name of the section.

description
String

Further description of the section beyond what you can do with a label. Displays in the page editor. 255 characters maximum.

screenshotPath
String/path

Path to a screenshot of the section. This is used to give content creators an easy visual reference for what the section looks like.

page editor add reusable section UI

Section screenshot tip: Use Chrome or Firefox to inspect the sections wrapper in the live page. Then right click the section's wrapper element. The context menu that appears contains "screenshot node"/ "capture node screenshot". Note if you have a sticky header, you may want to hide it using the inspector as it may appear over the screenshot.

A section template must begin and end with a dnd_section tag. Only one section can be within a section template. Inside of that section you can place modules, rows and columns. All of this follows the same dnd_area rules as dnd areas you would add to a page template. The exception is that you are defining the content for just a section and it's child drag and drop elements.

HubL
<!--
 templateType: section
 label: Banner
 description: "A banner typically used at the top of a page highlighting a product or main topic."
 isAvailableForNewContent: true
 screenshotPath: ../images/section-previews/banner.png
-->
{% dnd_section
 padding={
   'top': 200,
   'right': 20,
   'bottom': 200,
   'left': 20
 },
 background_image={
   'backgroundPosition': 'MIDDLE_CENTER',
   'backgroundSize': 'cover',
   'imageUrl': context.backgroundImage || get_asset_url('../images/blank-page-banner.png')
 },
 max_width=778,
 vertical_alignment='MIDDLE'
%}
 {% dnd_column %}
   {% dnd_row %}
     {% dnd_module path='@hubspot/rich_text' %}
     {% module_attribute 'html' %}
       <div style="text-align: center">
         {{ context.content || '<h1 style="color: #fff;">Communicate <span style="font-weight: 400;">Your Way</span></h1><p style="color: #fff;">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus dapibus posuere mi, in pretium ante posuere a. Aliquam a risus at eros molestie pretium.</p>' }}
       </div>
     {% end_module_attribute %}
     {% end_dnd_module %}
   {% end_dnd_row %}
   {% dnd_row %}
     {% dnd_module
       path='../modules/button',
       button_text={{ context.buttonText || 'Subscribe' }}
       horizontal_alignment='CENTER'
     %}
     {% end_dnd_module %}
   {% end_dnd_row %}
 {% end_dnd_column %}
{% end_dnd_section %}

Previewing your section

The easiest way to preview your section while developing, is to use the Design Manager. Open a template containing a dnd_area which calls your section template using a include_dnd_partial tag. In the top right corner click preview. This way you can keep updating your section and see your changes reflected right away. This is much more efficient than having to create a new page for each change you make.

Section context

You can use section context variables to override section level and module level default values. Section context variables are defined by you - meaning they are not associated directly with the modules and their fields.

In your page template you can set these context variables through the context parameter in the include_dnd_partial tag.

HubL
{% dnd_area 'dnd_area' class='body-container body-container--home-page', label='Main section' %}

   {# Banner Section #}
   {% include_dnd_partial path='../sections/banner.html'
     context={
       'content': '<h1 style="color: #fff;">Home Page</h1><p style="color: #fff;">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus dapibus posuere mi, in pretium ante posuere a. Aliquam a risus at eros molestie pretium.</p>',
       'buttonText': 'Buy Now'
     }
   %}
   {# End Banner Section #}

{% end_dnd_area %}

Any variables you add to your context parameter will become available to reference within your section template. Just like how you can set module and dnd element parameters with your custom HubL variables - you can do the same with context. In the following example we set the image URL to use the image URL set in context if it exists. We do the same for the rich text area and button content.

HubL
<!--
 templateType: section
 label: Banner
 description: "A banner typically used at the top of a page highlighting a product or main topic."
 isAvailableForNewContent: true
 screenshotPath: ../images/section-previews/banner.png
-->
{% dnd_section
  background_image={
   'backgroundPosition': 'MIDDLE_CENTER',
   'backgroundSize': 'cover',
   'imageUrl': context.backgroundImage || get_asset_url('../images/blank-page-banner.png')
 },
 max_width=778
%}
 {% dnd_column %}
   {% dnd_row %}
     {% dnd_module path='@hubspot/rich_text' %}
     {% module_attribute 'html' %}
       <div style="text-align: center">
         {{ context.content || '<h1 style="color: #fff;">Communicate <span style="font-weight: 400;">Your Way</span></h1><p style="color: #fff;">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus dapibus posuere mi, in pretium ante posuere a. Aliquam a risus at eros molestie pretium.</p>' }}
       </div>
     {% end_module_attribute %}
     {% end_dnd_module %}
   {% end_dnd_row %}
   {% dnd_row %}
     {% dnd_module
       path='../modules/button',
       button_text={{ context.buttonText || 'Subscribe' }}
       horizontal_alignment='CENTER'
     %}
     {% end_dnd_module %}
   {% end_dnd_row %}
 {% end_dnd_column %}
{% end_dnd_section %}

Notice everywhere context variables are used, there is an || (or). The simplest example is in the button module. What we're saying is if context.buttonText has a value use it. Else set the text to 'Subscribe'. This gives you a way to fallback to alternate default content if none is provided.

Section classes

As a developer you can add classes to the section wrapper using the class parameter. This will add the class you specify to the class field of the dnd section's html element. It's recommended wherever possible that you use styling controls built into sections to enable content creators to be able to modify them. The class option gives you a way to do more sophisticated styling.

HubL
{% dnd_section
 class='my-hero-section'
 padding={
   'top': 200,
   'right': 20,
   'bottom': 200,
   'left': 20
 },
 background_image={
   'backgroundPosition': 'MIDDLE_CENTER',
   'backgroundSize': 'cover',
   'imageUrl': context.backgroundImage || get_asset_url('../images/blank-page-banner.png')
 },
 max_width=778,
 vertical_alignment='MIDDLE'
%}
...

Content creators can't edit, add, or remove classes. They can only be "removed" by recreating a section manually in the editor.

Additionally you should avoid changing the layout of section children using CSS or JavaScript. Doing so can create an unpleasant page editor experience for the content creator. 


Was this page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.