Lesson 1: Create an Article content type

Brightspot’s backend is based on the Model-View-ViewModel pattern (for introductory information about this design pattern, see Model-view-viewmodel). In this lesson, you will take the first step in developing with the backend by creating a model that is a content type.

In a developer context, a content type is a Java class that represents a type of content. Examples of content types are articles, images, videos, and blogs. An item is an instantiation of a content type: an editor instantiates multiple articles (objects) of the article content type (class).

Content types include properties and methods that represent a publication’s business logic. The business logic typically specifies the fields and data validation rules that comprise a content type.

In this lesson you will create a content type for articles. Each article has a required headline, a rich-text field for writing the article’s body, and an associated image.

Step 1: Declare the Article class

In this step you declare a Java class for the article content type.

  1. In your IDE or in a new terminal window, change to the source-file directory brightspot-tutorial/init/src/main/java.

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

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

    1
    2
    3
    4
    5
    6
    7
    package article;
    
    import com.psddev.cms.db.Content;
    
    public class Article extends Content {
    
    }
    
  4. Refresh the dashboard. This step launches a background process that responds to changes in your code as you proceed through the lesson.

In the previous snippet, line 5 declares a class that extends from Content. Brightspot uses the class Content to render a content edit form.

Step 2: Add text fields to the article

In this step, you add two fields, headline and body, to the article content type.

  1. Update the file Article.java with the following highlighted lines:

    Simple content type with two text fields
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    package article;
    
    import com.psddev.cms.db.Content;
    
    public class Article extends Content {
    
        private String headline;
    
        private String body;
    
        public String getHeadline() {
            return headline;
        }
    
        public String getBody() {
            return body;
        }
    
    }
    
  2. Refresh the dashboard. A prompt appears in the right-hand side of the header to install the reloader. (If the prompt does not appear, halt the server in the terminal window by pressing Ctrl-C, restarting the server with ./run.sh or run.cmd, and then reloading the page in the browser.)

    ../../../_images/reloader.png
  3. Click the link to install the reloader. After installation the dashboard appears.

  4. In the dashboard’s header, click in the search field to open the search panel.

    ../../../_images/new-article.svg
  5. In the Create widget, select Article, and then click New. A form appears for adding a new article. (If Article is not available in the Create widget, reload the dashboard with the URL http://localhost:9480/cms/index.jsp?_reload=true.)

    ../../../_images/new-fields.png

In the snippet Simple content type with two text fields

  • Lines 7–9 declare the properties headline and body. Brightspot renders these properties as fields in a content edit form for articles.
  • Lines 11–17 are the getters for headline and body. The view-model you build in Lesson 3: Creating a view-model use the getters to retrieve content at run time. (In a production environment, you can also declare setters that can enforce data formatting rules, such as the correct syntax for dates or phone numbers.)

Brightspot displays the content edit form’s fields in the same order as they appear in the content type; in this example, the Headline field appears above the Body field. You can override the order in which fields appear using the annotations @ToolUi.DisplayAfter, @ToolUi.DisplayBefore, @ToolUi.DisplayFirst, and @ToolUi.DisplayLast.

Brightspot derives the labels Headline and Body from the field names headline and body. You can customize the field names using the annotation @Recordable.DisplayName.

Step 3: Make a field required

  1. Update the file Article.java with the following highlighted line:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    package article;
    
    import com.psddev.cms.db.Content;
    
    public class Article extends Content {
    
        @Required
        private String headline;
    
        private String body;
    
        public String getHeadline() {
            return headline;
        }
    
        public String getBody() {
            return body;
        }
    
    }
    
  2. Refresh the content edit form. The cue (Required) appears in the headline field. (If the cue does not appear, halt the server in the terminal window by pressing Ctrl-C, restarting the server with ./run.sh or run.cmd, and then reloading the page in the browser.)

    ../../../_images/required-field.png

In the previous snippet, the annotation @Required in line 7 specifies that the headline field is required. At run time, when an editor attempts to save an article with an empty headline, Brightspot displays an error.

The annotation @Required is available from the interface Recordable, which the class Content implements. Recordable provides many annotations for implementing data validation. For details, see Data Modeling Annotations.

Step 4: Add a rich-text editor

A rich-text editor (RTE) provides features available in word processors, such as character- and paragraph-level formatting, tables, and graphics. In this step, you annotate the body field to include an RTE.

  1. Update the file Article.java with the following highlighted lines:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    package article;
    
    import com.psddev.cms.db.Content;
    import com.psddev.cms.db.ToolUi;
    
    public class Article extends Content {
    
        @Recordable.Required
        private String headline;
    
        @ToolUi.RichText
        private String body;
    
        public String getHeadline() {
            return headline;
        }
    
        public String getBody() {
            return body;
        }
    
    }
    
  2. Refresh the content edit form. Brightspot renders the body field as an RTE. (If the toolbar does not appear in the Body field, halt the server in the terminal window by pressing Ctrl-C, restarting the server with ./run.sh or run.cmd, and then reloading the page in the browser.)

    ../../../_images/rte-editor.png

In the previous snippet, the annotation @ToolUi.RichText in line 11 specifies that the body field is rendered as an RTE. The class ToolUi has many annotations for rendering data-entry fields. For details, see Content Modeling Annotations.

Step 5: Add an image to the content type

In this step you add a field that represents an image.

  1. Update the file Article.java with the following highlighted lines:

    Simple content type with text and image fields
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    package article;
    
    import com.psddev.cms.db.Content;
    import com.psddev.cms.db.ToolUi;
    import com.psddev.dari.util.StorageItem;
    
    public class Article extends Content {
    
        @Required
        private String headline;
    
        @ToolUi.RichText
        private String body;
    
        private StorageItem image;
    
        public String getHeadline() {
            return headline;
        }
    
        public String getBody() {
            return body;
        }
    
        public StorageItem getImage() {
            return image;
        }
    
    }
    
  2. Refresh the content edit form. The content edit form now has a field for adding an image. (If the Image field does not appear, halt the server in the terminal window by pressing Ctrl-C, restarting the server with ./run.sh or run.cmd, and then reloading the page in the browser.)

    ../../../_images/image-field.png

In the previous snippet—

  • Line 5 imports the class StorageItem. Brightspot uses the class StorageItem to manage binary files, such as displaying a preview of an image in the content edit form and automatically assigning it a URL.
  • Line 15 adds a StorageItem to the article content type.
  • Lines 25–27 provide the image’s getter.

Step 7: Compose an article

Now that you have a content type for articles, it is time for you to write an article announcing the arrival of aliens on our planet.

  1. In your browser, reload the dashboard.

  2. In the Quick Start widget, click Article. The content edit page appears.

  3. In the Headline field, enter the article’s headline.

  4. In the Body field, enter the article’s body.

  5. In the Image field, select New URL, and enter the URL of an image depicting extra-terrestrial creatures, such as https://spaceplace.nasa.gov/review/voyager-to-stars/aliens_200.en.jpg.

  6. Click Publish. Your content edit page looks similar to the following:

    ../../../_images/populated-article.png

Referring to the previous illustration—

  • The Body field includes rich text, including the word Hamilton set in italics.
  • Brightspot displays a thumbnail of the image in the content edit form. This is a feature provided by the StorageItem class.
  • Brightspot assigns a permalink in the URLs widget. The permalink is a normalized transformation of the value in the Headline field.

Summary

In this lesson, you learned the following:

  • How Brightspot uses properties in the class Content (which implements Recordable) to render a content edit page.
  • How to create a content type and add fields to that type.
  • How to render text fields as a rich-text editor.
  • How to include an image in a content type.
  • How to generate permalinks.