Promo Theming Tutorial

In this section you work through an example for creating a new promo module based on an existing promo 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 Promo Module

For our demonstration, let’s create a promo module with a lead image, title, body text, and category. The lead image, title, and category are set as hyperlinks.

../../../../_images/promo-tutorial-wireframe.svg

Step 2: Create Template File

In this step you create the promo’s template by extending the core promo template. In the styleguide/ directory, create a file promo-sbs/PromoSideBySide.hbs and enter the following text:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{{#block "PromoSideBySide" override="/node_modules/brightspot-express/styleguide/core/promo/Promo.hbs"}}
    {{element "media" noWith=true}}

    {{#element "info" noWith=true}}
        <div class="{{elementName}}">
            {{element "title"}}
            {{element "description"}}
            {{element "category"}}
        </div>
    {{/element}}
{{/block}}

In the previous snippet—

  • Line 1 declares a new template with the attribute override that overrides elements found in the template Promo.hbs.
  • Line 2 overrides the element media found in Promo.hbs, adding an attribute noWith. All other components of the original element, such as the nested <div> and hyperlink, are inherited into our template.
  • Lines 4–10 override the element info in Promo.hbs:
    • The elements title, description, and category are directly inherited into our template without any overrides.
    • The elements type, duration, date, and button are specified in the template Promo.hbs, but are not mentioned in our template, so they are not part of the new template’s View.

Step 3: Create Data File

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

1
2
3
4
{
  "_template": "PromoSideBySide.hbs",
  "_include": "/node_modules/brightspot-express/styleguide/core/promo/Promo.json"
}

In the previous snippet—

  • Line 2 declares this data file pertains to the companion template file PromoSideBySide.hbs.
  • Line 3 includes the existing definitions from the data file Promo.json.

Step 4: Register Custom Module

In a text editor, open the file /styleguide/_config.json and add the following styles key at the root level as in the following example.

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

Step 5: Add Image Size

In this step you register an image size of 450×370 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, you attach the identifier landscape-large-450x370 to the 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, you specify the context in which to use your custom image size. Returning to the file _config.json, under the /imageSizeContexts node, add lines 3–5 from the following snippet:

1
2
3
4
5
6
7
{
  "imageSizeContexts": {
    "/styleguide/promo-sbs/PromoSideBySide.hbs": {
      "image": "landscape-large-450x370"
    }
  }
}

The previous snippet indicates that Brightspot renders the promo using PromoSideBySide.hbs using the image size landscape-large-450x370.

For more information about the imageSizeContexts object, see Define Image Size Context.

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 Promo Side By Side.
../../../../_images/promo-in-styleguide.png

Referring to the previous example, the lead image, title, and category are set inside hyperlinks, as inherited from the template Promo.hbs.