Columns

Columns are basically specifications on how to render a data item property. Columns default templates are able to render properly any simple property, booleans, and enumerations both in display and edit mode. They use properly several data annotations such as the DisplayAttribute to get pretty names (possibly localized) for enums. However, each annotation may be overriden by a "parallel" column tag attribute.

Properties containing external keys are rendered in display mode with their "display values", and in edit mode with either a select containing both key values and display names or with an autocomplete tag that has the same function of selects, but allows an easy selection also with big sets of data. All additional information needed to render properly external keys are furnished through the external-key-static and the external-key-dynamic tag helpers that are nested within the column tag helper. Starting from version 2.1.0 the same information may be provided through the ColumnConnectionAttribute together with the implementation of the IDispalyValueItemsProvider or IDispalyValueSuggestionsProvider interfaces. This approach, results in simpler tag helpers markup and in more modular code, since the interface implementations may be reused in several places.

Each column has the following templates, whose defaults depend on the control to render:

Display template that specifies how a column is rendered in display mode.
Edit template that specifies how a column is rendered in edit mode.
Filter template that specifies how each single filter condition is rendered. At moment the default template used by all controls is this one.

Custom edit/display row templates may be provided either by overriding the default templates partial views as explained in the Templates section or by inserting an asp-template tag within the column tag helper. The model passed to a column template is the value of the data item property it refers to. The model passed to the templates of all "computed columns" (see below) that are not associated to any property is the whole data item. The option object passed to all column templates is a Column class containing all column settings.

column tag helper attributes and their equivalent annotations

asp-for: ModelExpression

Specifies the property the column is associated with. Its format is:

PropertyTheControlIsDefinedFor.Element().PropertyName. In case the control the column is in renders an IEnumerable. The .Element() extension method represents the generic item of the IEnumerable.
```
<column asp-for="Products.Element().TypeId">
```
PropertyTheControlIsDefinedFor.SubElement<T>().PropertyName. In all cases when the column is defined within a row-type tag helper specific for a subclass T of the compile time item type.
```
<column asp-for="Products.SubElement<ProductMaintenanceViewModel>()
                    .MaintenanceYearlyRate" />
```
PropertyTheControlIsDefinedFor.PropertyName. Otherwise.
```
<column asp-for="TypeId">
```

name: string

Name of the column. Used only for columns that are not associated to any property, and that, accordingly, have no asp-for attribute. Similar columns are called "computed columns". All computed columns must specify a custom template. The model passed to computed columns is the whole data item.

<column name="fullprice"
        title="Price" priority="300" readonly="true">
    <asp-template type="Display">
        @{{
                var Model = Html.Item<SimpleProductViewModel>();
                <span>@Model.Price</span>@getEnumDisplayName(Model.ChosenCurrency)
            }}
    </asp-template>
</column>

See it live

remove: bool

When set the property with the same name/property name is removed from a set of already computed columns (inherited from another row, or created automatically with all-properties="true" on its row).

hidden: bool

It declares that the column is "hidden". Hidden columns are rendered just in server controls in edit mode. In this case they are rendered in hidden inputs.

readonly: bool

It declares that the column is "readonly". Readonly columns are rendered in display mode also when row is in edit mode.

editonly: bool

It declares that the column is "editonly". Editonly columns are not rendered when row is in display mode.

title: string

display name of property, used for form labels and table columns headers. Associated data annotation:Name property of the DisplayAttribute.

priority: int

It determines order columns are rendered. Highest priority columns are rendered first. Associated data annotation:Order property of the DisplayAttribute.

placeholder : string

input placeholder to be displayed when in edit mode. Associated data annotation:Prompt property of the DisplayAttribute.

null-text : string

text to render in display mode when property is null. Associated data annotation: NullDisplayText property of the DisplayFormatAttribute. Default is empty string.

format : string

format string used to render the property in display mode when property is not null. Associated data annotation: DataFormatString property of the DisplayFormatAttribute. Default is default format for the current culture.

widths, detail-widths : decimal[]

Percentage widths (referred to the column container) of the column, in list mode, and in detail mode, in the various viewports supported by the css grid system. If no grid system is used to render columns (like in the case of table columns) only the first array value is used. Form more information on using widths with grid systems see here. Associated data annotation: WidthsAsString, and DetailWidthsAsString properties of ColumnLayoutAttribute. WidthsAsString, and DetailWidthsAsString are strings containing decimals separated by spaces.

colspan : int?

colspan used typically in table based rendering. However, also other row template types may use this info somehow.

container-class : string

Css class to apply to the container the column is rendered in. For instance, in case of a table based grid, this class is applied to the td enclosing the column value.

input-class, input-detail-class, chekbox-class, chekbox-detail-class : string

Css class to apply respecively to input tags and checkboxes/radiobuttons. The two variants with "-details-" are used by "detail" controls while the others are used by controls that lists several items.

Query specific column attributes

query-constraints: QueryOptions?: Bit flag that specifies all query operations allowed on the column. All constraints are in logical and with the analogous constraints in the QueryAttribute of the property associated to the column. As special cases: if this attribute is not specified queries are based only on the constraints contained in the QueryAttribute, while if the property contains no QueryAttribute, querying on the column is completely disabled.
filter-clauses: QueryOptions[]: When specified with a not empty length the filter-clauses array overrides completely the analogous constraints coming from the property FilterLayoutAttribute, if any. When a QueryOptions[] information is specified either through this attribute or through a FilterLayoutAttribute, any filter window will contain a number of filter clauses involving the column that is equal to the length of the QueryOption array, instead of simply 1.
Moreover, each QueryOptions i in the array provides additional constraints for the allowed filter operators in ith filter condition.

external-key-static and the external-key-dynamic tag helpers

Important: Starting from version 2.1.0 the same information may be provided through the ColumnConnectionAttribute together with the implementation of the IDispalyValueItemsProvider or IDispalyValueSuggestionsProvider interfaces. This approach, results in simpler tag helpers markup and in more modular code, since the interface implementations may be reused in several places.

The external-key-dynamic tag helper contains exacly the same attributes of the autocomplete tag, so please refer to autocomplete documentation for more infos on it. The external-key-static has the following attributes:

display-property: ModelExpression: The model property containing the display value associated with the key. It has the same format as the asp-for column tag attribute. Used just in display mode.
items-selector: Func<object,Task<IEnumerable>>: An async function that returns all data items needed to build the select list;
client-items-selector: string: The name of a JavaScript function that do the same job as of items-selector on the client side for columns that are parts of client controls (controls whose html is created on the client side).
items-value-property: string: The name of the property of the data items returned by items-selector/client-items-selector that contains the external key
items-display-property: string: The name of the property of the data items returned by items-selector/client-items-selector that contains the display value

Below the definition of a grid column containing an external key reference:

<column asp-for="Products.Data.Element().TypeId">
    <external-key-remote display-property="Products.Data.Element().TypeName"
                         items-value-property="Value"
                         items-display-property="Display"
                         items-url="@(Url.Action("GetTypes", "CGrids",
                                    new { search = "_zzz_" }))"
                         dataset-name="product-types"
                         url-token="_zzz_"
                         max-results="20" />
</column> />

See it live