Support and Documentation

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") 1
public class BreakingImage extends Alteration<Image> { 2


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

}

1

Changes the class's display name within Brightspot to Breaking Image.

2

Indicates that BreakingImage alters the base class Image, and any annotations applied in BreakingImage override or are in addition to those in Image.

3

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
Figure 111. Content edit form for base class


Content edit form for altered class
Figure 112. Content edit form for altered class


Altering modifications

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 51. Image implements Promotable interface
public class Image extends Record implements Promotable


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

Example 53. ImageAlteration class example
@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.

content-edit-form-image2.png
Altering interface implementations

The class ImageAlteration (see the snippet ImageAlteration class example) 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.")

content-edit-form-image3.png

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