Support and Documentation

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.

Procedure. To install and run the tutorial project:

  1. Open a command window, and change to any directory.

  2. Clone the Brightspot repository: git clone https://github.com/perfectsense/brightspot-demo.git.

  3. Ensure you use the correct version of node: nvm use v.8.9.3.

  4. Change to the theming directory: cd brightspot-demo/theme/.

  5. Install packages: yarn.

  6. Build and run the Styleguide server: yarn server:styleguide.

  7. In a web browser, go to http://localhost:8080/_styleguide/index.html. The Styleguide UI appears.

    styleguide-running.png

Theming directory structure

The following illustration shows the contents of the theme/ directory in the repository brightspot-demo/.

Example 62. Directory structure for theming tutorial project

theme/ ├── _build/ 1 └── styleguide/ 2 ├── All.js ├── All.less ├── _config.json 3 └── article/ 4 ├── Article.hbs ├── Article.json └── Article.less



1

Directory where Brightspot outputs built themes.

2

Root directory for the theme's source files.

3

Theme's configuration file.

4

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 and chefs, create subdirectories recipes/ and chefs/ under styleguide/. (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 file All.min.css that contains all of your CSS selectors for the entire project.

  • In the root directory, create a file All.js and import the classes you want to include in your deployed project. When building a theme, Brightspot collects all imported JavaScript files into a minified file All.min.js.

Step 1: Create template

In this step you create the HTML layout for an article.

  1. In the directory styleguide/ create a subdirectory article/.

  2. Change to the subdirectory article/.

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

1

Introduces a placeholder {{headline}}. Styleguide populates all such placeholders with values from the data file you'll create in Step 3.

2

Specifies a class name Article in an outer <div> and class names Article-headline and Article-body in inner <div>s. These class names and nested <div>s are part of the Block-Element-Modifier methodology. For more information about this methodology, see Get BEM.

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.

  1. In the directory article/ create a file Article.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
}

    1

    Specifies a key _template that points to the template Article.hbs you created in Step 2.

    2

    Specifies a key headline that corresponds to the placeholder {{headline}} in the template. At runtime, Styleguide injects the value for headline into the template.

    3

    Specifies a key body that corresponds to the placeholder {{body}} in the template. At runtime, Styleguide injects the value for body into the template.



  2. From the root styleguide/ directory, run yarn server:styleguide. Styleguide is running when you see the message Server started on http://localhost:3000/_styleguide/index.html.

  3. In your browser, open Styleguide at http://localhost:3000/_styleguide/index.html.

  4. Click the link for Article. Styleguide displays the article using the HTML structure from the template and the mock data from the data file.

tutorial-nostyling.png

Step 3: Create styling

In this step you add styling for your article.

  1. In the directory article/ create a file Article.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}.

  2. In the directory styleguide/, open the file All.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 file All.min.css for the entire project.

  3. In the terminal window, stop Styleguide's server by pressing Ctrl-C.

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

  5. Refresh Styleguide in your browser and click the link for Article. The article appears with the specified styling.

tutorial-styling.png

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.