Dictionary Editor

<sa-dictionary-editor asp-for="LocalNames" key-label="Language" key-pattern="[a-z]{2}"
                      key-pattern-message="Use a two-letter language code, like pt."
                      key-casing="DictionaryEditorCasing.Lower" key-placeholder="pt"
                      value-label="Local name" value-max-length="120" add-text="Add translation"
                      empty-text="No translations yet. Pages use the English name." />

UsageCopy Anchor Link

<sa-dictionary-editor> edits a Dictionary<TKey, TValue> or IDictionary<TKey, TValue> whose key is a string or an enum and whose value is a string, a number or an enum. Bind it with asp-for. Each entry is a row with the key and the value side by side under their column labels, and Add is the last row.

<sa-dictionary-editor asp-for="..." key-label="..." value-label="..." />

Each row posts indexed names, such as LocalNames[0].Key and LocalNames[0].Value, which MVC binds to the dictionary. A hidden marker posts with the rows, so removing every entry binds an empty dictionary instead of keeping the old one. Rows left blank don't post. How the dictionary is stored is up to the app; with EF Core, it needs a value converter or a JSON column.

The rows are rendered on the server, so the values show before the script runs. Adding and removing rows needs stellar-admin.js.

Enter in a key moves to its value, and Enter in the last value adds a row. Escape in a blank row removes it. Pasting lines such as pt=Passeio por Lisboa, pt: Passeio por Lisboa or tab-separated pairs adds an entry for each line.

ExamplesCopy Anchor Link

Enum keysCopy Anchor Link

An enum key or value is a select of the enum's members, with the names from their [Display] attributes. A key can be used once, so the keys other rows use are disabled, and the dictionary can have one entry for each member. key-placeholder and value-placeholder set the text of a select's empty choice.

<sa-dictionary-editor asp-for="SeasonalPrices" key-label="Season" key-placeholder="Choose a season"
                      value-label="Price per traveller" value-min="0" value-step="0.01"
                      value-prefix="€" add-text="Add season" />

ItemsCopy Anchor Link

asp-key-items and asp-value-items take the keys or values to choose from, as SelectListItems, like asp-items on a select. With key items, the dictionary can have one entry for each item.

<sa-dictionary-editor asp-for="GuidesByLanguage" asp-key-items="Index.Languages"
                      asp-value-items="Index.Guides" key-label="Language" key-placeholder="Choose a language"
                      value-label="Guide" value-placeholder="Choose a guide" add-text="Add language" />

NumbersCopy Anchor Link

A number value renders a number input, aligned to the end so that the digits line up; value-align sets the values' alignment. The keys are always aligned to the start. value-min, value-max and value-step set its range and step, and value-prefix and value-suffix show text beside it, such as a currency symbol or a unit.

<sa-dictionary-editor asp-for="BaggageAllowance" key-label="Cabin" key-placeholder="Economy"
                      value-label="Allowance" value-min="0" value-max="50" value-suffix="kg"
                      add-text="Add cabin" />

Key and value checksCopy Anchor Link

The key and value take the same checks as a list editor's items, with a key- or value- prefix: key-pattern, key-pattern-message, key-max-length and key-casing, and the same for the value. A key can't repeat another row's, and a row with a key needs a value, and the other way round.

The editor checks a row when focus leaves it, and every row when the form is submitted. A row's error shows under the row, and the submit is blocked until the errors are fixed. The browser checks can be bypassed, so check the entries again on the server.

ValidationCopy Anchor Link

An error in ModelState for a key or value, such as BaggageAllowance[1].Value, shows under that row, and an error for the property shows under the field. The demo adds one to ModelState.

<sa-dictionary-editor asp-for="BaggageAllowance" key-label="Cabin" value-label="Allowance"
                      value-suffix="kg" />

Read onlyCopy Anchor Link

Set readonly to show the entries as text, without adding or removing. A select's value shows its item's text. A read-only dictionary posts no values.

<sa-dictionary-editor asp-for="SeasonalPrices" key-label="Season" value-label="Price per traveller"
                      value-prefix="€" readonly="true" />

AccessibilityCopy Anchor Link

The box is a group labelled by the field's label. Each input is named by its column and number, such as "Language 2", and the remove button as "Remove row 2". A row's error is linked to its input with aria-describedby.

Part classesCopy Anchor Link

Pass a DictionaryEditorClassNames instance from the StellarAdmin.UI namespace using class-names. Each property accepts an optional string of space-separated CSS classes, which are added to the part's existing classes.

Root, Label, Description, Error, and Content are inherited from FieldClassNames; see Field part classes.

API ReferenceCopy Anchor Link

<sa-dictionary-editor>Copy Anchor Link

Renders a web component with the column labels, a row per entry, the Add row, and a hidden marker that posts with the rows. It also takes class-names, column-span, column-start, description, error, label, name and wrap-in-field, as the list editor does.

The editor throws when it has no asp-for, or is bound to something other than a supported dictionary.