Brightspot CMS Developer Guide

Visibility labels

Editors use visibility labels to filter the results of search criteria on the Brightspot UI. Brightspot uses visibility labels in conjunction with visibility-indexed fields to suppress objects; for details, see Excluding records from queries with visibility labels.

Brightspot uses visibility labels to manage pre- and post-publication states in addition to the published state. Using visibility labels, editors can filter on the type of objects that they want to retrieve. For example, the following search status filter lists the default visibility labels.

Default visibility labels Default visibility labels

If workflows are defined in Brightspot, then workflow statuses are added to the default visibility labels.

By implementing the VisibilityLabel interface, you can create custom states for content types. Implementations of this interface set custom labels on objects hidden by a visibility-indexed field. In Brightspot, the custom labels provide a query filter for retrieving the hidden objects.

The following example shows how to use visibility labels to set and display visitor comments on articles. In this scenario, visitors post comments on individual articles, and a site administrator approves or rejects the comment for publication.

To implement this comment-review scenario, a Comment class is used with a visibility-indexed field that stores the state of a comment, either in-review, rejected, or null. If null, the comment is published.

The visibility-indexed field takes a ModerationState enumeration, which has two constants, IN_REVIEW and REJECTED.

public enum ModerationState {

    IN_REVIEW("In Review"),

    private final String displayName;

    ModerationState(String displayName) {
        this.displayName = displayName;

    public String getDisplayName() {
        return displayName;

In the Comment class, a ModerationState constant is set on moderationState. The class also implements the createVisibilityLabel method from the VisibilityLabel interface.

public class Comment extends Content implements VisibilityLabel {

    private String text; 
    private User author;
    private Article articleCommentedOn;

    @Indexed(visibility = true)
    private ModerationState moderationState;

    protected void afterCreate() { 

        if (getState().isNew()) {
            moderationState = ModerationState.IN_REVIEW;

   public String createVisibilityLabel(ObjectField field) { 
      if ("moderationState".equals(field.getInternalName())) {
         return moderationState != null ? moderationState.getDisplayName() : null;
      return null;   }

   /* Getters and setters */

  • Declares four properties:

    • text stores a visitor’s comment entered on the front end.
    • author stores the visitor who enters the comment.
    • articleCommentedOn stores the article on which the comment is entered.
    • moderationState declares the visibility-indexed field. The @ToolUi.Placeholder annotation is applied to the field so that a third option, Approved, is available in the content edit form. An administrator can set this option on the moderationState field, in addition to the ModerationState constants of IN_REVIEW and REJECTED. Selecting Approved in Brightspot sets the moderationState field to null, thus making the Comment object retrievable by queries and viewable on the front end.
  • Sets moderationState to the IN-REVIEW value for a new comment. Triggered when a comment record is instantiated.
  • Returns string labels to Brightspot, which uses the labels in the UI to reflect the state of an object.

When a visitor enters a comment on the front end, a Comment object is created in an in-review state. In the content edit form, an administrator can approve or reject the comment for publication.

Rendered comment states Rendered comment states

The createVisibilityLabel method returns string labels to Brightspot, which uses the labels in the UI to reflect the state of an object. For example, if moderationState is set to IN_REVIEW or REJECTED, the createVisibilityLabel method returns the applicable ModerationState value to Brightspot. In the Revisions widget, past comments are identified by IN REVIEW or REJECTED. In the search panel, Brightspot adds the labels to the status filter for the Comment content type.

Rendered custom labels Rendered custom labels

To find comments that have not been published, you can use the following queries:

return Query.from(Comment.class).where("moderationState = ?", ModerationState.IN_REVIEW); 

return Query.from(Comment.class) 
               .where("moderationState = ?", ModerationState.REJECTED)
               .and("author = ?", author);
  • Returns a query for all comments in the review state.
  • Returns a query for all rejected comments for a specified visitor.

When an editor opens a selection field, Brightspot performs a query and lists those objects that satisfy the following conditions:

  • Is an instance of the associated class.
  • One of the following:

    • No visibility label in the class.
    • A visibility label is in the class, and the visibility label’s value is null.

Brightspot uses two fields to control the visibility of objects in a selection field: draft and trash.

@Indexed(visibility = true)
private Boolean draft;

@Indexed(visibility = true)
private Boolean trash;

In the previous snippet, the properties draft and trash are annotated with @Indexed(visibility = true). If the value of either field is non-null, Brightspot does not display the associated record in a selection field.

The following table summarizes the behavior of the properties draft and trash in an asset’s life cycle.

Asset visible in selection field?
Editor creates an asset
Set to non-null
Editor publishes asset
Set to null
Editor re-publishes asset
No change
Editor archives asset
No change
Set to non-null

See also:

Previous Topic
Customizing search results
Next Topic
Was this topic helpful?
Thanks for your feedback.
Our robust, flexible Design System provides hundreds of pre-built components you can use to build the presentation layer of your dreams.

Asset types
Module types
Page types
Brightspot is packaged with content types that get you up and running in a matter of days, including assets, modules and landing pages.

Content types
Landing pages
Everything you need to know when creating, managing, and administering content within Brightspot CMS.

Admin configurations
A guide for installing, supporting, extending, modifying and administering code on the Brightspot platform.

Field types
Content modeling
Rich-text elements
A guide to configuring Brightspot's library of integrations, including pre-built options and developer-configured extensions.

Google Analytics
Apple News