Creating an Article Model

An article’s Model represents the business logic and data validation associated with an article. The business logic typically specifies which components comprise an article, and data validation describes how those components are populated.

Step 1: Declaring the Article Class

In this step you declare a Java class for articles.

  1. In an IDE or text editor, create the file Article.java in the directory src/main/java/brightspot/tutorial/article/, and enter the following text:
package brightspot.tutorial.article;

import com.psddev.cms.db.Content;

public class Article extends Content {

}
  1. Refresh the web page running at localhost:9480. This step launches a background process that responds to changes in your code as you proceed through the tutorial.

Step 2: Adding Text Fields to the Article Model

In the MVVM pattern, the Model includes business logic. In this step, you implement business logic stating that an article has two text components: a headline and a body.

  1. Returning to the IDE, update the file Article.java with the following:
 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
package brightspot.tutorial.article;

import com.psddev.cms.db.Content;

public class Article extends Content {

    private String headline;

    private String body;

    public String getHeadline() {
        return headline;
    }

    public void setHeadline(String headline) {
        this.headline = headline;
    }

    public String getBody() {
        return body;
    }

    public void setBody(String body) {
        this.body = body;
    }

}
  1. Refresh the web page running at localhost:9480. A prompt appears in the right-hand side of the header to install the reloader. (If the prompt does not appear, skip to step 4.)

    ../../../_images/reloader.png
  2. Click the link to install the reloader. After installation the Dashboard appears.

  3. In the Dashboard’s header, click in the search field, and in the panel that opens click New to create a new article.

../../../_images/new-article.svg

A form appears for adding a new article.

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

In the previous snippet—

  • The properties headline and body in lines 7 and 9 indicate your article has headline and body fields.
  • The setter and getter methods in lines 11–25 save and retrieve the current values of those fields.

Step 3: Making a Field Required

In addition to business logic, the MVVM Model also specifies data validation. In this step, you include a validation rule that each article must have a headline.

  1. Returning to the IDE, update the file Article.java with the following:
 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
package brightspot.tutorial.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 void setHeadline(String headline) {
        this.headline = headline;
    }

    public String getBody() {
        return body;
    }

    public void setBody(String body) {
        this.body = body;
    }

}

In the previous snippet, the annotation @Required in line 7 specifies that the headline field is required. (This annotation is available from Interface Recordable, which Class Content implements.) Brightspot has many @Recordable annotations for implementing data validation. For details, see Annotations.

Step 4: Adding a Rich-Text Editor

A rich-text editor (RTE) provides controls for formatting at the character and paragraph level. In this step, you recast the body field to include an RTE.

  1. Returning to the IDE, update the file Article.java with the following:
 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
30
package brightspot.tutorial.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 void setHeadline(String headline) {
        this.headline = headline;
    }

    public String getBody() {
        return body;
    }

    public void setBody(String body) {
        this.body = body;
    }

}
  1. Refresh the web page running at localhost:9480. The headline field has a hint that it is required, and the body field is rendered as an RTE.
../../../_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. Brightspot has many @ToolUi annotations for rendering data-entry fields. For details, see Annotations.

Step 5: Creating an Image Package

In this step you create a package for images. In a later step you’ll import this package into the article’s Model.

In an IDE or text editor, create the file Image.java in the directory src/main/java/brightspot/tutorial/image/, and enter the following text:

 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 brightspot.tutorial.image;

import com.psddev.cms.db.Content;
import com.psddev.dari.db.Recordable;
import com.psddev.dari.util.StorageItem;

@Recordable.PreviewField("file")
public class Image extends Content {

    private String title;

     private StorageItem file;

     public String getTitle() {
         return title;
     }

     public void setTitle(String title) {
         this.title = title;
     }

     public StorageItem getFile() {
         return file;
     }

     public void setFile(StorageItem file) {
         this.file = file;
     }
}

In the previous snippet—

  • The @Recordable.PreviewField annotation in line 7 indicates that Brightspot displays the actual image file in the Content Edit Form.
  • Lines 10 and 12 indicate that each Image object has a title and a file. Line 12 introduces the StorageItem class, which is a high-level Dari class for working with files, particularly graphic, video, and audio.
  • The setter and getter methods in lines 14–28 save and retrieve the current values for the title and file.

Step 6: Add Image to Article

In this step you import the image package from the previous step, and use that package to add a lead image field to the article’s model.

  1. Returning to the IDE, update the file Article.java with the following:
 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
30
31
32
33
34
35
36
37
38
39
40
41
42
package brightspot.tutorial.article;

import brightspot.tutorial.image.Image;

import com.psddev.cms.db.Content;
import com.psddev.cms.db.ToolUi;

public class Article extends Content {

    @Required
    private String headline;

    private Image leadImage;

    @ToolUi.RichText
    private String body;

    public String getHeadline() {
        return headline;
    }

    public void setHeadline(String headline) {
        this.headline = headline;
    }

    public Image getLeadImage() {
        return leadImage;
    }

    public void setLeadImage(Image leadImage) {
        this.leadImage = leadImage;
    }

    public String getBody() {
        return body;
    }

    public void setBody(String body) {
        this.body = body;
    }

}
  1. Refresh the web page running at localhost:9480. The content edit form now has a field for adding an image.
../../../_images/image-field.png

In the previous snippet—

  • Line 3 imports the image package you created in the previous step.
  • Line 13 adds an Image field to the article’s Model. Brightspot displays the content edit form’s fields in the same order as they appear in the Model. (See Annotations for a list of annotations you can use to override this order.)
  • Lines 26–32 provide the image’s getter and setter.

Step 7: Composing an Article

Now that you have a Model, it’s time for you to write an article announcing the arrival of aliens on our planet.

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

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

  3. In the Lead Image field, do the following:

    1. Click in the field. The Content Picker appears.

    2. Click New Image. A new content edit form appears.

    3. In the Title field, type a title.

    4. From the File field, select New URL and enter a URL such as https://spaceplace.nasa.gov/review/voyager-to-stars/aliens_200.en.jpg.

      ../../../_images/new-image.png
    5. Click Save Draft. The image appears in the content edit form, and is now saved on your local Brightspot server.

    6. Click Publish. Publishing makes the image available to published articles that contain the image.

    7. Click Back to Select Lead Image. You return to the content picker displaying the new image.

      ../../../_images/new-image-in-content-picker.png
    8. Click the new image. You return to the article’s content edit form displaying the selected image.

    ../../../_images/populated-article.png
  4. Click Save Draft.

Summary

In this lesson you learned the following skills:

  • How to create a Model.
  • How to add different types of fields to a model.
  • How to incorporate one Model into another.