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.

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):

   Copy

   
   
   
    <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.

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;
using Kentico.Web.Mvc;
using System.Web;

...

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

using Kentico.Content.Web.Mvc;
using Kentico.Web.Mvc;
using System.Web;

...

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

using Kentico.Content.Web.Mvc;
using Kentico.Web.Mvc;
using Microsoft.AspNetCore.Http;

...

bool previewEnabled = HttpContext.Kentico().Preview().Enable;

using Kentico.Content.Web.Mvc;
using Kentico.Web.Mvc;
using Microsoft.AspNetCore.Http;

...

string cultureName = HttpContext.Kentico().Preview().CultureName;

Checking whether edit mode is enabled for requests

Use the following code to check whether edit mode (i.e., editing of pages on the Page builder tab in the Pages application) is enabled for a request:

using Kentico.Web.Mvc;
using Kentico.PageBuilder.Web.Mvc;
using System.Web;

...

bool editModeEnabled = HttpContext.Current.Kentico().PageBuilder().EditMode;

using Kentico.Web.Mvc;
using Kentico.PageBuilder.Web.Mvc;
using Microsoft.AspNetCore.Http;

...

bool editModeEnabled = HttpContext.Kentico().PageBuilder().EditMode;

Loading the latest versions of pages

For requests that have preview mode enabled, you need to ensure that your code loads the latestversions of pages instead of the published versions. It is recommended to use the IPageRetriever interface (available in the Kentico.Content.Web.Mvc namespace), as it automatically ensures that you have the correct version of content. For more information about retrieving page data, see Displaying page content.

private readonly IPageRetriever pageRetriever;

// Gets an instance of the IPageRetriever service using dependency injection
public ExampleController(IPageRetriever pageRetriever)
{
    this.pageRetriever = pageRetriever;
}

public ActionResult Index()
{
    // Retrieves pages of 'Article' page type that are in the '/Articles/May' section of the content tree
    var articles = pageRetriever.Retrieve<Article>( query => query
                    .Path("/Articles/May", PathTypeEnum.Children));
}

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

  ...
});

If you use data caching with DocumentQuery/MultiDocumentQuery 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.

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