Value Lists
Overview
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.
Get Started
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.
Create a Value List
There are two ways of creating a valuelist in Servoy Developer:
Using Solution Explorer:
In the Solution Explorer, right-click the
ValueListsnode and selectCreate Value ListEnter 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
Using "valuelist" property of a component:
In the component Properties Editor, double-click the
valuelistproperty to open the Value List ChooserClick the button to Create New Value List
Enter the name of the valuelist
Click
Finish. (ClickOKto dismiss the Value List Chooser.) This will open the new Value List in the Value List EditorSet up the Value List Properties
You can find an use-case example here
Components List
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:
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.
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%%.
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.
Advanced Feature Global Method Values represent an advanced feature, consider the other types first.
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.
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. 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.
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.
Deprecated
A value list can be deprecated, and a description has to be provided to hint users about what the alternative is.
Encapsulation
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.
Last updated
