Cascading List Lookup
Description
Display choices for a lookup as one or more cascading lists.
Discussion
The Cascading List lookup displays a list of choices organized as a list with sub-lists. If the choice has a sub-list (e.g. list of Cities for a Country), the sub-list is shown when the user hovers over the item. If items in the sub-list have their own sub-lists, the sub-lists are shown when the user hovers over any item that has a sub-list. This behavior continues indefinitely until a leaf node is displayed (a leaf node is an item that has no sub-list). When a user clicks on a leaf, the lookup field is filled in with the value.
For example, the images below show a lookup for the CustomerId field. The lookup cascade has been defined as Country, City, Contactname, CustomerId. When the lookup is first opened, a list of Countries is shown. If the list contains any Cities for a given Country, the list has an icon showing that a sub-list is available. When the user hovers over or clicks on an item that has a sub-list, the sub-list is shown (as shown in the second image). Finally, when an item has no sub-lists (i.e. a leaf) and the user clicks the item, the item's value is inserted into the Lookup field.
To define a Cascading List lookup for a textbox or textarea, check the Lookup property and then select CascadingList form the list of available lookup types.
To define the Cascading List lookup, click the smart field for the Lookup definition property. This will open the builder as shown in the image below.
Lists can either be dynamic (based on a SQL query, or an Xbasic function), or static (based on a list of choices that you define at design time).
If you are basing the lookup on a SQL data source, you must select the fields to display. The order in which you select the fields is significant. It defines the hierarchy of the cascade. For example, in the image above, the fields are Country, City, ContactName.
This means that when the list is initially displayed, you will see a list of Countries. For each Country you will see a list of Cities, For each City you will see a list of ContactNames. ContactName is the leaf.
Configuring Static Choices
You can also define a static list of choices for the Lookup. Static choices are defined using a CR-LF delimited format with tabs to indicate whether or not a choice is a sub-list of the item above:
alpha alpha1 alpha1-1 alpha1-2 alpha2 alpha2-1 alpha2-2 alpha2-2-1 alpha2-2-2 beta beta1 beta2 gamma
HTML can be used to customize the appearance of a menu item. For example, the first item in the list below, Alpha, is styled as bold, green text:
<span style="color:green;font-weight:bold;">Alpha</span> Beta Gamma Delta
Images can also be included using JSON. The example below includes several items with icons:
<span style="color:green;font-weight:bold;">Alpha</span>{value: 'Alpha', icon: 'svgIcon=#alpha-icon-basketRemoveSolid:iconSizeable,15{ fill: #2e72ff; stroke: #53f159;}'}
SubAlpha1
SubAlpha2
Beta{icon:'images/$$application.alpha.png.a5image'}
SubBeta1
SubSubBeta1{icon: 'svgIcon=#alpha-icon-basketRemoveSolid:iconSizeable,15{ fill: #2e72ff; stroke: #53f159;}'}Notice that each item in the list can be followed by an optional JSON definition that contains a value and icon property. The value property defines the value that will be inserted into the lookup field if the item is a leaf and it is selected. If the list includes HTML markup to style the menu options, it's recommended to define the value (e.g. {value:"Alpha"}) for that entry. Otherwise, the value inserted into the text box will include the HTML markup.
See A5.u.icon html() Method for examples on the format for images, CSS Icons, and SVG Icons when setting the icon property.
Videos
Cascading List Lookups
A cascading list shows a list of values where each item in the list may have a sub-list of choices, and so on, until you get to an entry that has no sub-list (called a leaf). Once the user clicks on a leaf entry, that entry is filled into to lookup field.
In this video, we show how you can set up a cascading list lookup that displays data from a SQL table. The lookup displays a list of countries. For each country a sub-list of cities is shown. For each city, a sub-list of company names is shown and then a sub-list of customer Ids is shown. Since customerId is the leaf, when the user clicks on the Customer Id, that value is inserted into the Lookup field.