Tag helpers

Abstract

Overview of the Sitecore ASP.NET Rendering SDK tag helpers.

In ASP.NET, tag helpers enable server side code to participate in creating and rendering HTML elements in Razor files. More information about tag helpers can be found in the Microsoft tag helpers documentation.

The Sitecore ASP.NET Rendering SDK provides several custom tag helpers for rendering content, placeholder data, and metadata required for page editing.

The following tag helpers are available in the Sitecore.AspNet.RenderingEngine library:

  • Placeholder tag helper

  • Text Field tag helper

  • Rich Text Field tag helper

  • Hyperlink tag helper

  • Date tag helper

  • Image tag helper

  • Number tag helper

Note

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

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:

@addTagHelper *, Sitecore.AspNet.RenderingEngine

Placeholder tag helper

The Placeholder tag helper can render the components defined in a Sitecore placeholder. By default, the tag helper also supports 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:

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

The name attribute is required, and its value must match the name of a placeholder returned by the Layout Service 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 Layout Service 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:

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

To disable translating newline characters into HTML break tags, add the convert-new-lines attribute ( true by default):

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

To disable editing of a Text Field, add the editable attribute (true by default):

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

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

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

To disable editing of a Rich Text field, add the editable attribute (true by default):

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

Hyperlink tag helper

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:

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

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

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

@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 (true by default):

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

Note

When rendered in the Experience Editor, link tag helpers with custom contents 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:

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

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

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

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

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

To disable editing of an Image Field, add the editable attribute (true by default):

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

@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: http://<Content Delivery server>/-/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.:

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

Important

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

The following is an example configuration patch:

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

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

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

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