Cascading selection lists is a common UI design pattern, where the list of values in one selection field depends on the current values in other fields. This helps narrow down the selection list and ensure that selected values in different fields are consistent. For example, the user can select a country, and then several regions within the country, and then several states within the selected regions.
Xomega Framework makes configuring cascading selection an extremely simple process. First off, you need to
set up the selection lists as cache lookup tables. When creating the corresponding lookup cache loaders for that, you need to make sure that you will set additional attributes for each item that correspond to the values of other fields that the current list depends on. In the example below the cache loader that populates the list of states, also stores the country code and the territory ID in the corresponding attribute for each state.
Code:
Header h;
if (!tbl.TryGetValue(id, out h)) tbl[id] = h = new Header(type, id, row.Name);
h.AddToAttribute(Enumerations.States.Attributes.CountryRegionCode, row.CountryRegionCode);
h.AddToAttribute(Enumerations.States.Attributes.TerritoryId, row.TerritoryId);
Note, that if you
generate your cache loaders from a
dynamic enumeration that is based on a service operation, then you need to make sure that the operation returns all the additional attributes, and the generated cache loaders will automatically store them for each item. If, however, your lookup table is based on a
static enumeration defined in the Xomega model, then you need to configure the values of all additional properties for each item in the enumeration.
Once you have set up the additional attributes for your lookup tables, all you have to do is to call the
SetCascadingProperty method on your enumeration property during object initialization, and pass it the attribute name and the other property, whose value the current selection list depends upon. If the other property allows multiple selection, then the current list will contain all values that match any of the selected values in the other property. Now whenever the value(s) of the other property changes, the selection list of the current field will be also automatically refreshed.
The following example shows how a list of territories is configured to depend on the selected country, and a list of states is configured to depend on both the selected country and/or selected territory.
Code:
protected override void OnInitialized()
{
base.OnInitialized();
// make the list of territories depend on the selected country code
TerritoryProperty.SetCascadingProperty(
Enumerations.Territory.Attributes.CountryRegionCode, CountryProperty);
// make the list of states depend on both the selected country code and territory
StateProvinceProperty.SetCascadingProperty(
Enumerations.States.Attributes.CountryRegionCode, CountryProperty);
StateProvinceProperty.SetCascadingProperty(
Enumerations.States.Attributes.TerritoryId, TerritoryProperty);
}