Tag Helpers

Tag Helpers are extensions of existing HTML tags. They can extend the functionality of a tag or even create completely new tags. Smartstore has created a lot of Tag Helpers to write simple and clear code and for better productivity.

How To Use Tag Helpers

To use the Smartstore Tag Helpers in your Views, you'll need to reference specific libraries. You can do this either in your View file or by using _ViewImports.cshtml (recommended). Add the following lines and IntelliSense should recognise the Tag Helpers.

//for public Tag Helpers
@addTagHelper Smartstore.Web.TagHelpers.Public.*, Smartstore.Web.Common

//for shared Tag Helpers
@addTagHelper Smartstore.Web.TagHelpers.Shared.*, Smartstore.Web.Common

//for admin Tag Helpers
@addTagHelper Smartstore.Web.TagHelpers.Admin.*, Smartstore.Web.Common

To learn more about _ViewImports.cshtml, check out this tutorial.

Try it out!

Type: <span s You should see a suggestion for sm-if, which is part of Smartstore's IfTagHelper.

A quick example:

<span sm-if="@Model.visible">Here I am!</span>

Smartstore Tag Helpers

Smartstore differentiates between three kinds of Tag Helpers.

• Public: Used in frontend

• Shared: Used in both front- and backend

• Admin: Used in backend

You can find the code to Smartstore Tag Helpers in Smartstore.Web.Common/TagHelpers/.

Public

Captcha Tag Helper

The CaptchaTagHelper creates a CAPTCHA.

<captcha sm-enabled="Model.DisplayCaptcha" />

It also supports the sm-enabled attribute.

ConsentScript Tag Helper

The ConsentScriptTagHelper allows a script to be loaded immediately after cookie consent is given. Otherwise it is loaded after a page refresh.

<script sm-consent-type="Analytics">

• sm-consent-type: The type of cookie the user needs to accept.

Honeypot Tag Helper

The HoneypotTagHelper is Smartstore's cyber-security implementation of the Honeypot mechanism.

<honeypot />

It also supports the sm-enabled attribute.

Shared

Attributes Tag Helper

The AttributesTagHelper adds attributes to the element. It can be used in two ways:

• Adding a collection of attributes to the element.

• Adding an attribute, if it evaluates to true.

@{
    var attributes = new AttributeDictionary().Merge(ConvertUtility.ObjectToDictionary(ViewData["htmlAttributes"] ?? new object()));
}
<span attrs="attributes">I might have some attributes</span>

//or

<input type="checkbox" attr-checked='(node.HasChildren, "checked")' />

CollapsedContent Tag Helper

The CollapsedContentTagHelper collapses the element to a maximum height. It also adds Show more or Show less to the element.

<collapsed-content sm-max-height="50">
    Odit non aspernatur sunt ipsum dolorem nihil quibusdam earum.<br />
    Eius nulla magni cum cum delectus sit omnis. Quam aut itaque ut.<br />
    Adipisci nihil enim aut eos voluptas et. Iure ut maxime ut qui.<br />
    Impedit adipisci laborum quia pariatur. Laboriosam voluptatibus<br />
    atque qui minima et ut deleniti.<br />
    <br />
    Debitis beatae aut aut iusto non consequuntur. Et inventore placeat<br />
    alias ut consequatur corrupti. Ut qui laboriosam amet tempora velit<br />
    sed est. Dolorem doloremque reiciendis voluptatem quasi nemo<br />
    perferendis quo. Voluptas exercitationem consequatur dolorum omnis<br />
    porro necessitatibus dignissimos qui.<br />
    <br />
    Consectetur et corporis vel voluptas autem libero magnam. Mollitia<br />
    pariatur placeat ut. Dolores quidem molestiae dolore ut accusamus<br />
    quam dolorem iure. Nihil optio voluptatibus eum quis.<br />
    <br />
    Officia a accusantium nihil voluptas et. Error aut labore est qui<br />
    rem. Fugiat perspiciatis repellendus voluptatem aut qui dolorem.
</collapsed-content>

To specify the maximum number of pixel you want to show, add the sm-max-height attribute. Otherwise the catalog's default setting will be used.

Confirm Tag Helper

The ConfirmTagHelper adds a confirm button. There are many ways to customise it.

<confirm button-id="entry-delete" />

<confirm message="@T("Common.AreYouSure")" button-id="entry-delete" icon="fas fa-question-circle" action="EntryDelete" type="Action" />

It also supports these attributes:

• action: Action to execute, if confirmed. Default: Delete

• controller: Controller to search for action. Default: ViewContext.RouteData.Values.GetcontrollerName()

• form-post-url

• type: Type of confirm action. Default: Delete

• backdrop: Button has a backdrop. Default: true

• title: Title of the dialog.

• accept-button-color: Color of the accept button.

• accept-text: Custom accept button text.

• cancel-text: Custom cancel button text.

• center: Dialog is centered vertically. Default: true

• center-content: Dialog is centered. Default: false

• size: Size of the dialog. Possible values: Small, Medium, Large, Flex, FlexSmall. Default: Medium

• message: Custom display message.

• icon: Icon class.

• icon-color: Custom icon color.

FileIcon Tag Helper

The FileIconTagHelper display a file icon.

<file-icon file-extension="@Model.FileExtension" show-label="true" badge-class="badge-info"/>

It also supports these attributes:

• label: Custom label. Default: the files extension

FileUploader Tag Helper

The FileUploaderTagHelper adds a highly customisable way to upload files.

Here is an excerpt from Smartstore.Web/Views/Customer/Avatar.cshtml to show this.

Avatar.cshtml

<file-uploader 
    file-uploader-name="uploadedFile"
    upload-url='@Url.Action("UploadAvatar", "Customer")'
    type-filter="image"
    display-browse-media-button="false"
    display-remove-button="fileId != 0"
    display-remove-button-after-upload="true"
    upload-text='@T("Common.FileUploader.UploadAvatar")'
    onuploadcompleted="onAvatarUploaded"
    onfileremoved="onAvatarRemoved"
    multi-file="false"
    has-template-preview="true" />

The default value for the attribute media-path is SystemAlbumProvider.Files.

If Tag Helper

The IfTagHelper adds a conditional attribute to the element. The output is suppressed, if the condition evaluates to false.

<span sm-if="@Model.visible">Here I am!</span>

MinifyTagHelper Tag Helper

The MinifyTagHelper allows an inline script to be minified automatically, before being loaded. Default: false

<script sm-minify="true">

This should not be used if the script contains dynamic content like:

• SessionId

• A randomly generated ID

• User related data

• Model data

The Tag-Helper has no effect in combination with the src attribute.

SuppressIfEmpty Tag Helper

The SuppressIfEmptyTagHelper adds a conditional attribute to the element. The output is suppressed, if the condition is true and the element is empty or only contains whitespaces.

@{
    bool condition = true;
}

<div id="div1" sm-suppress-if-empty="condition">
    @* I will be suppressed *@
</div>

<div id="div2" sm-suppress-if-empty="condition">
    I won't be suppressed!
</div>

<div id="div3" sm-suppress-if-empty="!condition">
    @* I won't be suppressed *@
</div>

SuppressIfEmptyZone Tag Helper

The SuppressIfEmptyZoneTagHelper suppresses the output, if the targeted zone is empty or only contains whitespaces.

Here is an excerpt from Smartstore.Web/Views/ShoppingCart/Partials/OffCanvasShoppingCart.cshtml to show this.

<div sm-suppress-if-empty-zone="offcanvas_cart_summary" class="offcanvas-cart-external-checkout">
    <div class="heading heading-center py-0">
        <h6 class="heading-title fs-h5 fwn">@T("Common.Or")</h6>
    </div>
    <div class="d-flex justify-content-center align-items-center flex-wrap flex-column">
        <zone name="offcanvas_cart_summary" />
    </div>
</div>

TagName Tag Helper

The TagNameTagHelper changes the tag at runtime.

<span sm-tagname="div">I always wanted to be a div...</span>

Widget Tag Helper

The WidgetTagHelper adds HTML content and injects it into a zone. More information can be found in Widgets.

<widget target-zone="my_widget_zone">
    <span>Widget content</span>
</widget>

The key attribute makes sure only one instance of the widget is included in the zone.

Zone Tag Helper

The ZoneTagHelper defines an zone for widgets to inject content. More information can be found in Widgets.

<zone name="a_widget_drop_zone_name"/>

It also supports these attributes:

• model: Declare what model to use within the zone.

• replace-content: Replace content, if at least one widget is rendered.

• remove-if-empty: Remove the root zone tag, if it has no content. Default: false

• preview-disabled: If true, the zone preview will not be rendered. This is important for script or style zones that should not be printed. Default: false

• preview-class: Additional CSS classes for the span tag. For example, position-absolute to better control the layout flow.

• preview-style: CSS style definitions. For example, to set an individual max-width.

Controls

EntityPicker Tag Helper

The EntityPickerTagHelper adds an element to pick one or more entities from a larger group.

<entity-picker asp-for="Rotator" max-items="100" entity-type="product" dialog-title="Search" />

It also supports these attributes:

• entity-type: Entity type to be picked. Default: product

• target-input-selector: Identifier of the target input, defined by field-name.

• caption: Caption of the dialog.

• icon-css-class: Icon of the button that opens the dialog. Default: fa fa-search

• dialog-title: Title of the dialog.

• disable-grouped-products: Disable search for grouped products.

• disable-bundle-products: Disable search for bundle products.

• disabled-entity-ids: Ids of disabled entities.

• selected: Ids of selected entities.

• enable-thumb-zoomer: Enables the thumb zoomer.

• highlight-search-term: Highlight search term in search results. Default: true

• max-items: Maximum number of selectable items.

• append-mode: Append selected entity ids to already chosen entities. Default: true

• delimiter: Entity id delimiter. Default: ,

• field-name: Fieldname of [target-input-selector] to paste selected ids. Default: id

• ondialogloading: JS function called before dialog is loaded.

• ondialogloaded: JS function called after dialog is loaded.

• onselectioncompleted: JS function called after selection.

Menu Tag Helper

The MenuTagHelper adds a menu widget.

<menu name="Main" template="Categories"></menu>

Modal Tag Helper

The ModalTagHelper adds a customisable modal dialog. It works in combination with:

• ModalHeaderTagHelper

• ModalBodyTagHelper

• ModalFooterTagHelper

Here is an excerpt from Smartstore.Web/Areas/Admin/Views/Theme/Configure.cshtml to show this.

Configure.cshtml

<modal id="importvariables-window">
    <modal-header sm-title="@T("Admin.Configuration.Themes.ImportVars")"></modal-header>
    <modal-body>
        <form enctype="multipart/form-data" method="post" asp-action="ImportVariables" asp-route-theme="@Model.ThemeName" asp-route-storeId="@Model.StoreId">
            <p class="text-muted">
                @T("Admin.Configuration.Themes.ImportVars.Note")
            </p>
            <div>
                @T("Admin.Configuration.Themes.ImportVars.XmlFile"): <input type="file" id="importxmlfile" name="importxmlfile" />
            </div>
        </form>
    </modal-body>
    <modal-footer>
        <button type="button" class="btn btn-secondary btn-flat" data-dismiss="modal">
            <span>@T("Admin.Common.Cancel")</span>
        </button>
        <button id="importxmlsubmit" type="button" class="btn btn-primary">
            <span>@T("Common.Import")</span>
        </button>
    </modal-footer>
</modal>

The ModalTagHelper also supports these attributes:

• sm-size: Size of the dialog. Possible values: Small, Medium, Large, Flex, FlexSmall. Default: Medium

• sm-fade: Show fade animation. Default: true

• sm-focus: Has focus. Default: true

• sm-backdrop: Backgrop behaviour. Possible values: Show, Hide, Static, Inverse, Invisible. Default: Show

• sm-show: Show the dialog immidiately. Default: true

• sm-close-on-escape-press: Dialog closes on pressing Esc. Default: true

• sm-center-vertically: Center content vertically. Default: false

• sm-center-content: Center content. Default: false

• sm-render-at-page-end: Insert dialog at the end of the page. Default: true

The ModalHeaderTagHelper also supports these attributes:

• sm-title: The dialog title.

• sm-show-close: Show close button. Default: true

The ModalBodyTagHelper also supports these attributes:

• sm-content-url: URL to content. Content is included via iframe.

Pagination Tag Helper

The PaginationTagHelper adds pagination.

<pagination sm-list-items="Model.MySubscriptions" />

Pass an IPageable object that should be paged, using the sm-list-items attribute.

It also supports these attributes:

• sm-list-items

• sm-alignment: Element alignment. Possible values: Left, Centered, Right. Default: Centered

• sm-size: Element size. Possible values: Mini, Small, Medium, Large. Default: Medium

• sm-style: Element style. Possible values: Pagination, Blog

• sm-show-first: Always show first page. Default: false

• sm-show-last: Always show last page. Default: false

• sm-show-next: Always show next page. Default: true

• sm-show-previous: Always show previous page. Default: true

• sm-max-pages: Maximum number of displayed pages. Default: 8

• sm-skip-active-state

• sm-item-title-format-string

• sm-query-param: Default: page

TabStrip Tag Helper

The TabStripTagHelper adds a tab strip. It works with the TabTagHelper.

<tabstrip id="tab-example" sm-nav-style="Material" sm-nav-position="Top">
    <tab sm-title="First Tab" sm-selected="true">
        <partial name="Tab1" model="TabModel" />
    </tab>
    <tab sm-title="Second Tab" sm-selected="true">
        <partial name="Tab2" model="TabModel" />
        </tab>
</tabstrip>

The TabStripTagHelper also supports these attributes:

• sm-hide-single-item: Hide navigation on single tab. Default: true

• sm-responsive: Collapse navigation on smaller screens. Default: false

• sm-nav-position: Position of the navigation. Possible values: Top, Right, Below, Left Default: Top

• sm-nav-style: Style of the navigation. Possible values: Tabs, Pills, Material.

• sm-fade: Add fade animation. Default: true

• sm-smart-tab-selection: Reselect active tab on reload. Default: true

• sm-onajaxbegin

• sm-onajaxsuccess

• sm-onajaxfailure

• sm-onajaxcomplete

• sm-publish-event: Fires the TabStripCreated event. Default: true

The TabTagHelper also supports these attributes:

• sm-name

• sm-title

• sm-selected

• sm-disabled

• sm-visible: Tab visibility. Default: true

• sm-hide-if-empty: Default: false

• sm-ajax: Load content with AJAX

• sm-icon

• sm-icon-class

• sm-badge-text

• sm-badge-style: Badge Style. Possible values: Secondary, Primary, Success, Info, Warning, Danger, Light, Dark.

• sm-image-url

• sm-adaptive-height: Responsive height. Default: false

Forms

AjaxForm Tag Helper

The AjaxFormTagHelper adds unobtrusive AJAX to a form.

<form sm-ajax method="post" asp-area="" asp-action="Do" sm-onsuccess="OnDo@(Model.Id)" sm-loading-element-id="#do-prog-@(Model.Id)">

It also supports these attributes:

• sm-ajax: The form is an unobrusive AJAX form.

• sm-confirm: Custom confirm message.

• sm-onbegin

• sm-oncomplete

• sm-onfailure

• sm-onsuccess

• sm-allow-cache

• sm-loading-element-id

• sm-loading-element-duration

• sm-update-target-id

• sm-insertion-mode: Mode of insertion of the response. Possible values: Replace, InsertBefore, InsertAfter, ReplaceWith.

Further information can be found in this explanation.

ColorBox Tag Helper

The ColorBoxTagHelper adds a color-picker. It is used under the hood of the SettingEditorTagHelper to display colors.

<colorbox asp-for="MyColour" sm-default-color="#ff2030" />

Editor Tag Helper

The EditorTagHelper adds a customisable input field. It works similiar to the SettingEditorTagHelper.

<editor asp-for="PriceInclTax" sm-postfix="@primaryStoreCurrencyCode" />

To add more ViewData attributes, use asp-additional-viewdata.

FormControl Tag Helper

The FormControlTagHelper adds labels and CSS classes to form elements.

<input type="text" asp-for="Name" />
<input type="checkbox" asp-for="MyBool" sm-switch />

It also supports these attributes:

• sm-append-hint

• sm-ignore-label

• sm-switch: Process checkboxes as switches. Default: true

• sm-control-size: Size of the element. Default: Medium

• sm-plaintext: View as plaintext.

• sm-required

Hint Tag Helper

The HintTagHelper displays the localised Hint of resource passed in asp-for.

<div><span>John Smith</span><hint asp-for="Name" /></div>

InputPassword Tag Helper

The InputPasswordTagHelper adds the ability to toggle the visibility of a password input.

<input type="password" sm-enable-visibility-toggle="false"/>

• sm-enable-visibility-toggle: Displays an eye icon to toggle the visibility of the password. Default: true

NumberInput Tag Helper

The NumberInputTagHelper extends the number-input's customisability and styles the element.

<input type="number" sm-decimals="2" sm-numberinput-style="centered" asp-for="price"/>

TripleDatePicker Tag Helper

The TripleDatePickerTagHelper adds a customisable date-picker displaying the day, month and year.

<triple-date-picker day-name="@(controlId + "-day")" month-name="@(controlId + "-month")" year-name="@(controlId + "-year")" day="Model.SelectedDay" month="Model.SelectedMonth" year="Model.SelectedYear" begin-year="Model.BeginYear" end-year="Model.EndYear" disabled="Model.IsDisabled" />

The default value for control-size is Medium.

Media

All media Tag Helpers support the following attributes: sm-file, sm-file-id, sm-url-host.

All image-based Tag Helpers (ImageTagHelper, MediaTagHelper, ThumbnailTagHelper, VideoTagHelper) support the following attributes: sm-model, sm-size, sm-width, sm-height, sm-resize-mode, sm-anchor-position and sm-no-fallback.

Audio Tag Helper

The AudioTagHelper adds an audio element.

<audio sm-file="AudioFile" />

Image Tag Helper

The ImageTagHelper adds an image with attributes used in Model or the File.

<img sm-file="JPGFile"/>

Media Tag Helper

The MediaTagHelper adds a suitable tag for a given media type.

<media sm-file="Model.CurrentFile" sm-size="Model.ThumbSize" alt="@picAlt" title="@picTitle" />

Thumbnail Tag Helper

The ThumbnailTagHelper adds a thumbnail of a media file.

<media-thumbnail sm-file="MediaFile" sm-size="ThumbSize" />

Video Tag Helper

The VideoTagHelper adds a video element.

<video sm-file="VideoFile" controls preload="metadata" />

Admin

BackTo Tag Helper

The BackToTagHelper adds a left arrow icon to a link.

<a href="#" sm-backto>Go back</a>

DataGrid Tag Helper

There are different types of DataGrid Tag Helpers. They all work together to extend the functionality of the Grid Tag Helper.

Here is an excerpt from Smartstore.Web/Areas/Admin/Views/ActivityLog_Grid.ActivityLogs.cshtml to show this.

_Grid.ActivityLogs.cshtml

<datagrid allow-resize="true" allow-row-selection="true" allow-column-reordering="true">
    <datasource read="@Url.Action("ActivityLogList", "ActivityLog")"
                delete="@Url.Action("ActivityLogDelete", "ActivityLog")" />
    <sorting enabled="true">
        <sort by="CreatedOn" by-entity-member="CreatedOnUtc" descending="true" />
    </sorting>
    <paging position="Bottom" show-size-chooser="true" />
    <toolbar>
        <toolbar-group>
            <button datagrid-action="DataGridToolAction.ToggleSearchPanel" type="button" class="btn btn-light btn-icon">
                <i class="fa fa-fw fa-filter"></i>
            </button>
        </toolbar-group>
        <zone name="datagrid_toolbar_alpha"></zone>
        <toolbar-group class="omega"></toolbar-group>
        <zone name="datagrid_toolbar_omega"></zone>
        <toolbar-group>
            <button type="submit" name="delete-all" id="delete-all" value="clearall" class="btn btn-danger no-anims btn-flat">
                <i class="far fa-trash-alt"></i>
                <span>@T("Admin.Common.DeleteAll")</span>
            </button>
            <button datagrid-action="DataGridToolAction.DeleteSelectedRows" type="button" class="btn btn-danger no-anims btn-flat">
                <i class="far fa-trash-alt"></i>
                <span>@T("Admin.Common.Delete.Selected")</span>
            </button>
        </toolbar-group>
    </toolbar>
    <search-panel>
        <partial name="_Grid.ActivityLogs.Search" model="parentModel" />
    </search-panel>
    <columns>
        <column for="ActivityLogTypeName" entity-member="ActivityLogType.Name" hideable="false" />
        <column for="Comment" wrap="true" />
        <column for="CustomerEmail" entity-member="Customer.Email" type="string">
            <display-template>
                <a :href="item.row.CustomerEditUrl" class="text-truncate">
                    {{ item.value }}
                </a>
            </display-template>
        </column>
        <column for="IsSystemAccount" halign="center" sortable="false" />
        <column for="CreatedOn" entity-member="CreatedOnUtc" />
    </columns>
    <row-commands>
        <a datarow-action="DataRowAction.Delete">@T("Common.Delete")</a>
    </row-commands>
</datagrid>

SettingEditor Tag Helper

The SettingEditorTagHelper provides automatic HTML-Input type Mapping.

<setting-editor asp-for="Name"></setting-editor>

It automatically checks the type of the variable passed in asp-for and looks for an appropriate HTML input. Additionally it offers model binding and matching.

SmartLabel Tag Helper

The SmartLabelTagHelper displays a label and an optional hint.

<smart-label asp-for="Name" />

It also supports these attributes:

• sm-ignore-hint: Hint will be ignored. Default: true

• sm-text: Custom label text.

• sm-hint: Custom label hint.

Further Reading

If you are interested in writing your own TagHelper or learning more about them, follow this Microsoft Tag Helper tutorial.