Alterations

Alterations provide the capability to override annotation values in cases where you cannot modify existing classes. An annotation can be altered if its processor modifies the state of ObjectType or ObjectField. Override values are persisted to the object state, and are reflected downstream in the Brightspot editorial UI or in frontend page rendering.

An alteration extends the Alteration class with the target of the alteration, which must be of type Recordable. For example, if you have a type Image

public class Image extends Record {

private String title; // display name is implicitly "Title"

// getters & setters
}

… an alteration class specifies Image as the target of Alteration, and applies the @DisplayName annotation to the title field. The value of the annotation will be reflected in the content edit form for the Image type.

public class ImageAlteration extends Alteration<Image> {

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

 }

The next example expands the Image class with file and previewFile fields. Annotated with @MimeTypes, the file field will take any type of image set on it in the content edit form. A user can also set an image on the previewFile field, but, in fact, it would not be used as the preview image because Brightspot uses the first StorageItem field set in the class for image previews.

public class Image extends Record {

   private String title; // display name is implicitly "Title"

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

   private StorageItem previewFile;

   // getters & setters
}

To rectify the previewFile issue, the alteration specifies the @PreviewFile annotation, making the previewFile field the target of the annotation. The alteration also overrides the mime type value for the file field, allowing only images of subtype png to be set on the file field.

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

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

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

 }

The alterations impact all fields on the Image content edit form.

../../_images/content-edit-form-image.png

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.

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

   // getters & setters
}

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.

../../_images/content-edit-form-image2.png

Altering Interface Implementations

The ImageAlteration class 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”.)

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