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

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

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

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

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

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 Kentico administration display a blank page instead of the previewed content.

If you set CSP headers on your own, make sure to always whitelist the Kentico 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 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.

Tip: If the URL pattern that you use for your content-only pages does not include a variable for the page culture (for example if you use a different mechanism to pass the requested culture), you can get the 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 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");


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 Kentico integration package in your MVC application automatically ensures that the output cache is not used for page requests in preview mode.

Preview mode should now work correctly for the Kentico application that you use to manage your website’s content.

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