Support and Documentation

Special keys

The following keys provide additional logic when processing the data file.

_dataUrl

Deprecated.

Location of a file to be included in the JSON object. Although _dataUrl is still supported, new code should use _include.

_delegate

Inserts any selected template into a wrapper template's delegated placeholder. Applicable in top-level data files styleguide/_wrapper.json. This key promotes modular development, because it incorporates different types of referred templates into a top-level referring template. A typical scenario is building a referring template with a header, body, and footer, and delegating the contents of the body to an arbitrary referred template.

The following example illustrates the effect of _delegate.

Step 1: Create article template

Create a modular template styleguide/article/Article.hbs containing an article's headline and body.

<div class="Article">
    <div class="Article-headline">
        {{articleHeadline}}
    </div>
    <div class="Article-body">
        {{articleBody}}
    </div>
</div>

The previous snippet is designed to be referenced by other templates: there are no <html>, <head>, and <body> tags, all of which are provided by the more complete wrapper template.

Step 2: Create article data file

Create a data file styleguide/article/Article.json that populates the template Article.hbs with mock data.

{
  "_template": "/article/Article.hbs",
  "articleHeadline": "New Mexico Headed for Real Estate Bubble",
  "articleBody": "Real estate agents throughout northern New Mexico are reporting brisk sales of property even though a meteor is predicted to flatten the area in the year 2035."
}

Step 3: Create wrapper template

Create a template styleguide/page/Page.hbs that serves as a wrapper template. At runtime, Styleguide wraps all selected templates inside this template.

<!DOCTYPE html>
<html>
   <head>
       <title>{{pageHeader}}</title>
       <link href="/styleguide/All.min.css" type="text/css" rel="stylesheet" />
   </head>

   <body>
       <div class="Page">
           <div class="Page-header">
               {{pageHeader}}
           </div>
           {{pageBody}} 1
           <div class="Page-footer">
               {{pageFooter}}
           </div>
       </div>
   </body>
</html>

1

At runtime, Styleguide replaces this placeholder with the populated template selected in the Styleguide GUI. (When your Styleguide project is integrated with a parent project such as Brightspot, the back end implements interfaces to populate this placeholder with the appropriate child View.)

Step 4: Create wrapper data file

Create a data file styleguide/_wrapper.json that populates the wrapper template Page.hbs with mock data and includes a delegate instruction.

{
  "_template": "/page/Page.hbs",
  "pageHeader": "Extraterrestrial Times",
  "pageBody": { 1
    "_delegate": true
  },
  "pageFooter": "Area 51, Edwards Air Force Base"
}

1

Inserts any selected template into the wrapper template's {{pageBody}} placeholder.

Note

You can prevent a template from being wrapped inside a wrapper template. For details, see _wrapper.

Step 5: Run Styleguide

If the Styleguide server isn't running, in the theme/ directory enter yarn server:styleguide.

Runtime Analysis

The sequence of events at runtime are as follows:

  1. User clicks a template in the Styleguide GUI, such as Article.

  2. Check for existence of the file styleguide/_wrapper.json.

  3. If the file exists, retrieve associated wrapper template from the key _template, in this case Page.hbs.

  4. Populate the retrieved wrapper template with explicit values from styleguide/_wrapper.json.

  5. Open the data file associated with the selected template Article, in this case Article.json.

  6. Retrieve the associated template from the key _template, in this case Article.hbs.

  7. Populate Article.hbs with values from its data file Article.json.

  8. Place the populated template Article.hbs into the placeholder {{pageBody}} inside the wrapper template.

delegate-key.svg
_hidden

Hides individual templates from appearing in Styleguide. This feature is useful if one template is always nested inside another (although you can use this key with standalone templates). For example, the following illustration indicates that the child template Image.hbs is nested in three parent templates: Author.hbs, Promo.hbs, and Blog.hbs.

nested-templates.svg

Image.hbs may be a simple template that you don't need to view in Styleguide. To suppress its appearance in Styleguide, add the key _hidden to the corresponding data file Image.json.

{
  "_hidden": true
}
. See also:
_image

If true, Styleguide and the back end retrieve available image attributes, such as height and width, from the configuration file _config.json.

Example 75. Data file with _image key
{
  "_template": "/path/to/Image.hbs", 1
  "image": {
    "_image": true, 2
    "src": "/path/to/image.png" 3
  }
}

1

Indicates the template is Image.hbs.

2

Specifies when evaluating the template's placeholder image, retrieve all available attributes from the configuration file _config.json. In effect, at build time Styleguide replaces this line with all attributes found in the corresponding context in _config.json.

3

Provides the path for the attribute src.



The following code samples illustrate the processing logic for configuring and retrieving the image attributes.

Step 1: Configure image attributes

Configuring image attributes requires specifying the following in _config.json:

  • Image-sizes context under the node imageSizeContexts.

  • Actual attribute values under the node imageSizes.

Example 76. Context-sensitive image attributes
{
  "imageSizes": {
    "landscape-small-100x50": { 1
      "width": 100,
      "height": 50
    }
  },
  "imageSizeContexts": {
    "/absolute/path/to/Image.hbs": { 2
      "image": "landscape-small-100x50"
    }
  }
}

1

Provides the image attributes for landscape-small-100x50.

2

Specifies that when rendering the placeholder image in the template Image.hbs, the corresponding image attributes come from element imageSizes.landscape-small-100x50.



Step 2: Retrieving image attributes

Inside a template, you can access an image's attributes using the dot operator.

{{#element "image"}}
    <img src="{{this.src}}" 1
        width="{{this.width}}" 2
        height="{{this.height}}"
    />
{{/element}}

1

Retrieves the value for the src attribute from the listing Data file with _image key.

2

Retrieves the values for the width and height attributes from the listing Context-sensitive image attributes.

. See also:
_include

Location of a referenced data file to be included in this one. This key promotes the reuse of existing templates and data files.

You can use absolute or relative paths; for details, see Pathing for referred data files and templates.

Example 1: Referencing one data file from another

The following steps provide an example of using _include to reference an author data file from an article data file.

Step 1: Create author template

Create a modular template AuthorInfo.hbs containing the author's name and bio.

<div>
    {{authorName}}
</div>
<div>
    {{authorBio}}
</div>

The previous snippet is designed to be referenced by other templates: there are no <html>, <head>, and <body> tags, all of which are provided by the more complete referencing template.

Step 2: Create author data file

Create a data file AuthorInfo.json that populates the template AuthorInfo.hbs with mock data.

{
  "_template": "path/to/AuthorInfo.hbs",
  "authorName": "{{name()}}",
  "authorBio": "{{words(10)}}"
}

Step 3: Create article template

Create a template Article.hbs for an article that references the author template.

<!DOCTYPE html>
<html>
   <head>
       <title>{{headline}}</title>
   </head>

   <body>
       <div>
           {{headline}}
       </div>
       <div>
           {{body}}
       </div>
       {{authorInfo}} 1
   </body>
</html>

1

Styleguide replaces this placeholder with the template for author info using the data file created in the following step. Furthermore, this snippet is a complete HTML file: it contains the <html>, <head>, and <body> tags.

Step 4: Create article data file

Create a data file Article.json that populates the template Article.hbs with mock data and also contains a reference to the data file AuthorInfo.json.

{
  "_template": "path/to/Article.hbs",
  "headline": "{{words(4)}}",
  "body": "{{paragraphs(1, 2, 10)}}",
  "authorInfo": { 1
    "_include": "AuthorInfo.json"
  }
}

1

Performs the following:

  1. Opens the file AuthorInfo.json.

  2. Retrieves the value for the key _template, which is AuthorInfo.hbs.

  3. In the article template Article.hbs, replaces the placeholder authorInfo with the contents of the template AuthorInfo.hbs.

  4. Populates all placeholders with mock data from the data files Article.json and AuthorInfo.json.

At the end of these steps, Styleguide produces the complete page.

<!DOCTYPE html>
<html>
    <head>
        <title>Omri ka co uk</title>
    </head>

    <body>
        <div>
            Omri ka co uk
        </div>
        <div>
            <p>Awma uze lucfaw siwgicgev wugtuwdob gulnoj apevema gitjifo div dabawibep. Wasef je kim joh fa kohwodvo fabege koni tezwib binsifzen.</p>
        </div>
        <div>
            Frank Stanley
        </div>
        <div>
            Lohadmi pe voku lumowwi ha Eddie Silva odro da ed uwaeme
        </div>
    </body>
</html>
Example 2: Referencing one data file from another multiple times

Example 1: Referencing one data file from another describes how to reference one data file from another a single time. You can use the _repeat key to include a data file multiple times.

Example 77. Repeating a child data file
{
  "_template": "path/to/Article.hbs",
  "headline": "{{words(4)}}",
  "body": "{{paragraphs(1, 2, 10)}}",
  "authorInfo": [ 1
    {
      "_include": "AuthorInfo.json", 2
      "_repeat": [3, 4] 3
    }
  ]
}

1

Specifies an array for including multiple instances of a child data file into this parent data file.

2

Specifies the child data file to include.

3

Specifies the number of times to include the data file: a random integer between 3 and 4.



For more information about repeated includes, see _repeat.

Example 3: Including an element from a JSON array

There are times when you may want to organize similar template components into a single data file. The following snippet, named AuthenticationForms.json, contains variations for the prompt on an authentication page: register, log in, and forgot password.

[
  {
    "_template": "path/to/RegistrationForm.hbs",
    "body": "<p>Register</p>"
  },
  {
    "_template": "path/to/LoginForm.hbs",
    "body": "<p>Log in</p>"
  },
  {
    "_template": "path/to/ForgotPassword.hbs",
    "body": "<p>Forgot password</p>"
  }
]

The previous snippet is a JSON array of three elements. You can refer to one of these elements in a parent data file.

{
  "main": {
    "_include": "path/to/AuthenticationForms.json", 1
    "_key": 1 2
  }
}

1

Refers to the file containing a JSON array.

2

Refers to the index within the JSON array to include. In this case, Styleguide includes the second element in the array, corresponding to the log-in form.

For more information about including elements from a JSON array, see _key.

Example 4: Including a random element from a JSON array

There are times when you may want to display different layouts of the same content type. The following snippet, named AdTypes.json, contains variations for ad layout: one with text only, the other with text and an image.

[
  {
    "_template": "/content/random/TextOnly.hbs",
    "body": "{{words(10)}}"
  },
  {
    "_template": "/content/random/TextAndImage.hbs",
    "body": "{{words(10)}}",
    "image": "{{image(100,100)}}"
  }
]

The previous snippet is a JSON array of two elements, and at runtime Styleguide can randomly select one of them to display.

{
  "main": {
    "_include": "path/to/AdTypes.json", 1
    "_random": true 2
  }
}

1

Refers to the file containing a JSON array.

2

Instructs Styleguide to randomly draw one of the layouts from the referred data file and include it in the parent file.

. See also:
_key

Specifies which element to use from the array pointed to by the sibling _include key. Indexing of _include arrays starts at zero.

{
  "main": {
    "_include": "path/to/ArticleBodies.json",
    "_key": 0
  }
}

In the previous snippet, Styleguide examines the array in the file ArticleBodies.json, and uses the first element to generate child views for main. If there is no _key element, then Styleguide imports the entire included file.

For another example, see the snippets in Example 3: Including an element from a JSON array.

. See also:
_random

Randomly selects which element within an array to use for generating a view. Applies when all of the following are true:

  • Present with an _include key.

  • _include points to a file containing a JSON array.

  • _random is set to true.

This key is operational only at Styleguide's run time. In the production environment, when Brightspot uses Styleguide's templates to render an item, this key has no impact.

{
  "main": {
    "_include": "path/to/ArticleBodies.json",
    "_random": true
  }
}

In the previous snippet, Styleguide examines the array in the file ArticleBodies.json, and randomly selects one of the elements to generate child views for main.

For another example, see the snippet under Example 4: Including a random element from a JSON array.

_repeat

Number of times a data file referenced by _include is repeated. This entry has two forms:

  • Repeating a data file a fixed number of times: "_repeat": 1

  • Repeating a data file random number of times between x and y: "_repeat": [ x, y ]

This key, along with the associated data file, must be inside an array.

For an example, see the snippet Repeating a child data file.

_template

Path to the corresponding template. Your data file must have a _template key.

You can use absolute or relative paths; for details, see Pathing for referred data files and templates.

{
  "_template": "/page/Page.hbs",
}
_wrapper

When false, the associated template is not wrapped inside a wrapper template. For example, suppose you have a data file styleguide/_wrapper.json as follows:

{
  "_template": "path/to/Page.hbs",
  "pageHeader": "Extraterrestrial Times",
  "pageBody": { 1
    "_delegate": true
  },
  "pageFooter": "Area 51, Edwards Air Force Base"
}

1

Indicates that any template selected in the Styleguide GUI is populated and inserted into the wrapping template's {{pageBody}} placeholder. (For a detailed explanation, see _delegate.) However, if a template's data file has the key _wrapper set to false, Styleguide displays the selected template without the wrapping.

{
  "_template": "path/to/Article.hbs",
  "_wrapper": false, 1
  "articleHeadline": "New Mexico Headed for Real Estate Bubble",
  "articleBody": "Real estate agents throughout northern New Mexico are reporting brisk sales of property even though a meteor is predicted to flatten the area in the year 2035."
}

1

Prevents Article.hbs from being wrapped inside a top-level template.

javaPackage

Java package prefix for this theme. Brightspot uses this value when creating the view interfaces. For more information, see How the view generator creates view classes.

{
  "javaPackage": "brightspot.view"
}

The previous snippet configures Brightspot to generate view interfaces with the package name package brightspot.view.

pom

Maven POM file used to compile a theme.

{
  "pom": "frontend/pom.xml"
}

If this element is absent from _config.json, Brightspot builds the theme from the file pom.xml in the current directory.

vars

Array of arbitrary keys and associated values. You can use these values in Styleguide data files; for details, see var.

{
  "vars": {
    "exampleSiteUrl": "http://www.brightspot.com/" 1
  }
}

1

Declares a key exampleSiteUrl with a value http://www.brightspot.com/.