In-Website Preview

When working in the writing room, authors can preview their new content on their website without having to publish the document.

1. Include the Prismic Toolbar javascript file

Next you need to include the following scripts on every page of your website. Make sure to update <your-repo-name> with the name of the endpoint for your repository.

Copy
<script>
  window.prismic = {
    endpoint: 'https://<your-repo-name>.prismic.io/api'
  };
</script>
<script type="text/javascript" src="//static.cdn.prismic.io/prismic.min.js"></script>

Note for Sharable Previews

To guarantee that Sharable 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 the Shareable Preview might not work.

2. Setup a preview environment

In your repository, head to the Settings / Previews. Add a site name and the domain for your website where you wish to preview your content. You can also add an optional Link Resolver route which you will learn more about in the next section.

Note that you can also enter localhost domains such as:

Copy
http://localhost:3000

3. Use the correct reference

The next step is to make sure that the preview ref is used when you make your queries.

When you preview your website, a preview cookie is generated that contains the preview token. This token can be used as a valid ref to make Prismic API queries. For any query you make on your website, make sure to check for the Preview cookie and use this preview ref in the query options if the preview cookie exists.

The following example checks to see if there is a preview cookie. If there is, then it will set the ref variable to the preview ref. If not, it will use the experiment ref (if there is one) and otherwise the normal master ref (default published content).

Copy
def api
  @api = Prismic.api('https://your-repo-name.prismic.io/api')
end

def ref
  @ref ||= preview_ref || experiment_ref || api.master_ref.ref
end

def preview_ref
  if request.cookies.has_key?(Prismic::PREVIEW_COOKIE)
    request.cookies[Prismic::PREVIEW_COOKIE]
  else
    nil
  end
end

def experiment_ref
  if request.cookies.has_key?(Prismic::EXPERIMENTS_COOKIE)
    api.experiments.ref_from_cookie(request.cookies[Prismic::EXPERIMENTS_COOKIE])
  else
    nil
  end
end

Then you just need to add the "ref" query option as shown below to ensure that the preview ref is used. Here is an example query:

Copy
document = api.getByUID("page", "about-us", { "ref" => ref })

That is all you need to do to gain the basic functionality of the Preview feature! With the basic functionality of the Preview feature, when you click on the preview button, you will be taken to the homepage of your preview domain. From here you can navigate to the page you are trying to preview.

Next we will show you how to add a Link Resolver endpoint so that you will be taken directly to the page you are trying to preview.

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
http://{yoursite}/preview

In your preview settings add this endpoint to the optional Link Resolver field.

Using the official Prismic starter project?

If you are using the official Prismic Ruby on Rails starter project, 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're not using the official Prismic project, then follow the rest of the steps below.

Now you need to add the Link Resolver endpoint in your website application. When requested this endpoint must:

  • Retrieve the preview token from the token parameter in 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. All you need to do is pass this token into the preview_session method as shown below

Here is an example preview route:

Copy
# Preview
def preview
  api = Prismic.api('https://your-repo-name.prismic.io/api')
  preview_token = params[:token]
  redirect_url = api.preview_session(preview_token, link_resolver(), '/')
  redirect_to redirect_url
end

The example above uses a Link Resolver, link_resolver() , to determine the end url to redirect to. To learn more about how to set this up, check out our Link Resolving page.

Once all of these pieces are in place, your previews should be up and running!