Alterations

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;

}

The following examples illustrate the effect of applying the @DisplayName annotation on the 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

@Recordable.FieldInternalNamePrefix("promo.")
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.

@Recordable.PreviewField("previewFile")
public class ImageAlteration extends Alteration<Image> {

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

    @MimeTypes("+image/png")
    private StorageItem file;

    @Recordable.InternalName("promo.promotableTitle")
    @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.

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.InternalName("promo.promotableTitle")
    @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.”)

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