Resource bundles - Theme Guide

You can use Java-style properties files to customize and configure Styleguide.

You can use resource bundles along with various template helpers to display localized or conditional text in published content. When creating a resource bundle, use the following conventions:

1. Change to the directory containing the template you want to populate with a resource bundle.
2. Create or open the file <TemplateName>_xx.properties, where xx is the code of the target language. For example, the file Author_en.properties populates the template Author.hbs for English-language locales. (You need to add the target language’s code even if you are not localizing the template’s output.) For a list of two-letter language codes, see List of ISO 639-1 codes.
3. In the properties file, add lines of the form key=value.

The following illustration shows a typical example of a template with three resource bundles: one for English, French, and Spanish.

.
└── styleguide/
    └── author/
        ├── AuthorPage.hbs
        ├── AuthorPage.json
        ├── AuthorPage_en.properties
        ├── AuthorPage_es.properties
        └── AuthorPage_fr.properties

At runtime, Brightspot uses the following logic to evaluate a template’s {{format}} placeholders using resource bundles:

1. Extract the site from the received URL.
2. Determine the site’s locale.
3. Retrieve the template for the requested item.
4. Look up the properties file for the site’s locale.
5. Within the properties file, look up the string to evaluate and return.
6. Populate the template’s helpers using the standard view-model logic.

See also:

• Localization
• messageformat.js

Using resource bundles, you can implement conditional text in your templates’ output. Conditional text has different values depending on a variable’s value. Examples of conditional text include the following:

• Localization—Display “snail” in English or “escargot” in French.
• Plurals—Display “one doughnut” for singular or “two doughnuts” for plural.
• Variants–Display “written by” if the content type is an article or “recorded by” if the content type is a video.

Styleguide uses the nodejs module messageformat.js to evaluate conditional text.

Evaluating plurals
You can use a resource bundle and the helper {{format}} to conditionally output the singular or plural form of a noun, or to output numerals versus numbers. The example in this section uses a data file, template, and properties file to output the singular or plural form of the number of search results based on a passed quantity.

{
  "_template": "SearchResults.hbs", 
  "numberReturned": 12 
}

{{!-- File name SearchResults.hbs --}}
<div class="SearchResults">
    {{#with numberReturned}}
    <div class="SearchResults-numberReturned">
         {{format "searchResultMessage" count=this}}
    </div>
    {{/with}}
</div>

# File name SearchResults_en.properties
searchResultMessage=There {count, plural, =0{are no results} one{is 1 result} other{are # results}}.

In the previous snippet, the message formatter searchResultMessage receives a single parameter count passed from the previous template. The message formatter then outputs the correct form of the plural based on the value of the parameter count. At runtime, Styleguide evaluates and outputs the plural form as follows:

<div>There are 12 results.</div>

Textual variants
You can use a resource bundle and the helper {{format}} to output textual variants using logic similar to Java’s switch statement. The example in this section uses a data file, template, and properties file to output “written by” for articles, “recorded by” for videos, and “submitted by” for any other content type.

{
  "_template": "Byline.hbs", 
  "contentType": "article", 
  "authorName": "Beau Tye" 
}

{{!-- File name Byline.hbs --}}
<div class="Byline">
    {{#with authorName}} 
    <div class="Byline-authorName">
		{{format "bylineMessage" authorName=this}}</div> 
    </div>
	{{/with}}
</div>

# File name Byline_en.properties
bylineMessage={type, select, article {Written by} video {Recorded by} other {Submitted by}} {authorName}

In the previous snippet, the message formatter bylineMessage receives a single parameter type passed from the previous template. The message formatter then evaluates the select statement based on the value of the parameter type. At runtime, Styleguide evaluates and outputs the variant as follows:

<div>Written by Beau Tye</div>

See also:

• messageformat.js.
• {{format}}
• Localization
• Date formats and resource bundles

You can use resource bundles along with the {{format}} helper to display localized text in published content. This deployment requires a single template, a resource bundle for each locale, and an optional data file.

At runtime, Brightspot displays localized text using the following logic:

1. Extract the site from the received URL.
2. Determine the site’s locale.
3. Retrieve the template for the requested item.

4. Populate the template’s helpers using the standard view-model logic. However, when processing {{format}} helpers:

   1. Look up the properties file for the site’s locale.
   2. Within the properties file, look up the string to evaluate and return.

The following snippets provide an example for localization with the {{format}} helper. All of the snippets in this example are in the same directory.

{
  "_template": "AuthorPage.hbs" 
}

{{!-- File name AuthorPage.hbs --}}
<div>
    <h3 class="author-headline">{{format "aboutme"}}</h3> 
</div>

The default properties file has a name AuthorPage.properties, and the localized properties file has a name AuthorPage_xx.properties.

• The literal AuthorPage is mandatory because it must match the name of the template.
• The two letters before .properties must be a language code that Java recognizes. For a list of two-letter language codes, see Codes for the Representation of Names of Languages.
• Example: AuthorPage_fr.properties

# File name AuthorPage.properties
aboutme=My Recent History

The previous snippet is in a file AuthorPage.properties. This is the default properties file for localization. If there is no locale associated with the site, or if there is no properties file for the site’s locale, Brightspot renders the output using this file.

# File name AuthorPage_fr.properties
aboutme=Mon Histoire Récente

The previous snippet is in a file AuthorPage_fr.properties. When Brightspot detects that the published site’s locale is French, it looks up the value for {{format "aboutme"}} in this file.

<div>
    <h3 class="author-headline">Mon Histoire Récente</h3>
</div>

The previous snippet shows the resulting HTML output for localized text from the {{format"aboutme"}}helper.

See also:

• Location of resource bundles
• Conditional text
• Localizing published websites
• messageformat.js
• {{format}}

Brightspot displays dates with a default Java format of MMMM d, yyyy hh:mm aa, such as September 8, 2017 02:38 PM.

You can customize the date format by site, theme, content type, and language. For example, you can specify a 12-hour format for general-interest articles, and a 24-hour format for defense-related articles.

Priority of date formats
When resolving the date format to apply, Brightspot checks the following hierarchy and uses the first one available.

1. Use a format configured in theme’s properties (see below).
2. Use a format configured in a site’s settings (see Configuring a site’s date format).
3. Use a format appearing in a view model (see Formatting dates using view models).
4. Use MMMM d, yyyy hh:mm aa.

Configuring date formats with a resource bundle

1. Change to or create the path /themes/<theme_name>/resources/brightspot/view/core/.
2. Change to or create the subdirectory corresponding to the required view for the content type. For example, if you are configuring the date format for the articles’ view, change to the subdirectory article.

3. Create or open the file <View>Override.properties or <View>Override_<language-code>.properties. Examples:

   • The file ArticlePageViewOverride.properties specifies the date format for views associated with articles.
   • The file ArticlePageViewOverride_fr.properties specifies the date format for views associated with articles displayed in French.
   • For a list of two-letter language codes, see Codes for the Representation of Names of Languages.

4. In the properties file, add a line of the form dateFormat=<format-string>.

   • Construct format-string from the listing in Patterns for Formatting and Parsing in the Java class DateTimeFormatter.
   • Example: dateFormat=YYYY-MMMM-dd HH:mm displays a date such as 2017-September-12 15:05. Do not enclose the format string in quotes.
5. Reload or rebuild your Brightspot project.

See also:

• Formatting dates using view models

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.

{
  "_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 code snippet above, 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.

Original template (AuthorPage.hbs)

{{#element "name"}}
    <h1>{{this}}</h1>
{{/element}}

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": { 
      "example": "/author/AuthorPage.json", 
      "templates": [{ 
          "displayName": "Writer Emeritus",
          "template": "/core/author/AuthorPageNew.hbs"
        }
      ]
    }
  }
}

Step 6: Rebuild and upgrade theme

Rebuild the theme and then install it as a new release.

See also:

• Resource bundles
• Traditional

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 1. 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.

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 above, 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.

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

See also:

• Resource bundles
• Traditional
• Location of resource bundles