Support and Documentation

Style selection

A theme's configuration file _config.json associates templates with content types for a given theme and context. You can override these assignments using resource bundles.

Default style

The key _template in a Styleguide data file assigns a template to the data file, as in the following example.

Example 98. Assigning default ftyle
{
  "_template": "/path/to/AuthorPage.hbs"
}


Referring to the previous snippet, when a visitor retrieves an author's page, Brightspot looks up the template AuthorPage.hbs, populates the placeholders with retrieved data, and returns the HTML code.

You can override the assignment between a data file and template using a resource bundle. The following example describes how to override the default template for an author's bio page.

Step 1: Determine the assigned template

  1. Open the data file that contains template assignment you want to override.

  2. Note the template specified by the key _template.

Referring to the snippet Assigning default ftyle, the assigned template is /path/to/AuthorPage.hbs.

Step 2: Identify overriding templates

Create or locate the template you want to use as the default override.

Example 99. Original template (AuthorPage.hbs)
{{#element "name"}}
    <h1>{{this}}</h1>
{{/element}}


Example 100. Overriding template (AuthorPageNew.hbs)
{{#element "name"}}
    <h1>{{this}}</h1>
    <h1>Writer Emeritus</h1>
{{/element}}


The snippet Overriding template (AuthorPageNew.hbs) adds a byline Writer Emeritus under the author's name.

Step 3: Identify overriding data files

Create or locate the data files that use the template you identified in Step 2. For information about creating a data file, see Populating the Styleguide preview.

Step 4: Declare overriding template

  1. Create or open a properties file as described in Creating properties files.

  2. Add a line in the properties file similar to the following example:

    /path/to/AuthorPage.hbs/defaultTemplate=/path/to/AuthorPageNew.hbs
    

In the previous snippet—

  • The left side of the assignment contains the template you determined from Step 1. The literal /defaultTemplate is mandatory.

  • The right side of the assignment is the file you identified in Step 2.

Step 5: Register templates

Register the overriding template in the styles member of the theme's configuration file _config.json.

{
  "styles": {
    "/core/author/AuthorPage.hbs": { 1
      "example": "/author/AuthorPage.json", 2
      "templates": [{ 3
          "displayName": "Writer Emeritus",
          "template": "/core/author/AuthorPageNew.hbs"
        }
      ]
    }
  }
}

1

Assigned template you determined in Step 1.

2

Declares the data file you identified in Step 3.

3

Registers the overriding template you identified in Step 2.

Step 6: Rebuild and upgrade theme

Rebuild the theme and then install it as a new release. For details, see Upgrading a theme to new release.

Author page with assigned template
Figure 201. Author page with assigned template


Author page with overriding template
Figure 202. Author page with overriding template


Restricting available styles

The key styles in a theme's configuration file _config.json assigns available styles to a given template, as in the following example.

Example 101. Assigning available styles
{
  "styles": {
    "/core/article/ArticlePage.hbs": {
      "templates": [
        {
          "displayName": "Neutral Article",
          "template": "/core/article/Article.hbs"
        },
        {
          "displayName": "Optimistic Article",
          "template": "/core/article/Article-opt.hbs"
        },
        {
          "displayName": "Pessimistic Article",
          "template": "/core/article/Article-pess.hbs"
        },
        {
          "displayName": "Alarmist Article",
          "template": "/core/article/Article-alarm.hbs"
        }
      ]
    }
  }
}


Upon detecting an array templates as in the previous snippet, Brightspot lists the corresponding templates in the content edit form. Referring to the previous snippet, when publishing an article, an editor can select one of the available templates neutral, optimistic, pessimistic, and alarmist as indicated by the keys displayName. See the illustration Available templates from configuration file.

You can override the styles available to a given content type using a resource bundle. In most use cases, you limit the available styles declared in _config.json. The following example describes how to limit the available styles for an author's bio page.

Step 1: Determine the target template

  1. Open the configuration file _config.json that declares the available templates you want to override.

  2. Note the target template specified by the key styles.

Referring to the snippet Assigning available styles, the target template is /core/article/ArticlePage.hbs.

Step 2: Identify available templates

Create or locate the templates you want to make available for the target template

Step 3: Declare available templates

  1. Change to or create the path /themes/<theme_name>/resources/brightspot/.

  2. Change to or create the subdirectory corresponding to the model to which the templates apply. For example, if you are defining available templates for brightspot/core/article/Article.java, create a subdirectory /themes/<theme_name>/resources/brightspot/core/article.

  3. Change to the directory you created in step 2.

  4. Create a properties corresponding to the model to which the templates apply. Examples:

    • The file ArticleOverride.properties specifies the available templates associated with items of type Article.

    • The file ArticleOverride_fr.properties specifies the available templates associated with items of type Article displayed in French.

    • For a list of two-letter language codes, see Codes for the Representation of Names of Languages.

  5. Add lines in the properties file similar to the following example:

    /core/article/ArticlePage.hbs/availableTemplates=/core/article/Article-opt.hbs,/core/article/Article-pess.hbs
    

In the previous snippet—

  • The left side of the assignment contains the target template you determined in Step 1. The literal /availableTemplates is mandatory.

  • The right side of the assignment is a comma-separated list of templates you identified in Step 2.

Step 4: Rebuild and upgrade theme

Rebuild the theme and then install it as a new release. For details, see Upgrading a theme to new release.

At run time, Brightspot displays the available templates in the model's content edit form, Overrides widget, Page Style list.

Available templates from configuration file
Figure 203. Available templates from configuration file


Available templates from resources bundle
Figure 204. Available templates from resources bundle