Previewing Layout in the Styleguide

Brightspot’s Styleguide displays a preview of an article’s appearance based on a View. To render a preview, Styleguide incorporates character- and paragraph-level formatting, layout of elements, and other standard features in HTML and CSS code. Styleguide retrieves the layout from Handlebars files, and hydrates the preview using text from the JSON files. In this lesson, you’ll learn how to use the preview feature and modify the text used in the preview.

Step 1: Creating Styleguide Directory Structure

Move the Handlebars files you created in the previous lesson.

  • Move src/main/webapp/brightspot/tutorial/article/Article.hbs to styleguide/tutorial/article/.
  • Move src/main/webapp/brightspot/tutorial/page/Page.hbs to styleguide/tutorial/page/.

After moving the above files, your styleguide/ directory is as follows:

├── All.js
├── All.less
├── _config.json
└── tutorial
    ├── article
    |   └── Article.hbs
    └── page
        └── Page.hbs

Step 2: Opening Styleguide

In this step, you run and open Styleguide to view a preview of the article’s appearance.

  1. Ensure port 3000 on your local machine is open.
  2. Open a new command prompt (Windows) or Terminal (Mac/*nix), 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.

Step 3: Creating Styleguide JSON File for the Article

Styleguide’s JSON files serve two purposes:

  • Provide static text and images for the placeholders in Handlebars files; you can view the text and images in Styleguide’s preview.
  • Create Java interfaces for the Views, thereby ensuring the ViewModels implementing the interfaces provide the required methods and associated return types.
  1. Returning to the IDE, create the file Article.json in the directory styleguide/tutorial/article/, and enter the following text:
    "_template": "Article.hbs",
    "headline": "{{words(8)}}",
    "leadImageUrl": "{{image(400, 300)}}",
    "body": "{{paragraphs([2,3])}}"

In the previous snippet—

  • Line 2 indicates that this JSON file provides static text and generates interface methods for the placeholders in Article.hbs—the Handlebars file you created in Step 1: Adding the Article’s View.
  • Line 3 generates eight words of random text for the {{headline}} placeholder.
  • Line 4 creates an image 400 pixels wide by 300 pixes high, and places it in the {{leadImageUrl}} placeholder.
  • Line 5 generates three paragraphs of random text for the {{body}} placeholder.

Values in the JSON file surrounded by double braces are helpers. For a list of the helpers you can use in JSON files, see Value Helpers.

Step 4: Displaying 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.)

  2. Click Article. Styleguide displays static text and an image for the heading and body corresponding to the helpers you used in Step 3.


Step 5: Generating a View Interface

Brightspot automatically generates the View’s interface based on the template files you created in the previous steps.

  • Refresh the web page running at localhost:9480. The directory target/generated-sources/ now includes a Java interface styleguide/styleguide/tutorial/article/ (See the diagram in Project Structure Conventions.) You’ll refer to this interface when you create the view model class.