Adding preview mode support

Preview mode in Xperience provides a way to view the latest version of pages before they are published (for example when using Workflow).

To use the preview mode, you need to set up and configure the related functionality. The configuration differs based on your site's routing mode:

  • On sites using content tree-based routing, preview mode works automatically for all page types with the URL feature enabled.
  • On sites running in the custom routing mode, you need to specify the URL pattern for your page types (in the administration application). The URL pattern is used to create URLs to the content presented by the external application.

Preview URLs for pages are used in the following scenarios:

  • When viewing pages in Preview mode in the Pages application.
  • When editing pages via the page builder on the Page tab of the Pages application.
  • When generating preview links for pages in Pages -> Properties -> URLs -> Preview URL. See: Sending links to unpublished pages

The preview URLs the system generates for pages consist of additional information, such as language version and a hash for validating the URL. The integration package in your MVC application validates and processes the preview URL. The page is then displayed through the standard routing process.

You need to manually ensure that your application displays the latest versions of pages in preview mode. See Loading the latest versions of pages for details.

Preview mode and cookie SameSite requirements

Preview mode is used by the Xperience administration to preview content from the live site application. The feature relies on certain cookies transmitted between the two applications to work correctly. 

If your administration and live site applications are hosted on separate domains, you need to configure the system to send cookies with the appropriate SameSite mode when communicating under preview mode. See Configuring cookie SameSite mode.

Configuring the maximum URL length

The preview URLs that the system generates for pages can be very long (they contain information about the context of the page and validation hashes). We recommend increasing the maximum allowed URL length for the application used to present the content.

  1. Edit your MVC application's web.config file.
  2. Set the maxUrlLength attribute of the httpRuntime element in the system.web section (512 should be a large enough value):

    <system.web>
    ...
    	<httpRuntime targetFramework="4.8" maxUrlLength="512" />
    ...
    </system.web>

The application can now correctly process the preview URLs generated by the system.

Clickjacking protection and preview mode

If your MVC application is protected against cross-site request forgery and clickjacking attacks using the ValidateAntiForgeryToken attribute, your application automatically sends the X-Frame-Options HTTP header with the SAMEORIGIN framing policy. The system automatically disables the header for preview URLs. This allows users to preview content handled by the MVC application in the Xperience administration interface, even when running the administration on a different domain.

Because the preview URLs could potentially be vulnerable to clickjacking attacks, the system automatically adds the Content Security Policy (CSP) HTTP response header with the frame-ancestors policy, and sets the Xperience administration site's domain as a valid source. This allows you to display previewed pages in the Xperience administration, while preventing embedding on any other domains.

Important

If you manually apply the X-Frame-Options header in your MVC site's web.config file, the preview mode and all related features (such as the page builder and form builder) in the Xperience administration display a blank page instead of the previewed content.

If you set CSP headers on your own, make sure to always whitelist the Xperience administration parent site using the frame-ancestors policy. Otherwise the preview mode and all related features will not display content.

Excluding tracking scripts for preview mode

If you use third-party analytics or tracking scripts on your website (for example Google Tag Manager scripts), we strongly recommend that you disable them for preview mode. The preview URLs are intended for internal use within the Xperience administration interface or for viewing unpublished pages. Exposing preview URLs to third parties and having them affect your website's analytics data is typically not desired.

To exclude tracking scripts for preview mode, use conditions that evaluate whether preview mode is enabled for requests. You can add the conditions directly around the script code within your site's views, or within related business code that you use to include the scripts.

Checking whether preview mode is enabled for requests

Use the following code to check whether preview mode is enabled for a request:

using Kentico.Content.Web.Mvc;

...

bool previewEnabled = System.Web.HttpContext.Current.Kentico().Preview().Enabled;

The location where you need to check the request context for preview mode depends on the implementation of your MVC application. For example, directly in the code of your controllers or when registering repositories that retrieve page content.

Tip: You can get the current page culture from the context of the preview request:

using Kentico.Content.Web.Mvc;

...

string cultureName = System.Web.HttpContext.Current.Kentico().Preview().CultureName;

Loading the latest versions of pages

For requests that have preview mode enabled, you need to ensure that your code loads the latest versions of pages instead of the published versions. For more information about retrieving page data, see Displaying page content. For example:

// Uses DocumentQuery to load article pages, getting the latest versions instead of the published versions
var articles = ArticleProvider.GetArticles()
								.LatestVersion(true)
								.Published(false)
								.OnSite("mvcsite")
								.Culture("en-us")
								.OrderByDescending("DocumentPublishFrom");

Retrieving content under workflow in AJAX calls

When retrieving the latest edited version of content under workflow within an AJAX call, you need to ensure that the call's URL is authenticated. Use the AuthenticateUrl extension method (available in the Kentico.Content.Web.Mvc namespace) to add an appropriate authentication hash to a specified URL.

$.ajax({
  url: '@Url.Kentico().AuthenticateUrl("url")',
  type: 'get',

  ...
});

If you use data caching for your pages, you need to disable it for preview mode. This ensures that caching works correctly for standard requests, but is not used for the different content displayed in preview mode.

Preview mode and controller output caching

If you use caching of controller output in your MVC application (OutputCache attributes), the Xperience integration package in your MVC application automatically ensures that the output cache is not used for page requests in preview mode.

The preview mode is now configured for the Xperience application that you use to manage your website's content.

Install the Dancing Goat MVC sample site to see an advanced example of an MVC application that uses preview mode.


Was this page helpful?