Creating a custom Preview Type

To implement your own custom preview type in Brightspot, you need to follow a few steps. We'll start with discussing extending PreviewType.java directly, then discuss using the helper class IFramePreviewType.java for specifically creating a preview type that displays using an iframe.

Custom shareable preview

Below are step-by-step instructions for creating a new preview type in Brightspot. As part of these instructions, you'll develop a JSONPreviewType class that displays the raw JSON data of the preview content.

Step 1: Define your custom preview type class

Start by creating a new Java class that extends the PreviewType abstract class. This will serve as the foundation for your custom preview type. Be sure to import the necessary classes and packages at the beginning of your file.

public class JSONPreviewType extends PreviewType {
    
}

Step 2: Provide a display name

Override the getDisplayName() method in your custom class. This method returns the display name for your preview type. Choose a descriptive name that represents the purpose or functionality of your custom preview type.

@Override
public String getDisplayName() {
    return "JSON Preview";
}

Step 3: Implement the display method

Next, override the display(Preview preview) method. This method is responsible for generating the HTML that will be rendered in the display area of the preview pane. You can customize this method to generate the specific HTML markup required for your custom preview type. Remember to return the HTML as a String.

@Override
public String display(Preview preview) {
    Map<String, Object> previewObjectValues = preview.getObjectValues();
    String json = ObjectUtils.toJson(previewObjectValues);
    // You can customize the formatting or styling of the JSON as needed
    return "<pre>" + json + "</pre>";
}

Step 4: Specify when the preview type should display

Override the shouldDisplay(Preview preview) method in your custom preview type class. This method includes conditions that determine if your custom preview type should be displayed. Return true if it should be displayed, and false otherwise.

@Override
public boolean shouldDisplay(Preview preview) {
    // You can add custom logic here to determine when the JSON preview should be displayed for the given Preview Object
    return true;
}

Step 5: Make your preview type available

See Configuring preview types to learn how to make your new custom preview type available in the CMS. Both programmatic and admin configuration options are available.

Once your custom preview type is implemented and available, it's time to test it. Create or edit an asset that uses your custom preview type, and verify that the preview is displayed correctly. Make any necessary adjustments or refinements to ensure a smooth user experience.

Custom iframe preview

The IFramePreviewType abstract class supports the common use case of previewing an asset inside an iframe within the CMS.

Below is a step-by-step guide on how to implement an IFramePreviewType. As an example, code is provided for a DocumentPreviewType which renders an asset in a PDF preview.

Step 1: Define your custom preview type class

Create a new Java class called DocumentPreviewType that extends the IFramePreviewType abstract class. Be sure to import the necessary classes and packages at the beginning of your file.

import com.psddev.cms.db.Preview;
import com.psddev.cms.preview.IFramePreviewType;

public class DocumentPreviewType extends IFramePreviewType {

}

Step 2: Provide a display name

Override the getDisplayName() method in your DocumentPreviewType class to return the display name for your preview type. In this case, we use Document Preview as the display name.

@Override
public String getDisplayName() {
    return "Document Preview";
}

Step 3: Implement the getFormAction method

Override the getFormAction(Preview preview) method in your custom class. This method returns the URL or endpoint that generates the actual preview. This could be an internal Tool URL (powered by a ToolPage.java class, for example) or an external URL.

    @Override
    protected String getFormAction(Preview preview) {
        return new UrlBuilder(PdfPreviewToolPage.class).build();
    }

Step 4: Implement the createFormInputs method

Override the createFormInputs(Preview preview) method in your custom class. This method is responsible for creating and returning the necessary HTML form inputs for the request to the endpoint provided by getFormAction. You can include any required parameters or data as needed. In most cases, you will want to provide the ID of the preview object as a hidden form input element.

    @Override
    protected String createFormInputs(Preview preview) {
        return INPUT.typeHidden().value(preview.getId().toString()).name("previewId").toString();
    }

Step 5: Specify when the preview type should display

Override the shouldDisplay(Preview preview) method in your custom preview type class. This method includes conditions that determine if your custom preview type should be displayed. Return true if it should be displayed, and false otherwise.

@Override
public boolean shouldDisplay(Preview preview) {
    return preview.getObjectType().equals(ObjectType.getInstance(Document.class));
}

Step 6: Implement the refreshAsContentChanges method

Override the refreshAsContentChanges() method in your custom class. This method returns true if the form returned from the display() method is submitted as the content is updated, or false otherwise. If you return false, you typically want to provide a button to allow the user to manually refresh the preview. Set this value based on your specific requirements.

@Override
protected boolean refreshAsContentChanges() {
    // Set to true if the preview should be automatically refreshed when the content is updated
    return false;
}

Step 7: Make your preview type available

See Configuring preview types to learn how to make your new custom preview type available in the CMS. Both programmatic and admin configuration options are available.

When available, the preview type will display an HTML form that sends a request to the provided form action endpoint with the included form inputs. The resulting endpoint's response appears within an iframe in the preview pane.

Preview Type Helper Methods

Feel free to explore the various utility methods provided in the PreviewType class. These methods assist in creating additional functionality for your custom preview type.

createSharePreviewLink(Preview preview)
createSharePreviewLink(Preview preview) generates a share preview link for a specific preview object. This link can be used to share the preview with others, enabling collaboration and feedback. Pass the desired Preview object to this method, and the method returns an AElement HTML link element that can be easily converted to HTML using the toString() method.

createScheduleDateSelect(Preview preview, ToolUser user)
This method creates a date picker control for the preview. It allows users to preview an asset as it will look on a specific date, bringing in any scheduled published changes. You pass the Preview object and the current ToolUser to this method, and it returns a TextSearchInputElement that represents the date select input. You can then convert it to HTML using the toString() method.

createDeviceWidthSelect(Preview preview)
createDeviceWidthSelect(Preview preview) simplifies the creation of a device width select input. This input allows users to select a specific device width, making it easier to view how an asset appears on different devices. By passing the Preview object to this method, you'll receive a SelectElement that represents the device width select input. You can convert it to HTML using the toString() method. Note that you typically only want to display this option when in the content-edit-preview preview context, which you can detect using an if statement.

if (Preview.CONTENT_EDIT_PREVIEW_CONTEXT.equals(preview.getContext())) {
    div.add(PreviewType.createDeviceWidthSelect(preview));
}

These utility methods enhance the functionality of your custom preview type, and provide additional convenience for users. You can leverage them to create a more comprehensive and user-friendly preview experience.