Support and Documentation

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. 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.

package content.article;

import com.psddev.cms.db.Content;

public class Reporter extends Content {

    private String firstName;
    private String lastName;

    /* Getters and setters */

    public String getFullName() {
        return getFirstName() + " " + getLastName();
    }
}

In the previous snippet—

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.

public class Article extends Content implements Directory.Item {

   /* Other fields in an Article */

    @ToolUi.Hidden
    private Reporter reporterCredit;

    public Reporter getReporterCredit() {
        return reporterCredit;
    }
}

Step 3: Declare a custom updating content edit widget

package widgets;

import com.psddev.cms.tool.UpdatingContentEditWidget;

public class ReporterCreditWidget extends UpdatingContentEditWidget {

}

Brightspot instantiates this class every time an event occurs in the content edit page, such as when loading an item or clicking Publish.

Step 4: Display the widget's header

You display the custom widget's header by implementing the method getHeading in the class from Step 3.

public String getHeading(ToolPageContext page, Object content) {
    /* Return string appearing in widget's title bar. */
}

Step 5: Display the widget's body

You display the custom widget's body, including form elements, by implementing the method displayOrUpdate in the class from Step 3.

public void displayOrUpdate(ToolPageContext page, Object content, ContentEditWidgetPlacement placement) throws IOException {
    /* Use page.write methods to display the widget's body,
       including form elements. */
}

Step 6: Catch the update event

The parameter placement in Step 5 is passed as null when the widget detects an update event. You test for null to process the widget's current state.

if (placement == null) {
    /* Retrieve form values and update database. */
}

Step 7: Position the custom updating widget

You provide a position for the custom updating widget in the content edit page by implementing the method getPlacement in the class from Step 3.

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

See the table Placement constants for a list of possible placement values.

Step 8: Set Condition for displaying content edit widget

Custom updating content edit widgets often appear in the UI for certain types of content and are suppressed for other types. You override the method shouldDisplay with a condition that evaluates to true when you want the content edit widget to appear.

public boolean shouldDisplay(ToolPageContext page, Object content) {
     /* Condition for displaying custom updating widget. */
 }

Step 9: Display custom updating widget in content edit page

The following snippet shows an entire class for displaying the custom updating widget Reporter Credit in the content edit page. The widget lists the available reporters which can be assigned to the current article. When the user clicks Publish, Brightspot updates the article's record with the selected reporter. This example assumes you have a model that includes a field reporterCredit with the associated getter and setter as descried in Step 2.

package widgets;

import com.psddev.cms.tool.ContentEditWidgetPlacement;
import com.psddev.cms.tool.ToolPageContext;
import com.psddev.cms.tool.UpdatingContentEditWidget;
import com.psddev.dari.db.Query;
import content.article.*;

import java.io.IOException;
import java.util.List;
import java.util.UUID;

public class ReporterCreditWidget extends UpdatingContentEditWidget {

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

        Article myArticle = (Article) content;

        if (placement == null) {
            UUID reporterID = page.param(UUID.class, "reporter.select");
            Reporter creditedReporter = Query.from(Reporter.class).where("id = ?", reporterID).first();
            myArticle.setReporterCredit(creditedReporter);
            return;
        }

        List<Reporter> reporters = Query.from(Reporter.class).selectAll();
        Reporter currentReporter = myArticle.getReporterCredit();

        page.writeStart("select", "name", "reporter.select");
            page.writeStart("option", "value", "").writeEnd(); /* Initial blank option */
            for (Reporter reporter : reporters) {
                page.writeStart("option", "selected", reporter.equals(currentReporter) ? "selected" : null, "value", reporter.getId());
                    page.writeHtml(reporter.getFullName());
                page.writeEnd(); /* option */
            }
        page.writeEnd(); /* select */
    }

    @Override
    public ContentEditWidgetPlacement getPlacement(ToolPageContext page, Object content) {
        return ContentEditWidgetPlacement.RIGHT;
    }

    @Override
    public String getHeading(ToolPageContext page, Object content) {
        return "Reporter Credit";
    }

    @Override
    public boolean shouldDisplay(ToolPageContext page, Object content) {
        return content instanceof Article;
    }
}

In the previous snippet—

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