Tag helpers

Version: 0.x (alpha public release)

ASP.NET Core tag helpers enable server-side code to participate in creating and rendering HTML elements in Razor files.

The ASP.NET Core SDK provides standard tag helpers for rendering content, placeholder data, and metadata required for page editing. Tag helpers are available in the RenderingEngineConstants.SitecoreTagHelpers class.

Note

You must use an explicit closing tag with ASP.NET Core tag helpers that create or modify element content. If your tag is self-closing, there is no place for the tag helper to insert your field value.

To ensure the Sitecore tag helpers are available in the rendering host application, you must import the namespace of the library that contains the tag helpers in the \Views\_ViewImports.cshtml Razor view:

RequestResponse
@addTagHelper *, Sitecore.AspNetCore.SDK.RenderingEngine

Placeholder tag helper

The Placeholder tag helper can render the components defined in a Sitecore placeholder. By default, the tag helper also supports the rendering of multiple levels of nested placeholders.

When the page is in edit mode, the tag helper renders editing chromes in addition to components.

To use this tag helper, you add it as a standalone tag:

RequestResponse
<sc-placeholder name="main"></sc-placeholder>

The name attribute is required, and its value must match the name of a placeholder returned by the Experience Edge for the current component. If the name is invalid or unmatched, the tag helper renders a warning on the page using an HTML comment.

Note

The Placeholder tag helper is the entry point for rendering components based on Experience Edge output. You typically find one or more instances of this tag helper in the view returned by any controller action that is tagged with [UseSitecoreRendering].

Text Field tag helper

The Text Field tag helper can render and edit the content of single-line and multiline text fields when the page is in edit mode.

To use this tag helper, you add the name of a TextField property in the asp-for attribute of an HTML element:

RequestResponse
@model MyComponentModel
<h2 asp-for="@Model.Heading"></h2>

To disable translating newline characters into HTML break tags, add the convert-new-lines attribute and set it to false:

RequestResponse
@model MyComponentModel
<div asp-for="@Model.Description" convert-new-lines="false"></div>

To disable editing of a text field, add the editable attribute and set it to false:

RequestResponse
@model MyComponentModel
<div asp-for="@Model.Description" editable="false"></div>

Rich Text Field tag helper

The Rich Text Field tag helper can render and edit the content of Sitecore rich text fields when the page is in edit mode.

You can use this tag helper in two ways:

  • Add it as a standalone tag:

    RequestResponse
    @model MyComponentModel
    <sc-text asp-for="@Model.Content"></sc-text>

    This is often preferred because Sitecore rich text fields have their own root <p> tag, and this method does not introduce a new element to the DOM.

  • Add the name of a RichField property in the asp-for attribute on an HTML element:

    RequestResponse
    @model MyComponentModel
    <div asp-for="@Model.Content"></div>

To disable editing of a rich text field, add the editable attribute and set it to false:

RequestResponse
@model MyComponentModel
<sc-text asp-for="@Model.Content1" editable="false"></sc-text>
<div asp-for="@Model.Content2" editable="false"></div>

The Hyperlink tag helper can render and edit the content of Sitecore general link fields when the page is in edit mode.

You can use this tag helper in two ways:

  • Add it as a standalone tag:

    RequestResponse
    @model MyComponent
    <sc-link asp-for="MyLink"></sc-link>
    Note

    If you do not want the content author to configure a link text, you can add a static link text:

    RequestResponse
    @model MyComponent
    <sc-link asp-for="MyLink">This is my <b>custom</b> text</sc-link>
  • Add the name of a HyperLinkField property in the asp-for attribute on an a HTML element:

    RequestResponse
    @model MyComponentModel
    <a asp-for="@Model.MyLink">It is my link!</div>

Besides the href attribute, the tag helper renders the following attributes (if provided in the field properties):

  • class

  • target

  • title

You can override these attributes or add additional ones:

RequestResponse
@model MyComponent
<sc-link asp-for="MyLink" class="font-weight-bold" data-otherattributes="pass-through-to-anchor-tag">Link to Sitecore</sc-link>

To disable editing of a hyperlink field, add the editable attribute and set it to false:

RequestResponse
@model MyComponentModel
<sc-link asp-for="MyLink" editable="false" />
Note

When rendered in XM Cloud Pages, link tag helpers with custom content do not render their content. This is to allow WYSIWYG editing. Consider setting editable="false" and using the Field Editor for these cases.

Date tag helper

The Date tag helper can render and edit the content of Sitecore date fields when the page is in edit mode.

You can use this tag helper in two ways:

  • Add it as a standalone tag:

    RequestResponse
    @model MyComponent
    <sc-date asp-for="MyDate"></sc-date>
  • Add the name of a Date property in the asp-for attribute on an HTML element:

    RequestResponse
    @model MyComponent
    <span asp-for="MyDate" ></span>

You can specify the format of the date with the date-format attribute and the culture with the culture attribute. If no date-format attribute is specified, the tag helper shows the local format. If no culture attribute is specified, the tag helper shows the current culture format:

RequestResponse
@model MyComponent
<sc-date asp-for="Date" date-format="d" culture="en-us"></sc-date>
<sc-date asp-for="Date" date-format="MM/dd/yyyy HH:mm:ss" culture="en-us"></sc-date>
Note

The date tag helper supports standard .NET date and time format strings.

Image Field tag helper

The Image Field tag helper can render and edit the content of Sitecore image fields when the page is in edit mode.

You can use this tag helper in two ways:

  • Add it as a standalone tag:

    RequestResponse
    @model MyComponentModel
    <sc-img asp-for="@Model.Image" />
  • Add the name of a ImageField property in the asp-for attribute on an img HTML element:

    RequestResponse
    @model MyComponentModel
    <img asp-for="@Model.Image" />

To disable editing of an image field, add the editable attribute and set it to false:

RequestResponse
@model MyComponentModel
<sc-img asp-for="@Model.Image" editable="false" />
<img asp-for="@Model.Image" editable="false" />

You can pass additional parameters to Image tag helpers to perform server-side resizing of the image:

RequestResponse
@model MyComponentModel
<img asp-for="@Model.Image" image-params="new { mw = 100, mh = 50 }" />

All the parameters provided in this attribute are added to the image URL like this:

RequestResponse
https://<hostname>/-/jssmedia/<YOUR_SITE>/data/media/img/sc_logo.png?iar=0&amp;hash=F313AD90AE547CAB09277E42509E289B&amp;mw=100&amp;mh=50

If you want to render an image field with resizing parameters outside a tag helper, you can use the GetMediaLink extension for ImageField.:

RequestResponse
style="background-image: url(@Model.Banner?.GetMediaLink(new {mw = 1170mh = 402}))"
Important

All the parameters you pass in the image-params attribute or GetMediaLink must be allowlisted for resizing to occur.

The following is an example configuration patch:

RequestResponse
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"> 
  <sitecore> 
    <javaScriptServices> 
      <allowedMediaParams> 
        <projectName__1>mw=42,mh=42</projectName__1> 
      </allowedMediaParams> 
    </javaScriptServices> 
  </sitecore> 
</configuration> 

Number tag helper

The Number tag helper can render and edit the content of Sitecore number fields when the page is in edit mode.

You can use this tag helper in two ways:

  • Add the tag helper as a standalone tag:

    RequestResponse
    @model MyComponent
    <sc-number asp-for="MyNumber" />
  • Add the name of a Number property in the asp-for attribute on an HTML element:

    RequestResponse
    @model MyComponent
    <span asp-for="MyNumber" ></span>

You can specify the format of the number with the number-format attribute and the culture attribute. If no culture attribute is specified, the tag helper shows the current culture format:

RequestResponse
@model MyComponent
<sc-number asp-for="MyNumber" number-format="C" culture="en-us"></sc-number>
Note

The Number tag helper supports standard .NET numeric format strings.

Do you have some feedback for us?

If you have suggestions for improving this article,