Reference - Xperience Tag Helpers

✖
Copy to clipboard

This page serves as a reference of all ASP.NET Core Tag Helpers provided by the Xperience API.

Adding Tag Helpers to views

You can add individual Tag Helpers to your views via the @addTagHelper directive. Specify the fully qualified name of the Tag Helper class and the name of the assembly where it is located (both provided in the corresponding sections below). Alternatively, you can use the ‘*’ wildcard to include all Tag Helpers matching a specified pattern.




@* Adds all Tag Helpers from the Kentico.Content.Web.Mvc assembly to the view *@
@addTagHelper *, Kentico.Content.Web.Mvc

@* Adds the form zone Tag Helper to the view *@
@addTagHelper Kentico.Content.Web.Mvc.FormZoneTagHelper, Kentico.Content.Web.Mvc

Add the Tag Helpers in relevant _ViewImports.cshtml files to make them available in all related views automatically. 

Tag Helpers – Page builder

Page builder scripts

Fully qualified name: Kentico.Content.Web.Mvc.PageBuilderScriptsTagHelper

Assembly name: Kentico.Content.Web.Mvc

Renders markup that includes scripts required by the page builder feature. Serves as an alternative to the HtmlHelper.Kentico().PageBuilderScripts extension method.

The Tag Helper includes scripts used in the system’s editing interface, as well as those of individual page builder components (widgets, sections, inline property editors, page templates). See the linked documentation to learn how to correctly add custom scripts for your own components.




@addTagHelper Kentico.Content.Web.Mvc.PageBuilderScriptsTagHelper, Kentico.Content.Web.Mvc

<page-builder-scripts />

Page builder styles

Fully qualified name: Kentico.Content.Web.Mvc.PageBuilderStylesTagHelper

Assembly name: Kentico.Content.Web.Mvc

Renders markup that includes style sheets required by the page builder feature. Serves as an alternative to the HtmlHelper.Kentico().PageBuilderStyles extension method.

The Tag Helper includes style sheets used in the system’s editing interface, as well as those of individual page builder components (widgets, sections, inline property editors, page templates). See the linked documentation to learn how to correctly add custom style sheets for your own components.




@addTagHelper Kentico.Content.Web.Mvc.PageBuilderStylesTagHelper, Kentico.Content.Web.Mvc

<page-builder-styles />

Editable area

Fully qualified name: Kentico.Content.Web.Mvc.EditableAreaTagHelper

Assembly name: Kentico.Content.Web.Mvc

Marks a location where a page builder editable area is to be rendered when editing the page via the administration interface. Serves as an alternative to the HtmlHelper.Kentico().EditableAreaAsync extension method.

The helper has the following required attributes:

  • area-identifier– identifier of the area unique within the context of the given page.



@addTagHelper Kentico.Content.Web.Mvc.EditableAreaTagHelper, Kentico.Content.Web.Mvc

<editable-area area-identifier="areaSimple" />

Optionally, you can pass an EditableAreaOptions object via the area-options attribute to further configure the area. See Creating pages with editable areas for details.




@addTagHelper Kentico.Content.Web.Mvc.EditableAreaTagHelper, Kentico.Content.Web.Mvc
@using Kentico.PageBuilder.Web.Mvc

@{
    var options = new EditableAreaOptions
    {
        AllowedWidgets = new[] { "LearningKit.Widgets.NumberWidget",
                                 "LearningKit.Widgets.SomeOtherWidget" },
        AllowedSections = AllowedComponents.ALL
    };
}

<editable-area area-identifier="areaConfigured" area-options="options" />

Alternatively, you can pass each property of the EditableAreaOptions object as an individual attribute:

  • area-options-allowed-sections – a list of section identifiers that can be added to the area. If left empty, all sections are allowed.
  • area-options-allowed-widgets – a list of widget identifiers that can be added to the area. If left empty, all widgets are allowed.
  • area-options-default-section-identifier – identifier of the default section for the area.
  • allow-widget-output-cache – indicates whether the output of individual widgets placed into the area can be cached. This value is combined with the AllowCache property of widgets (specified during widget registration) to determine whether output caching is enabled for each widget instance contained within the area. The default value is false.
  • widget-output-cache-expires-on – a DateTimeOffset value that sets the absolute expiration date for cached content.
  • widget-output-cache-expires-after – a TimeSpan value that sets the length of time from the first request time to cache the contents.
  • widget-output-cache-expires-sliding – a TimeSpan value that defines a sliding window of expiration for the cached content. Content not accessed within the specified time frame gets evicted.

Note that if you both pass the options object and specify some parameters directly via attributes, the parameters specified via attributes take precedence (i.e., override the corresponding properties of the options object).

Cache configuration examples

The caching configuration options are modeled after and behave identically to the Cache tag helper provided by ASP.NET Core:




@* widget-output-cache-expires-on *@
@* Sets the cached entry to expire on 5:02 PM on January 29, 2025. If the specified date is in the past, nothing gets cached. *@
<editable-area area-identifier="editableArea" area-widget-output-cache="true" widget-output-cache-expires-on="@new DateTime(2025,1,29,17,02,0)" />

@* widget-output-cache-expires-after *@
@* Contents are evicted after five minutes and cached again on subsequent requests. *@
<editable-area area-identifier="editableArea" area-widget-output-cache="true" widget-output-cache-expires-after="@TimeSpan.FromSeconds(300)" />

@* widget-output-cache-expires-sliding *@
@* Cached content is evicted if not accessed again within 120 seconds of the initial request. *@
<editable-area area-identifier="editableArea" area-widget-output-cache="true" widget-output-cache-expires-sliding="@TimeSpan.FromSeconds(120)" />

Widget zone

Fully qualified name: Kentico.Content.Web.Mvc.WidgetZoneTagHelper

Assembly name: Kentico.Content.Web.Mvc

Marks a location where widgets can be placed within a page builder section. Serves as an alternative to the HtmlHelper.Kentico().WidgetZoneAsync extension method.

Every section must contain at least one widget zone – sections without widget zones are not supported.




@addTagHelper Kentico.Content.Web.Mvc.WidgetZoneTagHelper, Kentico.Content.Web.Mvc

<widget-zone />

The helper also has the following optional attributes:

  • zone-name – identifier of the zone used when changing the type of the zone in the page builder.
  • allowed-widgets – a list of widget identifiers that can be added to the zone. If left empty, all widgets are allowed.



@{
    var widgetsWhitelist = new[] { Kentico.Content.Web.Mvc.SystemComponentIdentifiers.FORM_WIDGET_IDENTIFIER,
                                   "LearningKit.Widgets.NumberWidget",
                                   "LearningKit.Widgets.SomeOtherWidget" };
}

<widget-zone zone-name="main-zone" allowed-widgets="widgetsWhitelist" />

Page data

Fully qualified name: Kentico.Content.Web.Mvc.WidgetZoneTagHelper

Assembly name: Kentico.Content.Web.Mvc

Renders an invisible form field that includes contextual information about the page. Necessary when developing components that use POST actions. Serves as an alternative to the HtmlHelper.Kentico().PageData extension metod.




@addTagHelper Kentico.Content.Web.Mvc.PageDataTagHelper, Kentico.Content.Web.Mvc

<form asp-controller="Controller" asp-action="HandlePost" id="form">

    ...

    <page-data />

    <input type="submit" value="Submit" />
</form>

Component properties data

Fully qualified name: Kentico.Content.Web.Mvc.ComponentPropertiesDataTagHelper

Assembly name: Kentico.Content.Web.Mvc

Used to persist properties of the currently rendered component for POST actions. Server as an alternative to the HtmlHelper.Kentico().ComponentPropertiesData extension method. 




@addTagHelper Kentico.Content.Web.Mvc.ComponentPropertiesDataTagHelper, Kentico.Content.Web.Mvc

<form asp-controller="Controller" asp-action="HandlePost" id="form">

    ...

    <component-properties-data />

    <input type="submit" value="Submit" />
</form>

Stand-alone widget

Fully qualified name: Kentico.Content.Web.Mvc.StandaloneWidgetTagHelper

Assembly name: Kentico.Content.Web.Mvc

Renders a specified widget directly. Serves as an alternative to the HtmlHelper.Kentico().RenderStandaloneWidgetAsync extension method. See Rendering widgets directly.

The helper has the following attributes:

  • widget-type-identifier– the string identifier under which the widget was registered.
  • (Optional) widget-properties – IWidgetProperties object representing the widget’s properties . Create an instance of the appropriate property model class and set any required values.



@addTagHelper Kentico.Content.Web.Mvc.StandaloneWidgetTagHelper, Kentico.Content.Web.Mvc
@using Kentico.Forms.Web.Mvc.Widgets
@using Kentico.Content.Web.Mvc

@{
    var widgetProperties = new FormWidgetProperties()
    {
        SelectedForm = "FormCodeName"
    };
}

@* Renders the system's default Form widget *@
<standalone-widget widget-type-identifier="@SystemComponentIdentifiers.FORM_WIDGET_IDENTIFIER" widget-properties="widgetProperties" />

Nested widget

Fully qualified name: Kentico.Content.Web.Mvc.NestedWidgetTagHelper

Assembly name: Kentico.Content.Web.Mvc

Renders a widget nested inside another widget. Serves as an alternative to the HtmlHelper.Kentico().RenderNestedWidgetAsync extension method. See Extending widgets. 




@addTagHelper Kentico.Content.Web.Mvc.NestedWidgetTagHelper, Kentico.Content.Web.Mvc

@* In this example, the extended widget uses an extended FormWidgetProperties class *@
@model ComponentViewModel<ExtendedFormWidgetProperties>
@* Renders the system's default Form widget as the nested widget *@
<nested-widget widget-type-identifier="@SystemComponentIdentifiers.FORM_WIDGET_IDENTIFIER" widget-properties="Model.Properties" />

Tag Helpers – Form builder

Form zone

Fully qualified name: Kentico.Content.Web.Mvc.FormZoneTagHelper

Assembly name: Kentico.Content.Web.Mvc

Marks a location where form components can be placed within a form section. Serves as an alternative to the HtmlHelper.Kentico().FormZoneAsync extension method.




@addTagHelper Kentico.Content.Web.Mvc.FormZoneTagHelper, Kentico.Content.Web.Mvc

<form-zone />

The helper also has the following optional attributes:- zone-name – identifier of the zone used when changing the type of the zone in the page builder.




<form-zone zone-name="main-zone" />

Tag Helpers – Caching

Cache dependency

Fully qualified name: Kentico.Web.Mvc.Caching.CacheDependencyTagHelper

Assembly name: Kentico.Web.Mvc

Allows for specification of dependency cache keys within the Cache tag helper element. See Caching page output in ASP.NET Core applications and Setting cache dependencies.

The helper has the following attributes:

  • cache-keys – an array of cache dependency dummy keys.
  • enabled – indicates whether the dependencies get injected. Enabled by default.



@addTagHelper Kentico.Web.Mvc.Caching.CacheDependencyTagHelper, Kentico.Web.Mvc

@{
    var userCacheKeys = new[] { "cms.user|all" };

    var enabled = false;
}
<cache enabled="@enabled">
    @* Clears the cached data whenever a user object is modified *@
    <cache-dependency cache-keys="@userCacheKeys" enabled="@enabled" />

    Time: @DateTime.Now
</cache>