Content edit widgets

Content edit widgets are widgets that appear on an editor’s content edit page. Brightspot comes with standard widgets such as Revisions and URLs. You can also create your own custom content edit widgets, and you can configure the standard and custom content edit widgets.

Creating content edit widgets

You can create widgets that appear in the content edit page by extending the abstract class ContentEditWidget. That abstract class includes three abstract methods that you must override, all of which support displaying read-only data.

The following snippet shows an entire class for displaying the custom widget Current Time Zones in the content edit page. The custom widget lists several cities and their current time.

1
import com.psddev.cms.tool.*;
2

3
public class CurrentTimesWidget extends ContentEditWidget {
①
4

5
    @Override
6
    public void display(ToolPageContext page, Object content, ContentEditWidgetPlacement placement) throws IOException {
7
        Map<String, String> timeZoneIdentifiers = new HashMap<>();
②
8
        timeZoneIdentifiers.put("New York", "America/New_York");
9
        timeZoneIdentifiers.put("Los Angeles", "America/Los_Angeles");
10
        timeZoneIdentifiers.put("Mexico City", "America/Mexico_City");
11

12
        page.writeStart("table");
13

14
            page.writeStart("tr");
③
15
                page.writeStart("th");
16
                    page.writeHtml("City");
17
                page.writeEnd(); /* th */
18
                page.writeStart("th");
19
                    page.writeHtml("Time");
20
                page.writeEnd(); /* th */
21
            page.writeEnd(); /* tr */
22

23
            for (String myTimeZone : timeZoneIdentifiers.keySet()) {
④
24
                page.writeStart("tr");
25
                    page.writeStart("td");
26
                        page.writeHtml(myTimeZone);
27
                    page.writeEnd(); /* td */
28
                    page.writeStart("td");
29
                        String localTime = displayTime(timeZoneIdentifiers.get(myTimeZone));
30
                        page.writeHtml(localTime);
31
                    page.writeEnd(); /* td */
32
                page.writeEnd(); /* tr */
33
            }
34
        page.writeEnd(); /* table */
35
    }
36

37
    public ContentEditWidgetPlacement getPlacement(ToolPageContext page, Object content) {
⑤
38
        return ContentEditWidgetPlacement.BOTTOM;
39
    }
40

41
    public String getHeading(ToolPageContext page, Object content) {
⑥
42
        return "Current Times";
43
    }
44

45
    private String displayTime(String timeZoneIdentifier) {
46
        /*
47
            Returns local time in hh:mm format based on
48
            passed time zone identifier.
49
        */
50
    }
51
}

• ①Declares the class CurrentTimesWidget. Objects instantiated from this class appear as Current Times Widget in the content edit page.
• ②Instantiates a HashMap of time zones.
• ③Writes a table header in the widget’s body.
• ④Loops through each time-zone record. For each record, call the method displayTime to retrieve and then print the time zone’s current time.
• ⑤Positions the widget under the content edit form. For details about positioning a widget on the content edit form, see Position.
• ⑥Displays the widget’s heading.

Based on the previous snippet, the custom widget Current Times appears at the bottom of the content edit page.

Creating content edit widgets that update

The content edit page includes an updating URLs widget that contains traditional HTML form tags such as <textarea> and <select>. You can create custom updating widgets that provide web forms in the content edit page by extending UpdatingContentEditWidget—an abstract class that includes the abstract method displayOrUpdate you must override in addition to the abstract methods described in Creating content edit widgets. These widgets respond to events and instantiate custom objects for data validation and posting content to the database.

In the following example you create a widget for attributing an article to a reporter—a typical task in a ghost-writing scenario.

Step 1: Create reporter model

In this step, you create a simple model to hold reporters’ first and last names.

1
public class Reporter extends Content {
①
2

3
    private String firstName;
4
    private String lastName;
5

6
    /* Getters and setters */
7

8
    public String getFullName() {
②
9
        return getFirstName() + " " + getLastName();
10
    }
11
}

• ①Declares the class Reporter that extends from Content. In a more robust implementation, you might create the class Reporter that extends ToolUser, create the class ReporterRole that extends ToolRole, and then assign instances of Reporter to ReporterRole.
• ②Returns a reporter’s full name as a concatenation of the reporter’s first and last name.

Step 2: Add field to model, hide from content edit form

By default, Brightspot places all of a model’s fields in the content edit form. In this example, you are attributing an article to a reporter, so a reporterCredit field must be part of the article’s model. Because reporterCredit appears in an updating content edit widget, you must use the @ToolUi.Hidden annotation in the model to remove the field from the content edit form.

1
public class Article extends Content {
2

3
    @ToolUi.Hidden
4
    private Reporter reporterCredit;
5

6
    public Reporter getReporterCredit() {
7
        return reporterCredit;
8
    }
9
}

Step 3: Display custom updating widget in content edit page

1
import com.psddev.cms.tool.ContentEditWidgetPlacement;
2
import com.psddev.cms.tool.ToolPageContext;
3
import com.psddev.cms.tool.UpdatingContentEditWidget;
4
import com.psddev.dari.db.Query;
5
import content.article.*;
6

7
public class ReporterCreditWidget extends UpdatingContentEditWidget {
①
8

9
    @Override
10
    public void displayOrUpdate(ToolPageContext page, Object content, ContentEditWidgetPlacement placement) throws IOException {
②
11

12
        Article myArticle = (Article) content;
③
13

14
        if (placement == null) {
④
15
            UUID reporterID = page.param(UUID.class, "reporter.select");
⑤
16
            Reporter creditedReporter = Query.from(Reporter.class).where("id = ?", reporterID).first();
⑥
17
            myArticle.setReporterCredit(creditedReporter);
⑦
18
            return;
19
        }
20

21
        List<Reporter> reporters = Query.from(Reporter.class).selectAll();
⑧
22
        Reporter currentReporter = myArticle.getReporterCredit();
⑨
23

24
        page.writeStart("select", "name", "reporter.select");
⑩
25
            page.writeStart("option", "value", "").writeEnd(); /* Initial blank option */
26
            for (Reporter reporter : reporters) {
27
                page.writeStart("option", "selected", reporter.equals(currentReporter) ? "selected" : null, "value", reporter.getId());
28
                    page.writeHtml(reporter.getFullName());
29
                page.writeEnd(); /* option */
30
            }
31
        page.writeEnd(); /* select */
32
    }
33

34
    @Override
35
    public ContentEditWidgetPlacement getPlacement(ToolPageContext page, Object content) {
⑪
36
        return ContentEditWidgetPlacement.RIGHT;
37
    }
38

39
    @Override
40
    public String getHeading(ToolPageContext page, Object content) {
⑫
41
        return "Reporter Credit";
42
    }
43

44
    @Override
45
    public boolean shouldDisplay(ToolPageContext page, Object content) {
⑬
46
        return content instanceof Article;
47
    }
48
}

• ①Declares the class ReporterCreditWidget as a subclass of an updating content widget.
• ②Callback for displaying or updating a content edit widget.
• ③Casts the incoming asset as an Article.
• ④Traps the widget’s update event.
• ⑤Retrieves the selected reporter’s UUID.
• ⑥Retrieves the Reporter record matching the selected reporter’s UUID.
• ⑦Assigns the retrieved reporter record to the article.
• ⑧Retrieves all of the reporters.
• ⑨Retrieves the current article’s reporter credit.
• ⑩Renders the widget's bgody with an HTML <select> field. The field’s options are a default blank entry and the list of retrieved reporters.
• ⑪Positions the widget in the right rail.
• ⑫Displays the widget’s heading Reporter Credit.
• ⑬Displays the widget if the current content type is an article.

Based on the previous snippet, the custom updating content widget Reporter Credit appears in the right rail of the content edit page.

Position

The position of a widget refers to its location relative to other widgets with the same placement. The following sections describe Brightspot’s default positioning logic as well as techniques for overriding that logic.

Default positioning

Within the same Placement (top, bottom, right, dedicated tab), Brightspot by default positions custom widgets in alphabetical order based on the class’s fully qualified name. For example, suppose you defined three custom widgets, widgets.AdamsCustomWidget, widgets.JacksCustomWidget, and specials.widgets.ZoesCustomWidget, and all of them appear under the content edit form. By default, Brightspot positions them in alphabetical order as in the following illustration.

Custom positioning

You can override the alphabetical sorting for custom widgets by implementing the method ContentEditWidget#getPosition and returning a double value. Values with smaller numbers appear closer to the top, and the default value is zero. Positions with the same value are sorted alphabetically by fully qualified class name.

1
import com.psddev.cms.tool.ContentEditWidget;
2
import com.psddev.cms.tool.ContentEditWidgetPlacement;
3
import com.psddev.cms.tool.ToolPageContext;
4

5
public class JillsCustomWidget extends ContentEditWidget {
6

7
    @Override
8
    public ContentEditWidgetPlacement getPlacement(ToolPageContext toolPageContext, Object o) {
①
9
        return ContentEditWidgetPlacement.BOTTOM;
10
    }
11

12
    @Override
13
    public double getPosition(ToolPageContext page, Object content, ContentEditWidgetPlacement placement) {
②
14
        return 8.0;
15
    }
16

17
    @Override
18
    public String getHeading(ToolPageContext page, Object content) {
19
        return "Jill's Custom Widget";
20
    }
21

22
    @Override
23
    public void display(ToolPageContext page, Object content, ContentEditWidgetPlacement placement) throws IOException {
24
        page.writeStart("p");
25
        page.writeHtml("Here is Jill's custom widget.");
26
        page.writeEnd();
27
    }
28
}

• ①Places Jill’s widget under the content edit form.
• ②Assigns Jill’s widget a relative position of 8.0

Suppose you assign Zoe’s, Adam’s, Jack’s, and Jill’s widgets return values for getPosition as in the following table.

Example values for positioning widgets

Widget	Fully Qualified Class Name	getPlacement	getPosition
Zoe	special.widgets.ZoesCustomWidget	ContentEditWidgetPlacement.BOTTOM	10.0
Adam	widgets.AdamsCustomWidget	ContentEditWidgetPlacement.BOTTOM	10.0
Jack	widgets.JacksCustomWidget	ContentEditWidgetPlacement.BOTTOM	8.0
Jill	widgets.JillsCustomWidget	ContentEditWidgetPlacement.BOTTOM	9.0

Because all the widgets have the same placement, Brightspot lays them out as in the following illustration.

Both Zoe’s and Adam’s widgets have the same return value for getPosition, so Brightspot breaks the tie by sorting by fully qualified class name.

Custom positioning with substitution

If you use a custom widget that is imported from another package, that widget may have a result from getPosition that conflicts with your implementation. Referring to the table "Example values for positioning widgets," Zoe’s custom widget has a position of 10, but you may want to place her widget first, in front of all the other custom widgets.

You can use substitutions to incorporate an imported widget into your project and then override the original value for getPosition.

At run time, the ported custom widget appears first among all other custom widgets under the content edit form.

1
import com.psddev.cms.tool.ContentEditWidgetPlacement;
2
import com.psddev.cms.tool.ToolPageContext;
3
import com.psddev.dari.db.Substitution;
4
import special.widgets.ZoesCustomWidget;
①
5

6
public class ZoesPortedCustomWidget extends ZoesCustomWidget implements Substitution {
②
7

8
    @Override
9
    public double getPosition(ToolPageContext page, Object content, ContentEditWidgetPlacement placement) {
③
10
        return 6.0;
11
    }
12

13
}

• ①Imports the custom widget ZoesCustomWidget from another package.
• ②Declares a ported custom widget ZoesPortedCustomWidget by extending the imported custom widget and implementing Substitution.
• ③Overrides the imported widget’s position, now assigning it 6 (compared to the original 10 as listed in the table "Example values for positioning widgets"). This position value is the lowest of all other custom widgets.

At run time, the ported custom widget appears first among all other custom widgets under the content edit form.

Placement

The placement of a widget refers to its location relative to the content edit form: top, bottom, right, or in its own tab. You provide a placement for a custom widget by implementing the method ContentEditWidget#getPlacement.

1
public ContentEditWidgetPlacement getPlacement(ToolPageContext page, Object content) {
2
    /* Return one of the placement constants. */
3
}

See the snippet "Implementing a custom widget in content edit page" for an implementation of this method.

The following table lists the available placement constants.

Placement constants

Constant	Description	Example
TOP	Places widget above content edit form.	return ContentEditWidgetPlacement.TOP;
TAB	Places widget in its own tab. If you use this position, the tab does not appear for embedded objects in the content edit form.	return ContentEditWidgetPlacement.TAB;
BOTTOM	Places widget below content edit form.	return ContentEditWidgetPlacement.BOTTOM;
RIGHT	Places widget below URLs widget.	return ContentEditWidgetPlacement.RIGHT;

Hiding

By default, Brightspot displays the following standard widgets in the content edit page: References, Revisions, SEO, Sites, Template, and URLs. Some of these widgets appear depending on an item’s state. For example, the Revisions widget appears only after you save a draft, change a workflow state, or publish an item. In addition, Brightspot automatically displays any custom widgets created for the content edit page. (For information about creating custom widgets for the content edit page, see Creating content edit widgets and Creating updating content edit widgets.)

You can hide widgets at the content-type level and at the custom widget level.

Hiding widgets at the content-type level

You can hide the standard or custom widgets at the content-type level. For example, you can show the URLs widget on content edit pages for articles, and hide the widget on content edit pages for images.

The interface ContentEditWidgetDisplay contains a method shouldDisplayContentEditWidget that you can override to specify if a widget is visible or not in a content edit page. You implement the interface at the model level, which gives you the flexibility for showing or hiding widgets depending on content type. The following example shows how to hide the standard URLs widget in an article’s content edit page.

1
import com.psddev.cms.db.Content;
2
import com.psddev.cms.db.ToolUi;
3
import com.psddev.cms.tool.ContentEditWidgetDisplay;
4
import com.psddev.cms.tool.content.UrlsWidget;
5
import com.psddev.dari.db.Recordable;
6

7
public class Article extends Content implements ContentEditWidgetDisplay {
8

9
    @Recordable.Required
10
    private String headline;
11

12
    @ToolUi.RichText
13
    private String body;
14

15
    @Override
16
    public boolean shouldDisplayContentEditWidget(String widgetName) {
①
17
        if (widgetName.equals(UrlsWidget.class.getName())) {
18
            return false;
19
        } else {
20
            return true;
21
        }
22
    }
23
}

• ①Implements the method shouldDisplayContentEditWidget. Brightspot calls this method for each widget eligible to appear in the content edit page. If the widget’s name is the same as the URLs widget’s name, the method returns false and the widget does not appear. See the following illustration.

Hiding custom widgets

If you create a custom widget, you can hide it from the content edit page—regardless of the content type—by overriding the shouldDisplay method in the widget’s definition.

1
import com.psddev.cms.tool.ContentEditWidget;
2
import com.psddev.cms.tool.ContentEditWidgetPlacement;
3
import com.psddev.cms.tool.ToolPageContext;
4

5
public class CurrentTimesWidget extends ContentEditWidget {
6

7
    @Override
8
    public void display(ToolPageContext page, Object content, ContentEditWidgetPlacement placement) throws IOException {
①
9

10
        page.writeStart("p");
11
            page.writeHtml("My widget for personal notes.");
12
        page.writeEnd(); /* p */
13
    }
14

15
    public ContentEditWidgetPlacement getPlacement(ToolPageContext page, Object content) {
16
        return ContentEditWidgetPlacement.BOTTOM;
17
    }
18

19
    public String getHeading(ToolPageContext page, Object content) {
20
        return "My Custom Widget";
21
    }
22

23
    @Override
24
    public boolean shouldDisplay(ToolPageContext page, Object content) {
②
25
        return false;
26
    }
27
}

• ①Defines a custom widget that appears under the content edit form.
• ②Hides the custom widget from the content edit page. See the following examples.

Additional configuration

You can configure widgets on the content edit form directly from Brightspot. Configuration includes the following features:

• Creating custom content edit form by content type.
• Assigning custom content edit forms at the role level or to site-role combinations.
• Add tabs to content edit forms, and adding fields to those tabs.
• Assigning read/write permissions at the tab and field level.

For details about these configuration activities, see the following topics in the Editorial Guide:

• Customizing content edit forms