Theming tutorial
In this tutorial, you develop a simple theme that includes a data file, template, and stylesheet. You also become familiar with Styleguide, Brightspot's theming development environment. If you created the back-end tutorial in Tutorial, you'll be able to install this theme into that tutorial.
What you should know
To successfully complete this tutorial you should know or understand the following:
Cloning a repository with git.
Running commands in a terminal.
Basic knowledge of HTML, CSS, and Less.
Basic knowledge of JSON.
Software requirements
You'll need the following software to complete this tutorial.
Git
nvm version 8.9.3
yarn
Port 8080 open on your localhost
This tutorial is platform-independent, so you can run it on Windows, OS X, or Linux.
Install and run the theming tutorial project
This section describes how to install the tutorial project and run Styleguide.
Open a command window, and change to any directory.
Clone the Brightspot repository: git clone https://github.com/perfectsense/brightspot-demo.git.
Ensure you use the correct version of node: nvm use v.8.9.3.
Change to the theming directory: cd brightspot-demo/theme/.
Install packages: yarn.
Build and run the Styleguide server: yarn server:styleguide.
In a web browser, go to http://localhost:8080/_styleguide/index.html. The Styleguide UI appears.
Theming directory structure
The following illustration shows the contents of the theme/
directory in the repository brightspot-demo/
.
Directory where Brightspot outputs built themes. | |
Root directory for the theme's source files. | |
Theme's configuration file. | |
Directory for a content type's source files. |
As a best practice, organize your theming projects using the following guidelines:
Every content type has its own directory with the same name as the content type. For example, if you have two content types
recipes
andchefs
, create subdirectoriesrecipes/
andchefs/
understyleguide/
. (If you are adding styling using Less, you must place your content-type files in a subdirectory.)In the root directory, create a file
All.less
and@import
all of the subsidiary Less files into it. When building a theme, Brightspot creates a minified fileAll.min.css
that contains all of your CSS selectors for the entire project.In the root directory, create a file
All.js
andimport
the classes you want to include in your deployed project. When building a theme, Brightspot collects all imported JavaScript files into a minified fileAll.min.js
.
Step 1: Create template
In this step you create the HTML layout for an article.
In the directory
styleguide/
create a subdirectoryarticle/
.Change to the subdirectory
article/
.Create a file
Article.hbs
and enter the following text:
<!DOCTYPE html> <html> <head> <title>{{headline}}</title> 1 <link rel="stylesheet" type="text/css" href="/styleguide/All.min.css" /> </head> <body> <div class="Article"> 2 <div class="Article-headline"> {{headline}} </div> <div class="Article-body"> {{body}} </div> </div> </body> </html>
Introduces a placeholder | |
Specifies a class name |
Other than the placeholders, a template looks just like a standard HTML file.
Step 2: Create data file
In this step you create a data file that populates the template with mock data.
In the directory
article/
create a fileArticle.json
and enter the following text:Example 63. Tutorial data file{ "_template": "Article.hbs", 1 "headline": "Deadly Gamma Ray Burst Headed for Manny's Pizzeria", 2 "body": "Sensitive radio telescopes in the isolated Canary Islands have detected a deadly gamma ray burst originating in an outer spiral of the Milky Way Galaxy. Instrumentation aboard European satellites confirm that the burst is headed for Manny's Pizzeria in mid-town Manhattan, home to the city's most cherished tomato sauce recipe." 3 }
Specifies a key
_template
that points to the templateArticle.hbs
you created in Step 2.Specifies a key
headline
that corresponds to the placeholder{{headline}}
in the template. At runtime, Styleguide injects the value forheadline
into the template.Specifies a key
body
that corresponds to the placeholder{{body}}
in the template. At runtime, Styleguide injects the value forbody
into the template.From the root
styleguide/
directory, run yarn server:styleguide. Styleguide is running when you see the messageServer started on http://localhost:3000/_styleguide/index.html
.In your browser, open Styleguide at
http://localhost:3000/_styleguide/index.html
.Click the link for
Article
. Styleguide displays the article using the HTML structure from the template and the mock data from the data file.

Step 3: Create styling
In this step you add styling for your article.
In the directory
article/
create a fileArticle.less
and enter the following text:.Article { color: black; font-family: sans-serif; &-headline { font-size: 26px; font-weight: bold; color: red; margin-bottom: 0.5em; } &-body { font-size: 16px; margin-bottom: 0.5em; } } /* Ensure this file ends with a blank line */
The previous snippet introduces Less syntax. For detailed information about these types of files, see {less}.
In the directory
styleguide/
, open the fileAll.less
and enter the following text:@import 'article/Article'; /* Ensure this file ends with a blank line */
At build time, Brightspot ingests all files appearing in
All.less
and creates a single fileAll.min.css
for the entire project.In the terminal window, stop Styleguide's server by pressing Ctrl-C.
Restart the server by entering yarn server:styleguide. Styleguide is running when you see the message
Server started on http://localhost:3000/_styleguide/index.html
.Refresh Styleguide in your browser and click the link for Article. The article appears with the specified styling.

Summary
In this tutorial you learned the basics of a simple theming project: templating, data files, and styling. The other sections in this guide describe the many features available for importing and referencing files, and using dynamic values to minimize and organize the coding effort.