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>
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" }
Inserts any selected template into the wrapper template's |
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:
User clicks a template in the Styleguide GUI, such as
Article
.Check for existence of the file
styleguide/_wrapper.json
.If the file exists, retrieve associated wrapper template from the key
_template
, in this casePage.hbs
.Populate the retrieved wrapper template with explicit values from
styleguide/_wrapper.json
.Open the data file associated with the selected template
Article
, in this caseArticle.json
.Retrieve the associated template from the key
_template
, in this caseArticle.hbs
.Populate
Article.hbs
with values from its data fileArticle.json
.Place the populated template
Article.hbs
into the placeholder{{pageBody}}
inside the wrapper template.
_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
.
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 }
_image
If true, Styleguide and the back end retrieve available image attributes, such as height
and width
, from the configuration file _config.json
.
{ "_template": "/path/to/Image.hbs", 1 "image": { "_image": true, 2 "src": "/path/to/image.png" 3 } }
Indicates the template is | |
Specifies when evaluating the template's placeholder | |
Provides the path for the attribute |
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
.
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}}
Retrieves the value for the | |
Retrieves the values for the |
_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>
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 |
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" } }
Performs the following:
|
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.
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.
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.
_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.
_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" }
Indicates that any template selected in the Styleguide GUI is populated and inserted into the wrapping template's |
{ "_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." }
Prevents |
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.