How to Set Up Composer Preview for PageBuilder or Headlessly

When using PageBuilder

How this works:

  • Arc XP Composer serves as a starting point in the workflow, which starts with a story that is ready to be previewed.
  • You click the Preview Story button, which takes you to the preview URL.
  • The preview URL is a PageBuilder URL that contains the story’s ID.
  • PageBuilder then renders the preview.

You must configure the following items to set up the preview workflow:

  • PageBuilder Content Source that retrieves an unpublished revision
  • PageBuilder Resolver
  • Composer Preview URL
  • Enable ‘Access PageBuilder’ permission for all roles requiring Composer preview

If your organization uses Arc XP Themes to build your website, see Configuring Composer for Themes.

In Composer

Determining the preview URL

A resolver must capture the preview URL, so it’s best to choose something easy to catch. Additionally, we recommend you include the story ID and the website.

published=false: lets you view unpublished stories.

_ignoreCache=true: tells PageBuilder to ignore the cache for the current URI, which renders the latest revision for the story.

This documentation uses this as an example: /pf/preview/{_id}/?_website={canonical_website}&published=false&_ignoreCache=true

Enter your preview URL in Composer > Settings.

comp_settings.png

In PageBuilder

A content source, resolver, and template are required for the preview. The resolver maps to a default template and a content source. The content source is what retrieves the document from Content API, in this case by story ID. The template is the article template that matches your live site’s article page so you can view the story accurately.

Create the content source

For this step, you can either:

  • Create a new content source that makes requests to Content API with the published=false parameter added, or
  • Alter an existing Content API content source with additional logic that adds the published=false parameter if a condition is fulfilled (in this case, it can look for a story ID).

We’re going to go with option #1 and create a new content source.

In PageBuilder Engine, you create this in code. For this example, the content source would have to call this API endpoint: /content/v4/?_id=${id}&_website=${arc-site}&published=false

Notice in the following example that the content source calls the Content API unpublished endpoint if it receives a story ID:

const pattern = key => {
  const { website_url, id, website } = key;


  if(website_url)
    return `/content/v4/?website=${website}&website_url=${website_url}`;


  if(!website_url && id)
    return `/content/v4/?website=${website}&_id=${id}&published=false`;
};


const resolve = key => pattern(key);


const params = {
  website_url: "text",
  website: 'site',
  id: "text"
};


const source = {
  resolve,
  params,
};


export default source;

Set up the resolver

You must have a page resolver to map the incoming URL so that it matches the setting value from Composer. This is not an automated integration; it is manually configured.

Using the previous example, the resolver would look like this. Your Default Template and Content Source are specific to your setup. We recommend you use the same article template that you use for published stories.

comp_resolver_fields.png

In Permissions

In Arc XP Permissions, add the Access PageBuilder privilege to all roles requiring Composer preview. This read-only permission is needed to access PageBuilder, which powers the preview experience.

comp_access_pagebuilder.png

Using the story preview

Back in Composer, click the story preview icon:

comp_preview_icon_close.jpg

This button opens the link to your PageBuilder Story template with the unpublished draft rendered.

Without PageBuilder

If you do not use PageBuilder for rendering your front end, this section describes how to configure the preview functionality. If your organization uses PageBuilder, see When using PageBuilder.

Preview a story from Composer

In Composer, you can preview a draft story as if you were a reader on the front end of your site. You can see how content looks when published to your live site by clicking the Preview icon in the top left of the story toolbar.

comp_menu_preview_icon.png

Clicking this button opens a new tab to preview the story. To configure this preview capability for your users, you must set up a Composer preview URL string and ensure your system is set up to fetch and render articles.

Preview works as follows:

  • Composer serves as a starting point in the workflow, with a user working on a story that is ready to be previewed.
  • The user clicks the Preview Story button, which takes them to the preview URL, containing the story ID.
  • That story ID is passed to Content API, along with the published=false parameter.
  • The article is then rendered the same way as a published article.

How to create a custom preview page

Determining the preview URL

In Composer > Settings, use the Preview section, which includes the preview URL and preview domain.

Use the preview URL field to set your own custom URL.

Here, instead of setting up a relative URL for PageBuilder, you can create your own URL pattern to direct to an external site, for example:

http://content.yoursite.com/preview/{_id}/?published=false&ignoreCache=true

To support live preview of recently edited content, your headless back end must make non-cached requests to Content API using the ID passed in. For example, if you received the ID ABCDEFGHIKLMNOPQRSTUVWXYZ, you would make a request to:

https://api.{orgname}.arcpublishing.com/content/v4/?_id=ABCDEFGHIKLMNOPQRSTUVWXYZ&published=false&website=mywebsite

The Preview button within the story then opens this URL in a new tab when users click the Preview icon, fetching the story by story ID from Content API.

Required attributes for preview page

Your organization must create a page at this endpoint to show the given content within your site’s experience. As long as you are able to fetch the content from Content API and turn that Arc XP Native Specification (ANS) document into a rendered article, you can do this outside of PageBuilder. The page you create should have the following attributes:

  • Access Content - Use Content API to pull the current version of the current story. The _id is passed in the request so you can do that.
  • Publish Flag - Ensure that requests you make to Content API include non-published articles. We pass this as a flag in case you want to repurpose your primary story display code.

If you cannot support preview, you could instead consider creating a custom message on the preview URL endpoint to explain to your authors how to handle the workflow for reviewing stories before publication.

FAQ

Why am I getting a 500 error when I try to preview a story?

Consult your organization’s URL rules for displaying previews and pay particular attention to which metadata fields are required to generate the URL. Ensure you completed those fields because they’re required to render the preview. For example, if your preview URL rule relies on SEO keywords, verify that you entered data in that field in Composer. We recommend using the story ID for purposes of a preview.

How can I securely configure preview?

If you’re building a preview URL and endpoint that lives outside of PageBuilder, and therefore outside of the Arc XP ecosystem, your organization must build its own security protocols for this configuration.