Xperience Page Builder Utilities

Packages

• XperienceCommunity.PageBuilderUtilities

• XperienceCommunity.PageBuilderTagHelpers

Dependencies

These libraries are compatible with ASP.NET Core 3.1 -> ASP.NET Core 5 and are designed to be used with the Xperience 13.0 Content Delivery (MVC) application running on ASP.NET Core.

Page Builder Utilities

This library provides an abstraction over the Kentico Xperience Page Builder rendering mode so that developers can conditionally execute code based on the mode of a given HTTP request to their ASP.NET Core application.

How to Use?

1. First, install the NuGet package in your ASP.NET Core project:

   dotnet add package XperienceCommunity.PageBuilderUtilities

2. Add the required types to the DI container in your Startup.cs file

   public void ConfigureServices(IServiceCollection services)
   {
       services.AddPageBuilderContext();
   }

3. You can now use the IPageBuilderContext from XperienceCommunity.PageBuilderUtilities as a constructor dependency anywhere in your application to more easily determine the state of the current request:

   public class ProductsController
   {
       private readonly IPageBuilderContext context;
   
       public ProductsController(IPageBuilderContext context) =>
           this.context = context;
   
       public ActionResult Index()
       {
           if (context.IsEditMode)
           {
               // ...
           }
   
           if (context.IsLivePreviewMode)
           {
               // ...
           }
   
           if (context.IsLiveMode)
           {
               // ...
           }
   
           if (context.IsPreviewMode)
           {
               // ...
           }
       }
   }

4. By not using IHttpContextAccessor and all the Kentico Xperience extension methods, your code is both easier to unit test and read.

5. You can inject this type into your Razor views, but the better option is to use ... 👇

Page Builder Tag Helpers

This library provides an ASP.NET Core Tag Helper for Kentico Xperience 13.0 to help toggle HTML in Razor views based on the Page Builder 'mode' of the request to the ASP.NET Core application.

How to Use?

1. First, install the NuGet package in your ASP.NET Core project

   dotnet add package XperienceCommunity.PageBuilderTagHelpers

2. Add the required types to the DI container in your Startup.cs file

   public void ConfigureServices(IServiceCollection services)
   {
       services.AddPageBuilderContext();
   }

   • Note: This extension method comes from the XperienceCommunity.PageBuilderUtilities package, above, which is a dependency of XperienceCommunity.PageBuilderTagHelpers

3. Include the tag helper assembly name in the ~/Views/_ViewImports.cshtml

   @addTagHelper *, XperienceCommunity.PageBuilderTagHelpers

4. Use the tag helper in your Razor views

   <page-builder-mode exclude="Live">
     <!-- will be displayed in Edit and LivePreview modes -->
     <h1>Hello!</h1>
   </page-builder-mode>
   
   <page-builder-mode include="LivePreview, Edit">
     <!-- will be displayed in Edit and LivePreview modes -->
     <h1>Hello!</h1>
   </page-builder-mode>
   
   <page-data-context> <!-- or <page-data-context initialized="true"> -->
     <!-- will be displayed only if the IPageDataContext is popualted -->
     <widget-zone />
   </page-data-context>
   
   <page-data-context initialized="false">
     <!-- will be displayed only if the IPageDataContext is not populated -->
     <div>widget placeholder!</div>
   </page-data-context>

References

Real World Examples

• Kentico Xperience: MVC Widget Experiments Part 2 - Page Specific Marketing Tags with Widgets
• Kentico Xperience: MVC Widget Experiments Part 3 - Unused Widgets Section

ASP.NET Core

• Using Tag Helpers
• Authoring Tag Helpers
• ASP.NET Core - Environment Tag Helper (source)

Kentico Xperience

• Using Xperience 13.0 Built-in Tag Helpers