Tutorial Setup

This section describes what you need to have to complete the Brightspot tutorial.

Software Requirements

You’ll need the following software to complete this tutorial.

Time Required

Estimated time to complete this tutorial is 30 minutes.

What You Should Know

To successfully complete this tutorial you should know or understand the following:

  • Java
  • Git
  • Java IDE or text editor
  • HTML
  • Basic understanding of Handlebars and JSON files

Download and Run the Brightspot Tutorial Project

  1. Ensure port 9480 on your local machine is open, and ensure you have an environment variable JAVA_HOME pointing to <jdk_root>, such as to /usr/local/java/jdk/jdk1.8.0_121/.

  2. Open a command prompt (Windows) or Terminal (Mac/*nix), and change to a directory where you want to install the Brightspot project.

  3. At the command line, type git clone https://github.com/perfectsense/brightspot-tutorial.

  4. Change the current directory to brightspot-tutorial/init/.

  5. Type ./run.sh (Linux, OS X) or run.cmd (Windows). The installation script requires about three minutes to download components, compile, and display at http://localhost:9480/cms/logIn.jsp. A form for entering a username and password appears.

  6. Enter your username and password, and click Log In. The Dashboard appears.

  7. If you are using an IDE, import the Brightspot project starting from the directory brightspot-tutorial/init/.

Project Structure Conventions

Brightspot projects are comprised of the following components:

  • Back-end code—Java code implementing the Model and ViewModel. Back-end files are stored in the directory src/main/java/.
  • Front-end code—JSON, Handlebars, JavaScript, CSS, and Less files implementing the View. Front-end files are stored in the directory styleguide/.
  • Automatically generated code—Code that Brightspot automatically generates when building the project. These files are under target/generated-sources/styleguide/<dir>/ in directories parallel to the JSON files. The value for <dir> is configured in the javaPackage key of the file styleguide/_config.json. For example, if your file styleguide/_config.json has a line "javaPackage" : "styleguide", and the JSON file is in the directory styleguide/tutorial/, then Brightspot generates files in the directory target/generated-sources/styleguide/styleguide/tutorial/.

A best practice is to create a dedicated subdirectory for a project, and then dedicated subdirectories for each type of content. Referring to the following diagram, the dedicated subdirectory for the project is brightspot/tutorial/, and the dedicated subdirectories for each type of content are article/, image/, and page/. (You’ll be working with these subdirectories during these tutorials.)

└── <root>
    ├── src
    |   └── main
    |       └── java
    |           └── brightspot
    |               └── tutorial
    |                   ├── article
    |                   |   ├── Article.java
    |                   |   └── ArticleViewModel.java
    |                   ├── image
    |                   |   └── Image.java
    |                   └── page
    |                       └── PageViewModel.java
    ├── styleguide
    |   ├── All.js
    |   ├── All.less
    |   ├── _config.json
    |   ├── _wrapper.json
    |   └── tutorial
    |       ├── article
    |       |   ├── Article.json
    |       |   ├── Article.less
    |       |   └── Article.less
    |       └── page
    |           ├── Page.hbs
    |           └── Page.less
    └── target
        └── generated-sources
            └── styleguide
                └── styleguide
                    └── tutorial
                        ├── article
                        |   └── ArticleView.java
                        └── page
                            ├── PageView.java
                            └── PageViewBodyField.java