External keys rendering with the ColumnConnection attribute
As explained in the "Columns" section, 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.
The list to be displayed in the select, or the way to provide "autocomplete" suggestions are specified by implementing repectively the
The IDispalyValueItemsProvider interface
- Task<IEnumerable> GetDisplayValuePairs(object x)
An async method that receives a
ClaimsPrincipal(User property available in each View) and returns all key/display names pairs that are compatible with the user permissions.
- ClientDisplayValueItemsSelector: string
- Used with client-providers that generate Html for client frameworks like Angular, Knockout, etc. The ViewModel property containing the array with all key/display names pairs. The exact syntax for specifying the property in the client viewmodel tree depends on the specific framework the provider is targetted to(Angulat, Knockout.js, etc.). If your application uses the defualt sever controls provider this property may simply return null;
The IDispalyValueSuggestionsProvider interface
- string GetDisplayValueSuggestionsUrl(IUrlHelper uri);
- A method that given a View IUrlHelper returns the Url where to get all suggestions. This url must contain a string token that will be replaced by the partial typed by the user. The string token cannot appear as substring of any other part of the Url, since the final Url is computed with a simple string replace.
- DisplayValueSuggestionsUrlToken: string
- The token that will be replaced by the partial string typed by the user.
An example implementation
The class below is an example of implenting both interfaces.
The [ColumnConnection] attribute
Once IDispalyValueSuggestionsProvider/IDispalyValueItemsProvider implementations have been defined, they may be referenced in the [ConnectionAttribute] that decorates the ViewModel property containing an external key nalue, as in the examples below:
"TypeName" is the name of the VieModel property containing the display value corresponding to the key,
"Display" the name of the property of the display property in each key/display property item, and
Value the name of the key property in each
key/display item. The first example refers to a select type rendering, so
ProductTypesItemsProvider is a
The second example refers to an autocomplete type rendering, and
ProductTypesSuggestionProvider is a
IDispalyValueSuggestionsProvider implementation. The last parameter specifies the maximum number of suggestions. This overload of the constructor accepts
also another optional argument, the dataset name, that is the name of the data structure where results received by the server
are cached. Autocomplites that specifies the same name share the same cache thus reducing the overall calls to the server. If no dataset name is provided a name that depends just
on the the name of the VieModel property containing the display value corresponding to the key is automatically created ("TypeName" in both our example). This dataset name works properly if the View doesn't contain other properties with the same name but a different semantic.
Both ConnectionAttribute constructors overloads have a last optional boolean parameter called
queryDisplay whose default value is false.
This parameter affects the way the column is rendered in filter forms, namely if set to "true" no select or autocomplete appears in filter forms, but column
filter is rendered as a simple text input based on the display names associated to the external keys.
Custom column templates
This subsection is just for the developers that need custom column edit templates for external key columns.
All information needed to render either an autocomplete or a select are contained in the
ColumnConnection property of the
Column object available in the template.
The example below shows how to use the
ColumnConnectionInfos object contained in the