Enable live preview

Optimizely CMS (SaaS) provides a user-friendly WYSIWYG (what you see is what you get) authoring interface. To ensure compatibility, you should develop your application's views with this in mind. The preview functionality is framework-agnostic, and you can use plain JavaScript.

To enable a live preview of the content, you need to complete four main tasks:

1. Configure an application .
2. Enable communication between CMS (SaaS) and your application.
3. Enable property overlays.
4. Refresh the application's view when content has changed.

Prerequisites

To complete the following steps, you must create a:

• content type.
• content item.

Configure application

CMS (SaaS) requires information about your application, particularly its URL.

1. Go to Settings > Applications.
2. Click Create Website Application, add a Name, and select an existing page as your start page or create a new.
3. Click Create Website.
4. Go to Hostnames.
5. Click Add Hostname and add a Hostname where Optimizely can locate your application. Note that this can be a local hostname on your computer, for example localhost:5000.
6. Click Add.

Enable communication between CMS and your application

CMS (Saas) must be able to notify your application to update its current view when editors change the content. Additionally, it must know the properties your view is rendering and how to display an overlay for them. You must set up a communication script to establish this communication between CMS (SaaS) and your application.

You must embed the https://app-xxx.cms.optimizely.com/util/javascript/communicationinjector.js script (available from your instance) in your application to preview content in CMS (Saas).

🚧

Important

If your application has configured Content Security Policies (CSP), make sure the policies let you embed your application in an iframe and lets the communication script be loaded from your CMS (SaaS) URL: https://app-{xxx}.cms.optimizely.com.

Content preview

You can use the CMS (SaaS) URL to determine when content is being previewed. CMS (SaaS) uses the following URL format:

https://your-app.com/preview?key={key}&ver={version}&loc={locale}&ctx={edit|preview}&preview_token={token}

• /preview – Check if the current path is /preview.
• preview_token – Check if the incoming URL contains the preview_token parameter.
• ctx – Check if the context mode is set to edit or preview. See the Context modes section for information.
• ver – Identify the version of the content being previewed.
• loc – Check the locale of the content.

📘

Note

The preview URL format is fixed, but soon you can define your own format.

Authorization

The preview functionality lets you load unpublished content, such as content drafts. To retrieve unpublished content from Optimizely Graph, authenticate the request using the preview token provided in the preview URL. Extract the preview token from the URL and include it in the Authorization header:

curl --location 'https://cg.optimizely.com/content/v2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {the preview token}' \
--data '{ your GQL query }'

📘

Note

The preview token is valid for 5 minutes.

Enable property overlays

The communication script provides CMS (SaaS) feedback on the location of content properties in the view. This information then displays an interactive overlay, visualizing editable content properties. The overlay lets you click on the properties you want to edit. In Visual Builder, the preview automatically scrolls the preview to the property that is being edited.

Decorate each rendered content property with an HTML attribute that includes the property name:

<span data-epi-edit="ThePropertyName">
  <!-- your JavaScript framework of choice decides how the property is actually rendered here -->
</span>

Encapsulate the rendering of these HTML attributes within a shared function that ensures they are only rendered during content preview and when the context mode is set to edit. See Context modes.

Context modes

Two context modes are available when previewing content: edit and preview. The context mode is determined by the ctx query parameter in the preview URL. You should only render the overlay HTML attributes when the context mode is set to edit. This lets editors preview the content without the property overlays blocking the view. See Visual Builder.

Refresh the application's view when content has changed

Subscribe to events emitted by the communication script to ensure real-time updates of your application's view when content is changed by an editor in CMS (SaaS). These events contain an updated preview URL and a preview token that you should use to update your application's view with the latest content version from Optimizely Graph.

The optimizely:cms:contentSaved event that indicates that the changes to the content being authored were saved, indexed by Optimizely Graph, and can be fetched. Now the view application can refetch/rerender the data and see the changes.

window.addEventListener('optimizely:cms:contentSaved', (event) => {
   const message = event.detail;
   // Re-run your graphql queries using the new previewToken which is returned as part of `message` or
   // extract the new preview URL from message and refresh your view or state with it.
});

interface ContentSavedEventArgs {
    contentLink: string;
    previewUrl: string;
    previewToken: string;
    properties: PropertySaved[];
    parentId?: string;
    sectionId?: string;
}

window.addEventListener('optimizely:cms:contentSaved', (event) => {
   const message = event.detail as ContentSavedEventArgs;
   // Re-run your graphql queries using the new previewToken which is returned as part of `message` or
   // extract the new preview URL from message and refresh your view or state with it.
});