Value Lists
Last updated
Last updated
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.
The value that is shown to the user, but may not necessarily be stored in a data provider.
The value that is returned into a data provider to which the value list is bound.
Whether populating dropdown menus, validating input, or optimizing decision-making processes, value lists play a crucial role in simplifying data handling, improving user interface interactions.
There are two ways of creating a valuelist in Servoy Developer:
In the Solution Explorer, right-click the ValueLists node and select Create Value List
Enter the name for the Value List. This will open the new Value List in the Value List Editor
Set up the Value List Properties
Assign the Value List to a component.
Preview of Employees Value List:
You can find an use-case example here
In the component Properties Editor, double-click the valuelist property to open the Value List Chooser
Click the button to Create New Value List
Enter the name of the valuelist
Click Finish. (Click OK to dismiss the Value List Chooser.) This will open the new Value List in the Value List Editor
Set up the Value List Properties
You can find an use-case example here
The following components have a valuelist property:
Searching over a Value List
By default, a component that has a valuelist as a property and uses user input to search in that valuelist uses a like search with a % at the end (startsWith search on the fields of the valuelist). The client property can be set to always do a like search when filtering over valuelist on a typeahead like component. This can be set on the element (element.putClientProperty()) or on a application wide level (application.putClientProperty()), DEFAULT: false.
This makes it a like %value%, so a contains search:
When creating a Value List, a developer will specify one of four types of value lists, each having different properties and applications.
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.
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.
Example: Value lists can easily be made multi-lingual by using i18n keys instead 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.
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%%.
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.
Advanced Feature Global Method Values represent an advanced feature, consider the other types first.
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.
If real value is not null, results will be appended to the valuelist.
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.
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.
Sample
Global method valuelist has three scenarios that should be handled (based on the values of displayValue and realValue parameters). If both these parameters are null, you should return the complete, unaltered valuelist. This path can be executed quite often. If displayValue is not null, means you need to return the filtered valuelist, so filter it based on provided value. In these two situations you must provide the exact, complete valuelist that should be displayed. In the third scenario, if the realValue parameter is not null, means that a specific real value was not not found in the valuelist and you have to provide it manually. So, you want to return here a single row that will be appended to the valuelist (here you should not return a full valuelist).
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.
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 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.
There are several design-time settings available for every 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. Fallback value lists are useful in find mode.
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.
This is a simple setting to indicate if a value list will have an empty/ null value available for selection.
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.
A value list can be deprecated, and a description has to be provided to hint users about what the alternative is.
A value list has encapsulation property, similar to the form encapsulation property.
Public – accessible from everywhere
Module Scope – accessible from the module it was created in
For non-public encapsulation, if the value list is accessed from somewhere else, you get a build marker in Problems View, but it will still function properly.
Click the Save All button (or ctrl+shift+s) to save all your editors
Click the Save All button (or ctrl+shift+s) to save all your editors
