Brightspot CMS Developer Guide


Alterations apply or modify annotations to classes and class members when you cannot modify the original class. An annotation can be added or modified if its processor modifies the state of ObjectType or ObjectField. An alteration extends the Alteration class with the target of the alteration, which must be of type Recordable.

The annotations’ values are persisted to the object state, and are reflected in the Brightspot UI or in the frontend. For example, suppose you have the following base class Image:

import com.psddev.cms.db.Content;

public class Image extends Content {

    private String title;


If you don’t have access to the class Image, you can change its display name and the display name of its members by applying the annotation @Recordable.DisplayName.

import com.psddev.dari.db.Alteration;
import com.psddev.dari.db.Recordable;

@Recordable.DisplayName("Breaking Image") 
public class BreakingImage extends Alteration<Image> { 

    @DisplayName("Punchy caption") 
    private String title;

  • Changes the class's display name within Brightspot to Breaking Image.
  • Indicates that BreakingImage alters the base class Image, and any annotations applied in BreakingImage override or are in addition to those in Image.
  • Changes the field's label to Punchy caption.

The following examples illustrate the effect of applying the @DisplayName annotation on the altered class.

Content edit form for base class.png Content edit form for base class.png
Content edit form for base class
Content edit form for altered class.png Content edit form for altered class.png
Content edit form for altered class

Alterations can also be applied to modifications that extend core classes. For example, say that Image implements the Promotable interface, and a modification adds an annotation and a field on all classes that implement Promotable.

Example 1: Image implements Promotable interface

public class Image extends Record implements Promotable

Example 2: Modification adds an annotation and a field that impacts the Image class

public class PromotableData extends Modification<Promotable> {

    /* Display name is implicitly "Promotable Title" */
    private String promotableTitle;


You can expand the ImageAlteration class to change the display name of the promotableTitle field in the Image content edit form.

public class ImageAlteration extends Alteration<Image> {

    @DisplayName("Image Title")
    private String title;

    private StorageItem file;

    @Recordable.DisplayName("Promotable Image Heading")
    private String promotableTitle;


The promotableTitle field added via modification and the alteration to the field’s display name are reflected in the Image content edit form.

New field displayed on Image edit form.png New field displayed on Image edit form.png
New field displayed on Image edit form

The class ImageAlteration alters annotation values of one target class, Image. Alterations can also target interfaces, overriding annotation values of all classes that implement the target interface.

For example, in addition to ImageAlteration, you can have an alteration that targets the Promotable interface. This class overrides the display name value of the promotableTitle field, impacting all class types that implement Promotable.

public class PromotableAlteration extends Alteration<Promotable> {

    @Recordable.DisplayName("Promotable Heading")
    private String promotableTitle;

Given that Image also implements Promotable, the alteration to promotableTitle’s display name is reflected in the Image content edit form. (Prior to PromotableAlteration, the promotableTitle’s display name in the Image content edit form was “Promotable Image Heading.”)

Promotable Image Heading field shown.png Promotable Image Heading field shown.png
Promotable Image Heading field shown

If a class is a target of more than one annotation alteration, the annotation values in the class can be overridden by multiple alterations.

Alterations classes are applied alphabetically in ascending order. So in the case of the Image class, its annotation values are first overridden by ImageAlteration, then by PromotableAlteration. Given that both ImageAlteration and PromotableAlteration override the promotableTitle display name, the PromotableAlteration override value takes precedence over the ImageAlteration override value.

To summarize the annotation alteration sequence for Image:

  1. ImageAlteration of Image target overrides:

    • PreviewField of Image class
    • DisplayName of title field
    • MimeTypes of file field
    • DisplayName of promotableTitle field
  2. PromotableAlteration of Promotable overrides:

    • DisplayName of promotableTitle field
Previous Topic
Next Topic
File Storage
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