Tutorial

This tutorial walks through the three most common steps of a Styleguide project: templating, data evaluation, and styling. Before starting this tutorial, be sure you installed all of the items described in System Requirements.

Step 1: Create Project

  1. Open a terminal window and create a project as described in Creating a Styleguide Project.
  2. After creating the project, change to the directory <root>/styleguide/.

Step 2: 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:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
<!DOCTYPE html>
<html>
    <head>
        <title>{{headline}}</title>
        <link rel="stylesheet" type="text/css" href="/styleguide/All.min.css" />
    </head>

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

In the previous snippet—

  • Line 4 introduces a Handlebars placeholder {{headline}}. Styleguide populates all such placeholders with values from the data file you’ll create in Step 3.
  • Line 9 specifies a class name Article in an outer <div>, and line 10 specifies a class name Article-headline in an inner <div>. These class names and nested <div>s are part of the Block-Element-Modifier methodology. For more information about this methodology, see BEM.

Other than the Handlebars placeholders, a template looks just like a standard HTML file.

Step 3: 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:

    1
    2
    3
    4
    5
    {
      "_template": "/styleguide/article/Article.hbs",
      "headline": "Deadly Gamma Ray Burst Headed for Manny's Pizzeria",
      "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."
    }
    
  2. From the root directory (the directory that contains gulpfile.js), run gulp styleguide. Styleguide is running when you see the message Server started on http://localhost:3000/_styleguide/index.html.

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

  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.

../../_images/tutorial-nostyling.png

In the previous snippet—

  • Line 2 specifies a key _template that points to the template file Article.hbs you created in Step 2.
  • Line 3 specifies a key headline that corresponds to the Handlebars placeholder {{headline}} in the template file. At runtime, Styleguide injects the value for headline into the template.
  • Line 4 specifies a key body that corresponds to the Handlebars placeholder {{body}} in the template file. At runtime, Styleguide injects the value for body into the template.

Step 4: 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/, create a file All.less and enter the following text:

    @import 'article/Article';
    /* Ensure this file ends with a blank line */
    

    At runtime, Styleguide ingests all files appearing in All.less and creates a single file All.min.css for the entire project.

  3. Stop Styleguide’s server by pressing Ctrl-C.

  4. Restart the server by entering gulp 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.

../../_images/tutorial-styling.png

Step 5: Project Integration

Your complete Styleguide project has all of the source files needed to generate a frontend. You integrate the Styleguide project with the parent project by copying the directory <root>/styleguide/ into the appropriate directory of the parent project. If you are using Styleguide as part of deploying a Brightspot project, copy the directory <root>/styleguide/ into <brightspot-root>/.

../../_images/integration-with-brightspot.svg

Summary

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

See also: