Lists and dictionaries

ListsCopy Anchor Link

A list of strings or numbers, like List<string> or int[], gets a list editor: one row per item, with Add as the last row. You only configure it to change its settings.

fields.Add(trip => trip.Highlights).UseListEditor(list =>
{
    list.MaxItems = 8;
    list.Sortable = true;
    list.Numbered = true;
    list.MaxLength = 120;
    list.AddText = "Add highlight";
});

fields.Add(trip => trip.DepartureAirports).UseListEditor(list =>
{
    list.Unique = true;
    list.Casing = ListEditorCasing.Upper;
    list.Pattern = "^[A-Z]{3}$";
    list.PatternMessage = "Use a three-letter airport code, like LIS.";
});

ListEditorCasing and ListEditorAlign are in StellarAdmin.UI.

The browser checks each row as people type, and the server checks again on save. Blank rows are dropped, and removing every row saves an empty list.

EF Core maps lists of strings and numbers as primitive collections, so they need no extra setup.

Lists hold text and numbers only. For a list of enum values, use a checkbox or toggle group. For related records, use a multi-lookup.

DictionariesCopy Anchor Link

A dictionary with a string or enum key, and a string, number or enum value, gets a dictionary editor: one row per entry, with a key and a value.

fields.Add(trip => trip.BaggageAllowance).UseDictionaryEditor(dictionary =>
{
    dictionary.Key(key => key.Label = "Cabin");
    dictionary.Value(value =>
    {
        value.Label = "Allowance";
        value.Max = 50;
        value.Suffix = "kg";
    });
});

The key and the value each take a Label, Placeholder, Pattern, PatternMessage, MaxLength and Casing. The value also takes Min, Max, Step, Prefix, Suffix and Align. The dictionary itself has MinItems, MaxItems, Numbered, AddText and EmptyText.

An enum key or value is a select of its members. To pick from another list, give the key or value items, just like a select:

fields.Add(trip => trip.GuidesByLanguage).UseDictionaryEditor(dictionary =>
{
    dictionary.Key(key => key.UseItems([
        new ChoiceItem("en", "English"),
        new ChoiceItem("pt", "Portuguese"),
        new ChoiceItem("ja", "Japanese"),
    ]));
    dictionary.Value(value => value.UseResource<Guide>());
});

Keys are unique, so with a select for the key there's at most one entry per option.

EF Core doesn't map dictionaries on its own. Store one in a JSON column, or give it a value converter.

Errors on one rowCopy Anchor Link

A handler or data source can put an error under a specific row. Name the row by its index, and the key or value for a dictionary:

return ResourceOperationResult.ValidationFailed([
    new ResourceValidationError("Highlights[2]", "We already have a highlight like this."),
    new ResourceValidationError("BaggageAllowance[1].Key", "That cabin doesn't exist."),
]);

Default textsCopy Anchor Link

The default texts, like "Add item" and "No items yet", are global labels, set with labels.ListEditor(...) and labels.DictionaryEditor(...).

In an inline row, a list or dictionary shows its badges instead of an editor, and saving the row keeps its value.