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
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 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:
<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.
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 and set it to false
:
@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:
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 theasp-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 (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:
RequestResponse@model MyComponent <sc-link asp-for="MyLink"></sc-link>
NoteIf 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 theasp-for
attribute on ana
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:
@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" />
When rendered in the Experience Editor, 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 theasp-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:
@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>
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 theasp-for
attribute on animg
HTML element:RequestResponse@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&hash=F313AD90AE547CAB09277E42509E289B&mw=100&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}))"
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:
RequestResponse@model MyComponent <sc-number asp-for="MyNumber" />
-
Add the name of a
Number
property in theasp-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:
@model MyComponent
<sc-number asp-for="MyNumber" number-format="C" culture="en-us"></sc-number>
The Number tag helper supports standard .NET numeric format strings.