# 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.
Preview of Employees Value List
### 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:**
1. In the [Solution Explorer](https://docs.servoy.com/reference/servoy-developer/solution-explorer), right-click the `ValueLists` node and select `Create Value List`
2. Enter the name for the Value List. This will open the new Value List in the [Value List Editor](https://docs.servoy.com/reference/servoy-developer/object-editors/valuelist-editor)
Create Employees Value List
3. Set up the [Value List Properties](https://docs.servoy.com/reference/servoycore/object-model/solution/valuelist#property-summary)
Properties for employees value list
4. Click the Save All  button (or `ctrl+shift+s`) to save all your editors
5. Assign the Value List to a component.
Preview of Employees Value List:
You can find an use-case example [here](https://docs.servoy.com/get-started/connect-to-a-data-dource#create-an-employees-value-list)
### **Using "valuelist" property of a component:**
Example: place a Type-Ahead component and bind to a new Value List
1. In the component Properties Editor, double-click the `valuelist` property to open the Value List Chooser
2. Click the button to Create New Value List
3. Enter the name of the valuelist
4. Click `Finish`. (Click `OK` to dismiss the Value List Chooser.) This will open the new Value List in the [Value List Editor](https://docs.servoy.com/reference/servoy-developer/object-editors/valuelist-editor)
5. Set up the [Value List Properties](https://docs.servoy.com/reference/servoycore/object-model/solution/valuelist#property-summary)
6. Click the Save All button (or `ctrl+shift+s`) to save all your editors
You can find an use-case example [here](https://docs.servoy.com/get-started/connect-to-a-data-dource#create-a-customers-value-list)
***
## Components List
The following components have a `valuelist` property:
* [Combobox](https://docs.servoy.com/guides/develop/ui-components/input-controls/combobox#combobox)
* FloatLabel Combobox
* [DataLabel](https://docs.servoy.com/guides/develop/ui-components/buttons-and-text/data-label#data-label)
* column of [DataGrid](https://docs.servoy.com/guides/develop/ui-components/grids/data-grid_new#data-grid)
* column of [Table](https://docs.servoy.com/guides/develop/ui-components/grids/table#table)
* [Choice Group](https://docs.servoy.com/guides/develop/ui-components/input-controls/choice-group#choice-group)
* [Type Ahead](https://docs.servoy.com/guides/develop/ui-components/input-controls/typeahead#type-ahead)
* FloatLabel Type Ahead
* [Group Buttons](https://docs.servoy.com/guides/develop/ui-components/input-controls/group-buttons#group-buttons)
* [Spinner](https://docs.servoy.com/guides/develop/ui-components/input-controls/spinner#spinner)
* [select2tokenizer](https://docs.servoy.com/guides/develop/ui-components/input-controls/select2tokenizer#select2tokenizer)
* [Native Data List](https://docs.servoy.com/guides/develop/ui-components/mobile/native-data-list#native-data-list)
* [Native Select](https://docs.servoy.com/guides/develop/ui-components/mobile/native-select#native-select)
***
{% hint style="info" %}
**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:
```javascript
// set only at element level
elements.myElement.putClientProperty(APP_NG_PROPERTY.VALUELIST_CONTAINS_SEARCH, true);
// set globally for alll valuelist search
application.putClientProperty(APP_NG_PROPERTY.VALUELIST_CONTAINS_SEARCH, true);
```
{% endhint %}
## 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](https://docs.servoy.com/reference/servoy-developer/solution-explorer/resources/i18n#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](https://docs.servoy.com/reference/servoy-developer/solution-explorer/resources/i18n#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.
{% hint style="warning" %}
**Advanced Feature**\
Global Method Values represent an advanced feature, consider the other types first.
{% endhint %}
#### Parameters
[String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/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](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/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.
{% hint style="warning" %}
If real value is not null, results will be appended to the valuelist.
{% endhint %}
[JSRecord](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsrecord) record - The record which is the context for the value list.
[String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/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](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/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**
```javascript
"function getDataSetForValueList(displayValue, realValue, record, valueListName, findMode, rawDisplayValue) {
var args = null;
var query = datasources.db.example_data.employees.createSelect();
/** @type {JSDataSet} */
var result = null;
//add the two columns for the dataset: displayValue and realValue
query.result.add(query.columns.firstname.concat(' ').concat(query.columns.lastname)).add(query.columns.employeeid);
if (displayValue == null && realValue == null) {
// TODO think about caching this result. can be called often!
// return the complete list
result = databaseManager.getDataSetByQuery(query, 100);
} else if (displayValue != null) {
// TYPE_AHEAD filter call, return a filtered list
args = [displayValue + "%", displayValue + "%"];
query.result.root.where.add(query.or.add(query.columns.firstname.lower.like(args[0] + '%')).add(query.columns.lastname.lower.like(args[1] + '%')));
result = databaseManager.getDataSetByQuery(query, 100);
} else if (realValue != null) {
// TODO think about caching this result. can be called often!
// real object not found in the current list, return 1 row with display,realvalue that will be added to the current list
// dont return a complete list in this mode because that will be added to the list that is already there
args = [realValue];
query.result.root.where.add(query.columns.employeeid.eq(args[0]));
result = databaseManager.getDataSetByQuery(query, 1);
}
return result;
}"
```
#### Execution Scenarios
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).
### 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.
{% hint style="info" %}
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.
{% endhint %}
### 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
{% hint style="info" %}
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.
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.servoy.com/guides/develop/application-design/data-modeling/value-lists.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
