Tag Helpers

In order to use tag helpers provided by Bulletcode.NET library, add the following directive to the _ViewImports.cshtml file, as described in the MVC chapter:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

Field

The <field> tag makes it possible to create a form field, including the label, input control and validation message, using a short syntax:

<field asp-for="Name" />

The label is based on the Display attribute, and the type of the input control depends on the type of the property and its data annotation attributes:

<input type="text"> — used for text properties, unless a data annotation is specified
<input type="email"> — used when the EmailAddress attribute is specified
<input type="tel"> — used when the Phone attribute is specified
<input type="url"> — used when the Url attribute is specified
<input type="number"> — used for numeric properties, unless a data annotation is specified
<input type="file"> — used for IFormFile properties
<input type="checkbox"> — used for bool properties
<password-input> — used when the DataType(DataType.Password) attribute is specified
<currency-input> — used when the DataType(DataType.Currency) attribute is specified
<date-input asp-type="datetime"> — used for DateTime properties, unless a data annotation is specified
<date-input asp-type="date"> — used when the DataType(DataType.Date) attribute is specified
<date-input asp-type="time"> — used when the DataType(DataType.Time) attribute is specified

An input control can also be specified explicitly. In this case, it’s used instead of the automatically generated one, and the label and validation message are automatically created:

<field asp-for="Option">
    <select asp-for="Option" asp-items="Html.GetEnumSelectList<Option>()"></select>
</field>

The <field> tag supports the following optional attributes:

asp-format — the format string used to format the value of the <input> element
asp-fixed — when specified, the <input type="number"> element uses a fixed number of decimal digits; additional zeros are automatically added by client-side handler
asp-hidden — when true, the field is initially hidden; this is typically used with OnlyIf validation attribute, as explained in the Validation chapter
asp-autocomplete — specifies the autocomplete attribute of the <input> element
asp-readonly — specifies the readonly attribute of the <input> element

Any other attributes are automatically added to the <div> element which wraps the field.

Fieldset

The <fieldset> tag makes it possible to create a fieldset containing radio buttons or multiple checkboxes, including a legend and validation message, for example:

<fieldset asp-for="Option" asp-items="Html.GetEnumSelectList<Option>()">
</fieldset>

If the property is a singular type, radio buttons are created. If the property is a collection type, for example a list or an array, checkboxes are created.

The <fieldset> tag supports the following optional attributes:

asp-hidden — when true, the field is initially hidden; this is typically used with OnlyIf validation attribute, as explained in the Validation chapter
asp-dropdown — when true, a dropdown button which expands the options is generated
asp-empty — specifies the text which is displayed in the dropdown button when no options are selected

Input controls

Input controls can be used stand-alone or inside the <field> tag.

The <addon-input> tag generates an <input> element with a prefix and/or suffix, for example:

<addon-input asp-for="Distance" asp-suffix="km">

You can also use an icon as a prefix and/or suffix:

<addon-input asp-for="UserName" asp-prefix-icon="user">

The <addon-input> tag supports the following optional attributes:

asp-type — specifies the type of the <input> element; by default it is based on the type of the property and data annotations
asp-format — the format string used to format the value of the <input> element
asp-fixed — when specified, the <input type="number"> element uses a fixed number of decimal digits; additional zeros are automatically added by client-side handler

The <currency-input> tag is similar to <addon-input>, but the prefix/suffix is generated automatically based on the currency format for the current locale. The <currency-input> always uses a <input type="number"> element and a two fixed decimal digits.

<currency-input asp-for="Price">

The <date-input> tag creates an <input> element with a dropdown calendar and/or time picker:

<date-input asp-for="DateOfBirth">

The <date-input> tag supports the following optional attributes:

asp-type — specifies the type of the date picker: date, time or datetime; the default type depends on the type of the property and data annotations
asp-format — the format string used to format the value of the <input> element
asp-min — the minimum value which can be selected
asp-max — the maximum value which can be selected

The <password-input> tag creates an <input type="password"> element with a button which can be used to toggle password visibility:

<password-input asp-for="Password">

Anchor

The <a> tag has a special asp-post attribute, which converts the link to a button. This makes it possible to perform a POST request, instead of a GET request, in order to perform an action with a side effect without the risk of a CSRF attack (see Security for more details). For example:

<a asp-action="Delete" asp-route-id="@Model.Id" asp-post>@_( "Delete" )</a>

The Delete action can then be decorated with a [Post] attribute to prevent executing it as a GET request.

An optional asp-post-return-url attribute can also be specified in order to pass the URL of the current page in the request data. When the controller calls ReturnToAction(), as described in the Return URLs section, the redirect is performed to the original URL instead of the specified action. This can be used to ensure that the user stays on the same page after the action is performed.

Alert

The <alert> tag displays a simple alert message with an icon. The asp-type attribute specifies the type of the alert: error (the default one), warning, success or info. The optional asp-icon attribute can be used to override the default icon, which depends on the type of the alert.

For example:

<alert type="warning">
    <p>@_( "Are you sure you want to delete user {0}?", Model.Email )</p>
</alert>

Search panel

The <search-panel> tag creates a panel for filtering a grid (see View Components). It can contain any number of filter fields, and a search button and clear button are automatically generated.

The asp-data attribute can be used to specify the data provider used to populate the grid. This ensures that the first page of results is displayed after clicking the search button, while preserving the current page size and sort order.

For example:

<search-panel asp-data="Model.DataProvider">
    <field for="Name" />
    <field for="Email" />
</search-panel>

Other helpers

Bulletcode.NET modifies the behavior of the <input> element generated for a property of a decimal, float or double type. It ensures that a numeric input field is used if the type is not explicitly specified, and sets the correct value of the step attribute (0.01 when the DataType(DataType.Currency) attribute is specified, any otherwise). It also ensures that the value is correctly formatted.

An optional asp-fixed attribute can be specified to force the <input> element to use a fixed number of decimal digits; additional zeros are automatically added by client-side handler.

The <link> and <script> elements can contain an asp-entry attribute to resolve the URL of the script, style sheet or other type of assets from the asset bundle generated by Vite. See Loading assets for more details.