Previews & the Prismic Toolbar

When working in the writing room, you can preview new content on your website without having to publish the document, you can set up one or more websites where the content can be previewed. This allows you to have a production server, staging server, development server, etc.  Discover how to handle multiple environments in Prismic.

The Toolbar allows you to edit your pages. In your website, just click the button, select the part of the page that they want to edit, and you'll be redirected to the appropriate page in the Writing Room.

New Toolbar Activation for Older Repos

The current preview toolbar is enabled by default on all new Prismic repos. However, if you're on an older repo, you might be on older version of the toolbar. If your preview script src url includes new=true, then your preview functionality includes an edit button. If the src does not include new=true and you would like the new preview toolbar, please contact us via the Prismic forum so we can activate it for you.

1. Configure Previews

In your repository, navigate to Settings > Previews. Here you can add the configuration for a new preview, just add:

  • The Site Name: The name of the current site your configuring.
  • Domain URL: You can add the URL of your live website or a localhost domain, such as: http://localhost:8000.
  • Link Resolver (optional) : In order to be taken directly to the page you are previewing instead of the homepage, add a Link Resolver which is an endpoint on your server that takes a Prismic document and returns the url for that document. More details on step 3. Add a Link Resolver endpoint.

2. Include the Prismic Toolbar javascript file

You will need to include the Prismic toolbar script on every page of your website including your 404 page.

You can find the correct script in your repository Settings section, under the Previews tab.

Settings > Previews > Script

Copy
<script async defer src="https://static.cdn.prismic.io/prismic.js?new=true&repo=your-repo-name”></script>

Correct repo name

Note: This example script has your-repo-name at the end of the URL, this value needs to be replaced with your repository name. You can find the correct script for in your repository's Settings > Previews > Script.

Shareable Previews & unpublished previews

To guarantee that Shearable Preview links and unpublished document previews work properly you must ensure that these scripts are included on every page of your website, including your 404/Page Not Found page. Otherwise these previews might not work.

3. Add a Link Resolver endpoint

In order to be taken directly to the page you are previewing instead of the homepage, you need to add a Link Resolver endpoint. A typical example of this would be:

Copy
https://{yoursite}/preview

In your preview settings add an endpoint to the optional Link Resolver field as explained in step 1.


If your Vue Router is in hash mode, the Link Resolver endpoint must contain the hash: /#/preview

Using the official Prismic Vue.js starter?

If you are using the official Prismic Vue.js starter, then you should already have all the code in place you need for in-website previews. That's as much as you need to do!

If you are using our official Prismic vue.js plugin (prismic-vue) or any other of our starter projects, then you should already have all the code in place that you need for Previews and the Prismic Toolbar!

If you are not using this kit to make your queries, then follow the rest of the steps below.

Add the Link Resolver route to your application

Now you need to add the Link Resolver endpoint route to your website router. In the Prismic Vue.js starter you will find this route in src/router.js.

Copy
// ...

import Preview from 'path/to/the/Preview.vue';

// ...

{
  path: '/preview',
  name: 'preview',
  component: Preview
},

// ...

You can see that when the "/preview" route is called, it will use the Preview component. Let's create this component now.

Add the Preview component

The Preview component must do the following:

  • Retrieve the preview token from the token parameter in the query string
  • Retrieve the documentId from the query string
  • Call the Prismic development kit with this token and the Link Resolver will retrieve the correct URL for the document being previewed
  • Redirect to the given URL

The Preview Token

Note that the preview token will be a URL. You DO NOT need to follow this url.

Processing the Preview Token with 'getPreviewResolver' method

All you need to do is pass the token into the getPreviewResolver method as shown below. (prismic-javascript kit V3.0.1 and above). Here is an example of what the Preview route might look like.

Copy
<template>
  <div class="outer-container">
    <p>Loading the Prismic's Preview...</p>
  </div>
</template>

<script>
import Vue from 'vue'

export default {
  name: 'Preview',
  beforeCreate () {
    const { token, documentId } = this.$route.query

    this.$prismic.client.getPreviewResolver(token, documentId).resolve(this.$prismic.linkResolver, '/')
      .then((url) => {
        window.location.replace(url)
      })
  }
}
</script>

The Link Resolver function

This requires the use of a Link Resolver function so that the preview endpoint knows where to redirect to. You can learn more about link resolving by checking out the Link Resolving page.

You either need to define the Link Resolver in the Preview component or import it.

You should already have the Link Resolving function in place if you have followed the Integrating with existing project page or are working with the Prismic Vue.js starter.

Deprecated 'previewSession' method

For anyone using a version of the prismic-javascript kit older than V3.0.1, then you should pass this token into the previewSession method as shown below.

Copy
<template>
  <div>
    <p>Loading the Prismic's Preview...</p>
  </div>
</template>

<script>
export default {
  name: 'Preview',
  beforeCreate () {
    const previewToken = this.$route.query.token;

    this.$prismic.client.previewSession(previewToken, this.$prismic.linkResolver, '/')
      .then((url) => {
        window.location.replace(url);
      })
  }
};
</script>

To learn more about how to preview a document, check out the user guide.

4. Troubleshooting

Mistakes happen. So sometimes you might to do a little troubleshooting to figure out where exactly the problem is from, luckily we've created an article for just that.

Deprecated: In-Website Edit Button

Note: The In-Website Edit Button has been deprecated in favor of the Preview Toolbar, which has an edit button built in.