Freeform Theming Tutorial

In this section you work through an example for creating a new freeform module based on an existing freeform module provided with Brightspot. To fully understand the examples in this section, you should have a good knowledge of Brightspot’s implementation of the Model-View-ViewModel paradigm. If you’re new to this topic, you can start with the Tutorials.

Step 1: Design and Characterize the Freeform Module

For our demonstration, let’s create the following freeform module:

../../../../_images/freeform-side-by-side.png

The above model has two distinct parts:

  • The right side has an image that we want to display 450 pixels wide by 370 pixels high.
  • The left side has five individual text elements.

Step 2: Create Template File

In this step you create the freeform module’s template by extending the core freeform template. In the styleguide/ directory, create a subdirectory freeform-sbs/FreeformSideBySide.hbs and enter the following text:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{{#block "FreeformSideBySide" extend="/node_modules/brightspot-express/styleguide/core/freeform/Freeform.hbs"}}
    <div class="{{blockName}}">
        {{#element "aside" noWith=true}}
            <div  class="{{elementName}}">
                {{element "items" }}
                {{element "link"}}
             </div>
        {{/element}}

        {{#element "media"}}
            <div class="{{elementName}}">
                {{include "../link/Link.hbs" href=../url target=../target body=this}}
            </div>
        {{/element}}
    </div>
{{/block}}

In the previous snippet—

  • Line 1 declares a new template with the attribute extend. This attribute adds elements to the template Freeform.hbs.
  • Lines 3–8 declare an element aside that itself contains two elements: items for text and link for a hyperlink.
  • Lines 10–14 declare an element media. This element is based on the existing template Link.hbs. The latter template sets the image within a hyperlink if one is provided.

Step 3: Create Data File

In the same directory where you created FreeformSideBySide.hbs, create a new file FreeformSideBySide.json and enter the following text:

1
2
3
4
5
6
7
{
  "_template": "FreeformSideBySide.hbs",
  "_include": "/node_modules/brightspot-express/styleguide/core/freeform/Freeform.json",
  "media": {
    "_include": "/node_modules/brightspot-express/styleguide/core/image/Image.json"
  }
}

In the previous snippet—

  • Line 2 declares this data file pertains to the companion template file FreeformSideBySide.hbs.
  • Line 3 includes the existing definitions from the data file Freeform.json.
  • Lines 4–6 provide a reference to Image.json, which itself provides the View fields for the element media appearing in the template file from step 2.

Step 4: Register Custom Module

In a text editor, open the file /styleguide/_config.json and add the following under a /styles key.

{
  "styles": {
    "/node_modules/brightspot-express/styleguide/core/freeform/Freeform.hbs": {
      "width": 1000,
      "height": 500,
      "scale": 0.5,
      "example": "/node_modules/brightspot-express/styleguide/core/freeform/Freeform.json",
      "templates": [
      {
        "displayName": "Side By Side",
        "template": "/styleguide/freeform-sbs/FreeformSideBySide.hbs",
        "example": "/styleguide/freeform-sbs/FreeformSideBySide.json",
        "fields": {
          "image": {
            "type": "record",
            "groups": "brightspot.core.image.imageOption"
          }
        }
      }
      ]
    }
  }
}

Step 5: Add Image Size

Our design for the freeform module specifies an image size of 450 × 370. In this step we register this image size with Brightspot. Returning to the file _config.json, under the /imageSizes node, add lines 3–6 from the following snippet:

1
2
3
4
5
6
7
8
{
  "imageSizes": {
    "landscape-large-450x370": {
       "width": 450,
       "height": 370
    },
  },
}

In the previous snippet, we attach the identifier landscape-large-450x370 to our custom image size. (For a best practice for naming image sizes, see Naming Convention for Image Sizes.)

Step 6: Add Image Context

In this step, we specify the context in which we use our custom image size. Returning to the file _config.json, under the /imageSizesContext node, add lines 3–5 from the following snippet:

1
2
3
4
5
6
7
{
  "imageSizesContext": {
    "/styleguide/freeform-sbs/FreeformSideBySide.hbs": {
      "image": "landscape-large-450x370"
    },
  }
}

The previous snippet indicates that whenever we apply the template FreeformSideBySide.hbs and need to display an image element, we look up the image landscape-large-450x370 from the imageSizes node.

Step 7: Add Styling

The template file created in Step 2 includes Handlebars helpers that generate class names using the Block-Element-Modifier methodology. In your CSS or Less file, add selectors corresponding to the class names to achieve the required styling effects. For details, see Nested Class Names in Less.

Step 8: View New Style

After creating the side-by-side style with the JSON and Handlebars files, you can display its preview.

  1. Open a terminal and change to the Brightspot project’s directory.
  2. Run the following commands:
    1. mvn clean install (necessary only if you haven’t yet built your Brightspot project)
    2. gulp styleguide
  3. Open a web browser, and go to http://localhost:3000/_styleguide/index.html.
  4. Click the link for Freeform Side By Side.
../../../../_images/freeform-in-styleguide.png

Referring to the previous example, the freeform module’s text is on the left side and the image is on the right side—an effect provided by CSS. Within the text, there are paragraphs of body text followed by a hyperlink.