Adding preview mode support

Preview mode in Kentico provides a way to view the latest version of pages before they are published (for example when using Workflow). If you wish to use preview mode in an MVC application that handles the presentation of the website’s pages, you need to implement the required functionality in the application’s code.

Before you can use preview URLs, you need to specify the URL pattern (in Kentico administration) for your content-only page types. The URL pattern is then used to create URLs to the Kentico content presented by an external application. Preview URL 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 -> General -> Preview URL. See: Sending links to unpublished pages

The preview URLs the system generates for content-only pages consist of additional information, such as language version and a hash for validating the URL. The Kentico integration package in your MVC application validates and processes the preview URL. The page is then displayed through the standard routing process (internally using the presentation URL based on the URL pattern).

Enabling preview mode in MVC applications

To enable preview support in your MVC application:

1. Specify a URL pattern for content-only pages.

2. Open your MVC project in Visual Studio.

3. Enable the preview feature for your MVC application by calling the UsePreview() method of the ApplicationBuilder instance.

   • Enable the feature at the start of your application’s life cycle, for example in the Application_Start method of your project’s Global.asax file.

     MVC projects created by the installer contain the ApplicationConfig class, whose RegisterFeatures method is called in the Application_Start method by default. You can use this class to encapsulate all of your ApplicationBuilder code (enabling and configuring of Kentico MVC features).

     Copy

     
     
     
       using Kentico.Web.Mvc;
       using Kentico.Content.Web.Mvc;
     
       ...
     
       protected void Application_Start()
       {
           ...
     
           // Gets the ApplicationBuilder instance
           // Allows you to enable and configure selected Kentico MVC integration features
           ApplicationBuilder builder = ApplicationBuilder.Current;
     
           // Enables the preview feature
           builder.UsePreview();
     
           ...
       }
     
     
       

Configuring the maximum URL length

The preview URLs that the system generates for content-only pages can be very long (they contain information about the virtual 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.6.1" 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 UsePreview feature disables the header for preview URLs. This allows users to preview content handled by the MVC application in the Kentico administration interface, even when running the administration on a different domain.

Because the preview URLs could potentially be vulnerable to clickjacking attacks, the UsePreview feature automatically adds the Content Security Policy (CSP) HTTP response header with the frame-ancestors policy, and sets the Kentico administration site’s domain as a valid source. This allows you to display previewed pages in the Kentico 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 Kentico 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 make use of your generated providers.

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 Generating classes for Kentico objects. 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");

$.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 should now work correctly for the Kentico application that you use to manage your website’s content.