Page History
...
| Note |
|---|
If the child forms are not shown through a relation, the approach may still work in many cases, because unrelated forms of the same table will share a single foundset. This is discussed in more detail in the section covering foundsets. |
Value Lists
A Value List is a powerful data modeling feature which, at design-time models a particular list of values, which may be static, or dynamic, data-driven lists. Value lists may be bound to UI components, as well as interacted with programmatically. At run-time, a value list returns a list of dynamically generated values for the context of a form/foundset. When bound to a UI component, a value list is displayed as a list of choices, i.e. in a combobox or radio button group, etc. Value lists obviate the need to write code and SQL, thus greatly enhancing developer productivity.
Display Value
The value that is shown to the user, but may not necessarily be stored in a data provider.
Stored Value The value that is returned into a data provider to which the value list is bound.
Types of Value Lists
When creating a Value List, a developer will specify one of four types of value lists, each having different properties and applications.
...
Custom Values
...
This is the simplest type of value list. It represents a static list of available values, both displayed and stored. A developer hand-enters values directly into the value list editor. The displayed and stored values may be literal, or evaluated at runtime using i18n keys and global variables.
Example In its most basic form, the value list is simply a list of values from which to choose. The values which are displayed are also stored into a data provider.
Yes |
No |
Example When designing a value list, a developer may use a pipe character '|' to separate display values from stored values. In this example, the options Yes and No will be displayed to the user, but the values 1 and 0 will be respectively stored into a data provider.
Yes|1 |
No|0 |
Example Value lists can easily be made multi-lingual by using i18n keys in lieu of literal values. Here the same value lists is made multi-lingual and the Yes and No values will be displayed in the language of the user's locale.
i18n:yes|1 |
i18n:no|0 |
Example Value Lists can also evaluate Data Tags to store literal values that are already declared as global variables. This approach is recommended to store constant values, which are declared once in the entire application. Here a list of order statuses are used. The display values are made multi-lingual as above. And the stored values reference global variables defining constant values for each order status. The data tag takes the form %%globals.myVariableName%%.
i18n:orderStatusNew|%%globals.ORDER_STATUS_NEW%% |
i18n:orderStatusConfirmed|%%globals.ORDER_STATUS_CONFIRMED%% |
i18n:orderStatusShipped|%%globals.ORDER_STATUS_SHIPPED%% |
...
Global Method Values
...
A value list can be bound to a global method which supplies the values every time the value lists is used. This option gives the developer the most control, but also requires that the developer write code, and is therefore recommended to be used when the other value list types are not sufficient. The method is invoked often, each time the value list is referenced and each time the context changes.
Parameters
String displayValue - The value entered by the user into the field bound to the value list. This value will be null, unless the user is typing into the field, in which case the method may be called often as the user types. This parameter is useful when used in combination with Type Ahead fields, allowing the developer to filter the values as the user types.
Object realValue - The real value that is stored in a data provider that is bound to the field for which the value list is invoked. This value is passed in to allow developers to provide display values for a given real value which may not already be in the list.
JSRecord record - The record which is the context for the value list.
String valueListName - The name of the value list for which values will be supplied as multiple value lists could use the same method to obtain their values.
Returns
JSDataSet containing the values, both displayed and stored. The dataset should have two columns, display and stored respectively. If the dataset has only one column, then it will be used for both displaying and storing values.
...
Table Values
...
A value list can be derived from all of the values in a single table. This approach is ideal to use a real table from which to look up values. The following properties apply to Table-based value lists:
Table The database table from which the values are drawn.
Stored Value This specifies the name of the column that will provide the values at run-time.
Display Value This specifies the name of the column(s) that may provide value which will be displayed when the value list is bound to a UI element. A value list may specify up to three display columns.
Separator Character This specifies a String which will separate display values when multiple display columns are specified. i.e. ', ' could be used to separate the database columns last_name, first_name
Value List Name as Filter This setting specifies that a column, named valuelist_name, will be used to filter the records used in the valuelist . If specified, only those records, who's value for the valuelist_name column equals the name of the value list itself will be returned.
| Note |
|---|
It is not common to use the Value List Name as Filter setting, unless a reusable, generic table is used to hold many display/values for different value lists. |
...
Related Values
...
Related value lists are similar to table-based value lists The only difference is that the table which is used is filtered by the characteristics of a relation. Moreover, the relation itself will be contextual to the form/foundset for which the value list is invoked.
Example A value list project_people is based on the relation projects_to_people. Therefore the values will be derived from the right-hand people table. And the value list may be used in context of the left-hand projects table. The resulting list of people will be contextual to the selected project record of a form/foundset.
Relation-based value lists can traverse across as many relations as need be to arrive at the destination table.
Example In the above example, a simple one-to-many relation projects_to_people was used. Suppose however that there is a many-to-many relation between projects and people expressed by a link table project_people. The value list could traverse across two relations to return the correct values: projects_to_project_people.project_people_to_people. The far right-hand table, people, is still used to return values in context of a single project record.
Design-Time Properties of Value Lists
There are several design-time settings available for every value list
...
Fallback Value List
...
This property specifies another value list which may be used in the event that a record's value does not fall within the set of values provided by the value list.
Example Using the above example for the project_people value list, which shows a list of people related to a project; Imagine that a person was removed from a project, however, the value stored in a related records may still point to that person. In this case, the value would no longer show up in a bound component (i.e. combo box, radio buttons, etc.) as the person is no longer a valid selection. Nevertheless, the person is still referenced by the record. Therefore it may be advantageous to use a fallback value list, say one that displays all people in the people table, to ensure that the person is displayed. However, when the record is edited, only the values in the project_people value list will be displayed.
...
Allow Empty Value
...
This is a simple setting to indicate if a value list will have an empty/ null value available for selection.
...
Sorting Definition
...
The values contained in a table-based, or relation-based value list can be sorted on any columns in the table. Additionally, any related columns may be used as well.
Overview
Content Tools
Activity