Setting up previews and Visual Editing

Set up preview URLs

Allow content editors to preview a content item by setting up a preview URL. You can set up preview URLs for multiple environments like production, acceptance, test, and development. Preview URLs are defined for a specific model.

To add one or more preview URLs, follow the steps below.

1. Go to the Schema tab and choose the model you want to update.

2. Click the Settings button at the top of the model and click the Features tab.

3. To make the Visual Editing icon visible in content items, make sure the Visual Editing toggle is switched on. Conversely, if you want to hide the icon to avoid confusion, for example, for a model for navigation bar content, then disable this toggle.

   

4. Go to the Preview tab and enter a name and the preview URL construct for this model. You can use {id} and {slug} variables for your construct. Example: https://example.com/{slug}.

5. If you want to make visual editing accessible for this model, then select the Use in Visual Editing option to enable the live side-by-side preview.

You can add an unlimited number of preview URLs to the model. The first name you set will be shown as default in the content items of this model.

Scoping environments for a preview URL

When you set up preview URLs for a shared model, you can either choose to make a preview URL available to all environments in the organization or set specific environments this preview URL is relevant for.

When you set a specific environment to a preview URL in the shared model, editors in that environment can choose this relevant URL to preview their content.

Access unpublished content

Accessing unpublished content is useful for previewing new content items before making them available publicly. The Prepr GraphQL API gives you control over whether you want to access published or unpublished content items in the front end.

To show content items that are not yet published in the front end, use the GraphQL Preview access token created by Prepr during the initial environment setup. With this access token, you can retrieve content items in all available workflow stages, including To do, In progress, Review, Done, and Published. The content editor can then review them and make any necessary changes before publishing.

Alternatively, you can create a new access token yourself and define token permissions according to your specific needs. Read more about GraphQL permissions.

Activate Edit Mode in your front end

If you have a Next.js front end, Edit mode is automatically available after you install the Prepr Next.js package in your front end and use an access token with Edit mode enabled.

Alternatively, if your preview web app is deployed on Vercel, Prepr supports the Vercel Content Link.

Vercel Content Link is a special link or URL provided by Vercel that directly serves dynamic content deployed on the platform. This feature allows content editors to edit content directly from the preview web app. When content editors open their preview web app, they can simply hover over elements to reveal a link to the corresponding item for quick updates.

Example preview website with Vercel Content Link enabled.

To enable Vercel Content Link for your preview environment, follow the steps below.

1. Deploy a preview environment on Vercel . When deploying a preview environment, Vercel automatically generates a content link, https://<project-name>.vercel.app for your project.

To enable Edit mode in a preview access token, follow the steps below.

1. In your Prepr environment, click the icon and choose the Access tokens option to view all the access tokens.

2. Click your preview access token to open it and select the Enable edit mode checkbox and click the Save button.

   

Once enabled, when content editors preview the web app, they can hover over an element and click the link to open the corresponding item for quick updates. The link takes them directly to the corresponding content item in their Prepr environment.

Enable live preview in your front end

To make sure Visual Editing works in your Prepr environment, you need to make sure that inline frames (iframes) are allowed for all Prepr environments.

Visual editing uses iframes for this in-app preview alongside a specific content item. This means your HTTP server needs to allow iframes for the Prepr domain.

If you get a server error like: Refused to frame 'https://...' because an ancestor violates the following Content Security Policy directive..., you can allow iframes by updating the Content-Security-Policy HTTP header in the web server configuration like in the code snippet below:

Content-Security-Policy: frame-ancestors <YOUR-PREPR-ENV-URLS>

Replace <YOUR-PREPR-ENV-URLS> with your own Prepr environment URLs, for example: https://prod-acme-lease.prepr.io https://dev-acme-lease.prepr.io where each URL is separated by a space.

Enable Segment and A/B test switches

When content editors add personalized content and or A/B test content to content items, it’s useful for them to preview the content per segment and A/B variant before publishing the adaptive content.

They can use the Segment and A/B test switches to do this type of live preview. You can find these switches just above the preview next to the Screen size icons.

If you have a Next.js front end, the Segment and A/B test switches are available automatically after you install the Prepr Next.js package in your front end.

If you’re not building your front end with Next.js, you can enable the switches with the following steps:

1. Post a loaded event message like in the following code snippet:

   if(window.parent !== self) {
     const message = { name: 'prepr_preview_bar', event: 'loaded' };
     window.parent.postMessage(message, '*');
   }

   When you post this message, Prepr enables the segment and A/B test switches.

2. When an editor changes the value of the switches, Prepr adds query parameters to the URL like in the example below:

   https://acme-lease.prepr.io/?prepr_preview_ab=B&prepr_preview_segment=sgm_8ip8odwnmcc

   The prepr_preview_ab parameter will have a value of A or B, while the prepr_preview_segment contains the _id value of the chosen segment. You can use these parameters to set the API header Prepr-ABTesting and Prepr-Segments to their provided values.

   See an example code snippet on setting API headers using Apollo.

   const { data } = await getClient().query<PageQuery>({
       query: PageDocument,
       variables: {
           slug: slug,
       },
       context: {
           headers: {
               'Prepr-Segments': <prepr_preview_segment value>,
               'Prepr-ABTesting': <prepr_preview_ab value>
           },
       },
   })

   By setting these headers, your query will retrieve specific personalized content and the specific content for the A or B variant. This means the editor sees the matching personalized content for the segment they chose and the matching A/B test content for the variant they chose.

At this point, your preview is ready for content editors. To complete the setup for Visual editing, the side-by-side live preview, continue with the steps below.

Maintain scroll position after refresh

When refreshing the live preview, it’s useful for editors if their last scroll position in the preview stays at the same place. If you have a Next.js front end, the scroll position is saved automatically if you install the Prepr Next.js package in your front end.

For other frameworks, check out the example code snippet below on how to set up the scrolling.

if(window.parent !== self) {
    let parentOrigin = null; //Get origin of parent outside iframe
    const message = { name: 'prepr_preview_bar', event: 'loaded' };
    window.parent.postMessage(message, '*');
    window.addEventListener("message", (evt) => {
        if(evt.data?.event === 'prepr:initVE' && !parentOrigin) {
            parentOrigin = evt.origin;
 
            if(evt.data?.scrollPosition) {
                //Timeout needed in order to scroll to position
                setTimeout(() => {
                    window.scrollTo(0, evt.data?.scrollPosition)
                }, 1)
            }
        }
        if(evt.origin !== parentOrigin) return;
 
        if(evt.data?.event === 'prepr:getScrollPosition') {
            const currentScrollY = window.scrollY || document.documentElement.scrollTop;
            window.parent.postMessage({
                ...message,
                event: "getScrollPosition",
                value: currentScrollY
            }, '*');
        }
    })
}