Support and Documentation

Lesson 2: Creating a front end

In this lesson, you will acquire an understanding of Styleguide, the tool Brightspot representatives use to create a front end. You will also develop a template that provides the HTML structure for your published article.

Step 1: Prepare for this lesson

Before starting this lesson,

  1. Complete Lesson 1: Create an Article content type.

  2. If you stopped the Brightspot server, do the following:

    1. Restart it by typing ./run.sh (Linux, OS X) or run.cmd (Windows). The login page appears in your browser at localhost:9480.

    2. Log in to display the dashboard.

  3. If you stopped the Styleguide server, restart it by typing gulp styleguide.

Step 2: Start Styleguide

In this step, you run Styleguide to view a preview of an article's appearance.

  1. Ensure port 3000 on your local machine is open.

  2. Open a new terminal window, and change the current directory to brightspot-tutorial/init/.

  3. Run gulp styleguide. A server starts.

  4. In your web browser, open http://localhost:3000/_styleguide. A blank Styleguide appears.

styleguide-blank.png
Step 3: Create a template

A template is an HTML file with placeholders for variables. Brightspot's templates are based on Handlebars.

  1. Open a new terminal window, and change to the directory brightspot-tutorial/init/styleguide.

  2. Create the directory article, and change to that directory.

  3. Create the file Article.hbs (see the illustration Tutorial project structure), and enter the following text:

    Example 5. Template
    <!DOCTYPE html>
<html>

    <head>
        <meta charset="UTF-8">
        <title>{{headline}}</title> 1
    </head>

    <body>
        <div> 2
            <div>
                <h1>{{headline}}</h1> 3
            </div>
            <div>
                {{body}} 4
            </div>
            <div>
                <img src="{{imageUrl}}" height="300"> 5
            </div>
        <div>
    </body>

</html>

    1

    Declares a title tag, the value of which is a variable headline. (Literals in {{double braces}} are placeholders for dynamic content.)

    2

    Opens an empty div tag. You will return to this tag when you apply styling.

    3

    Declares an h1 tag, the value of which is a variable headline.

    4

    Declares a placeholder for the article's variable body.

    5

    Declares an image tag, the source of which is a variable URL.



Brightspot populates the placeholders when a client requests an article. Brightspot retrieves the values from the view model, which you will learn about in Lesson 3: Creating a view model, and injects the values into the placeholders.

Step 4: Create a data file

Styleguide's data files serve two purposes:

  • Providing mock data appearing in Styleguide's preview.

  • Creating Java interfaces for the views.

  • Still in the directory brightspot-tutorial/init/styleguide/article/, create the file Article.json (see the illustration Tutorial project structure), and enter the following text:

    Example 6. Sample data file
    {
  "_template": "Article.hbs", 1
  "headline": "{{words(4)}}", 2
  "body": "{{paragraphs([1])}}", 3
  "imageUrl": "{{image(400, 200)}}" 4
}

    1

    Indicates that this data file provides mock values for the template Article.hbs you created in Step 3: Create a template.

    2

    Uses the helper words() to generate four words of random text for the {{headline}} placeholder. For information about this helper, see words.

    3

    Uses the helper paragraphs() to generate one paragraph of random text for the {{body}} placeholder. For information about this helper, see paragraphs.

    4

    Uses the helper image() to generate a mock URL for the {{imageUrl}} placeholder. For information about this helper, see image.



For a list of the helpers you can use in data files, see Value helpers.

Step 5: Display the Styleguide preview

  1. Refresh the web page running at localhost:3000/_styleguide. An entry for the article appears. (If you do not see an entry for the article, in the terminal press Ctrl-C to stop the server and then rerun gulp styleguide.)

    styleguide-article.png

  2. Click Article. Styleguide displays mock text and an image for the placeholders you used in Step 3: Create a template.

    styleguide-default.png
Step 6: Generate the view interface

  1. In a new terminal window, change to brightspot-tutorial/init/.

  2. Run ../mvnw clean package.

Brightspot generates the view interface in the file brightspot-tutorial/init/target/generated-sources/styleguide/com/psddev/styleguide/article/ArticleView.java (see the illustration Tutorial project structure). The interface includes the methods getHeadline, getBody, and getImageUrl, corresponding to the keys headline, body, and imageUrl in the data file you created in Step 4: Create a data file. You will refer to this interface when you create the view-model class.

Summary

In this lesson, you learned the following:

  • A template provides the HTML structure of a published article. A template includes placeholders into which Brightspot injects dynamic content at run time.

  • A data file defines the fields appearing in a template. Brightspot uses a data file to create the view interfaces, as well as to provide mock data for the Styleguide preview.

  • Styleguide provides a preview of how a client renders a template.