Populating the Styleguide preview - Documentation

Brightspot uses your data files to populate the Styleguide preview. You can populate the preview with static data or with random, mock data.

Populating the preview with static data

As you create data files, the keys correspond to placeholders in the template, and Brightspot injects the values into the placeholders.

See also:

Populating the preview with mock data

Populating static images

The following snippets illustrate how Brightspot injects static images from the data file into the Styleguide preview.

{
  "_template": "static.hbs",
  "remoteImage": "https://www.nps.gov/grca/planyourvisit/images/agrca0643.jpg" 
  "localImage": "/styleguide/assets/Las_Meninas.jpg" 
}

URL of remote image injected into the {{remoteImage}} placeholder.
Path to local image injected into the {{localImage}} placeholder. For information about using local images in data files, see Using local media in data files.

<body>
    <h1>Remote image</h1>
    <img src="{{remoteImage}}" >   
    <h1>Local image</h1>
    <img src="{{localImage}}" >   
<body>

{{remoteImage}} placeholder.
{{localImage}} placeholder.

Populating static video and audio

The following snippets illustrate how Brightspot injects static video from the data file into the Styleguide preview. The technique is similar for static audio files.

{
  "_template": "static.hbs",
  "remoteVideo": "https://www.jpl.nasa.gov/videos/mer/mer20101222/sunset20101222-640-i.ogv" 
  "localVideo": "/styleguide/assets/liftoff.mp4" 
}

URL of remote video injected into the {{remoteVideo}} placeholder.
Path to local video injected into the {{localVideo}} placeholder. For information about using local video or audio files in data files, see Using local media in data files.

<body>
    <h1>Remote video</h1>
    <video>
        <source src="{{remoteVideo}}" type="video/ogg"> 
    </video> 
    <h1>Local video</h1>
    <video>
        <source src="{{localVideo}}" type="video/ogg">   
    </video>
<body>

{{remoteVideo}} placeholder.
{{localVideo}} placeholder.

Using local media in data files

You can use local media (images, audio, video) or binary files in data files. These files appear in the Styleguide preview. To use local media, you need to place them in the directory /styleguide/assets/.

theme/
├── _build/
|   ├── article/
|   │   ├── Article.hbs
|   │   └── Article.json
│   └── styleguide/
│       └── assets/
│           └── mona-lisa.jpg
└── styleguide/
    ├── article/
    │   ├── Article.hbs
    │   └── Article.json
    └── assets/
        └── mona-lisa.jpg

Run-time directory for media.
Source directory for media.

When you start the Styleguide server (yarn server:styleguide), the script copies files from /styleguide/assets/ to /_build/styleguide/assets/. You can then reference the media in your data files using absolute or relative paths.

{
  "_template": "static.hbs",
  "localImageAbs": "/styleguide/assets/mona-lisa.jpg",
  "localImageRel": "../styleguide/assets/mona-lisa.jpg"
}

Brightspot moves the media to the directory /_build/styleguide/assets/ only when the Styleguide server starts. If you want to add additional media, you need to restart the Styleguide server.

Populating the preview with mock data

Mocking data is an important tool in theme development. Mock data provides your development environment with simulated real-life data (such as names, dates, text, and images) so you can evaluate your templates’ layout and styling.

Data files come with helpers that generate random mock data, saving you the time of creating your own or connecting to a back end to inject data into the template. The randomization also tests your templates’ robustness, allowing for evaluations with longer and shorter text strings and larger or smaller images.

See also:

Populating the preview with static data

Value helpers

Value helpers provide mock data in the theme preview. For example, suppose you have a template with the following markup:

{{#with "reporter"}}
    <div class="reporter">
        <p>{{this}}</p>
    </div>
{{/with}}

You can use a value helper in the data file to generate a random name.

{
  "_template": "path/to/template.hbs",
  "reporter": "{{name}}
}

At runtime, Brightspot evaluates the helper and generates the following HTML:

<div class="Article-reporter">
    <p>Alfalfa Mail</p>
</div>

The following sections describe the available value helpers.

See also:

Generating data files from published content

date

Generates a random date.

Syntax

Form	Result
`{{date}}`	Returns date as July 4, 1776
`{{date('unformatted')}}`	Returns date as Tue Jul 04 1776 07:31:28 GMT-0400 (EDT).
`{{date('short')}}`	Returns date as 7/4/1776.
`{{date('iso')}}`	Returns date as 1776-7-4.

{
   "dateBorn": "{{date('iso')}}"
}

hexcolor

Generates a random hex color.

Syntax

Form	Result
`{{hexColor}}`	Returns a random RGB color in lower-case hexadecimal, such as #0c4d6a.
`{{hexColor(luminosity)}}`	Returns the lower-case hexadecimal color corresponding to the provided luminosity (0 ≤ luminosity ≤ 100).

Example

{
  "textColor": "{{hexColor(45)}}"
}

image

Returns the URL for use in an HTML <img src="url"> tag.

Syntax

Form	Result
`{{image(width,height)}}`	Returns the path to a mock image with the passed width and height. Brightspot stores the mock image in /_build/placeholder-image/.

Example

{
  "headShot": "{{image(100, 500)}}"
}

You implement this value helper in the template as follows:

<img src="{{headShot}}" >

See also:

Populating static images

name

Generates a random name.

Syntax

Form	Result
`{{name}}`	Returns a mock first and last name.

Example

{
  "authorName": "{{name}}"
}

number

Generates a random number.

Syntax

Form	Result
`{{number(value)}}`	Returns the passed value.
`{{number[lower,upper]}}`	Returns a random number between lower and upper.

All arguments and returned values are integers.

Example

{
  "age": "{{number([1,100])}}"
}

paragraphs

Generates mock paragraphs.

Syntax

Form	Result
`{{paragraphs(paragraphCount, sentenceCount, wordCount)}}`	Returns the passed number of paragraphs, each containing the passed number of sentences. Each sentence contains the passed number of words. Some words may be a two-word name.

Example

The following snippet generates three HTML <p> tags with four sentences in each. Each sentence has five random words.

Because this helper provides the <p> tags, you don’t need to include them in the template.

sentences

Syntax

Form	Result
`{{sentences(sentenceCount, wordCount)}}`	Returns the passed number of sentences, each containing the passed number of words. Some words may be a two-word name.

Example

The following snippet generates three sentences with seven words each.

{
  "byLine": "{{sentences(3,7)}}"
}

var

Returns the value of a variable defined in the vars object in your theme’s _config.json file.

Syntax

Form	Result
`{{var('keyname')}}`	Returns the value for the passed `keyname`. If the passed key does not exist in `_config.json`, returns blank.

This value helper is available for use within a data file only; you cannot use it in a template.

Example

Suppose you have a file _config.json with the following vars object:

{
  "vars": {
    "color": "blue"
  }
}

You can retrieve the color using var.

{
    "headline": "The sky is {{var('color')}} today."
}

words

Generates mock words. Some words may be a two-word name.

Syntax

Form	Result
`{{words(wordCount)}}`	Returns the passed number of words.
`{{words([lower,upper])}}`	Returns a random number of words between lower (≥ 4) and upper (≤ 13).

Example

The following snippet generates 10 words.

{
  "headline": "{{words(10)}}"
}