JSValueList
Overview
JSValueList is a wrapper for defining and managing value lists in the Solution Model. It supports multiple types, including custom values, database values, and global methods. It provides flexibility in configuring the display and return values, sorting, and filtering options, allowing dynamic value lists tailored to specific application needs. ## Functionality
JSValueList offers constants like CUSTOM_VALUES and DATABASE_VALUES to define its type. Properties such as dataSource, relationName, and sortOptions allow integration with database tables and relations. Additional properties like addEmptyValue and lazyLoading enable control over list behavior, such as including an empty option or deferring list loading to improve performance. For global method-based value lists, a specified method can populate the list dynamically based on provided criteria.
Methods like setDisplayDataProviderIds and setReturnDataProviderIds configure the display and return data providers, while utility functions like getUUID provide metadata access. Examples demonstrate usage scenarios, such as creating value lists from custom strings or database queries, and dynamically updating their configuration.
For more details, please refer to the Value list section of these documentation.
Constants Summarized
Properties Summarized
Property that tells if an empty value must be shown next to the items in the value list.
Compact representation of the names of the server and table that are used for loading the data from the database.
The global method of the valuelist is called to fill in or adjust the values of the valuelist.
A property, specific for NG & Titanium clients with GlobalValuelist - it helps to query/call the global valuelist method only when it is needed.
A String representing the separator that should be used when multiple display dataproviders are set, when the value list has the type set to database values.
The name of the database server that is used for loading the values when the value list has the type set to database/table values.
The name of the database table that is used for loading the values when the value list has the type set to database/table values.
Flag that tells if the name of the valuelist should be applied as a filter on the 'valuelist_name' column when retrieving the data from the database.
Methods Summarized
Returns an array of the dataproviders that will be used to display the valuelist value.
Returns an array of the dataproviders that will be used to define the valuelist value that is saved.
void
Set the display dataproviders.
void
Set the return dataproviders.
Constants Detailed
CUSTOM_VALUES
Constant to set the valueListType of a JSValueList. Sets the value list to use a custom list of values. Also used in solutionModel.newValueList(...) to create new valuelists
Type Number
Sample
var vlist = solutionModel.newValueList('options', JSValueList.DATABASE_VALUES);
vlist.valueListType = JSValueList.CUSTOM_VALUES; // Change the type to custom values.
vlist.customValues = "one\ntwo\nthree\nfour";DATABASE_VALUES
Constant to set the valueListType of a JSValueList. Sets the value list to use values loaded from a database. Also used in solutionModel.newValueList(...) to create new valuelists
Type Number
Sample
var vlist = solutionModel.newValueList('options', JSValueList.CUSTOM_VALUES);
vlist.valueListType = JSValueList.DATABASE_VALUES; // Change the type to database values.
vlist.dataSource = 'db:/example_data/parent_table';
vlist.setDisplayDataProviderIds('parent_table_text');
vlist.setReturnDataProviderIds('parent_table_text', 'parent_table_id');
vlist.separator = ' ## ';
vlist.sortOptions = 'parent_table_text desc';EMPTY_VALUE_ALWAYS
Constant to set/get the addEmptyValue property of a JSValueList.
Type Number
Sample
var vlist = solutionModel.newValueList('options', JSValueList.CUSTOM_VALUES);
vlist.customValues = "one\ntwo\nthree\nfour";
vlist.addEmptyValue = JSValueList.EMPTY_VALUE_ALWAYS;
var cmb = form.newComboBox('my_table_text', 10, 10, 100, 20);
cmb.valuelist = vlist;EMPTY_VALUE_NEVER
Constant to set/get the addEmptyValue property of a JSValueList.
Type Number
Sample
var vlist = solutionModel.newValueList('options', JSValueList.CUSTOM_VALUES);
vlist.customValues = "one\ntwo\nthree\nfour";
vlist.addEmptyValue = JSValueList.EMPTY_VALUE_NEVER;
var cmb = form.newComboBox('my_table_text', 10, 10, 100, 20);
cmb.valuelist = vlist;Properties Detailed
addEmptyValue
Property that tells if an empty value must be shown next to the items in the value list.
Type Number The configuration for adding an empty value to the value list.
Sample
var vlist = solutionModel.newValueList('options', JSValueList.CUSTOM_VALUES);
vlist.customValues = "one\ntwo\nthree\nfour";
vlist.addEmptyValue = JSValueList.EMPTY_VALUE_NEVER;
var cmb = form.newComboBox('my_table_text', 10, 10, 100, 20);
cmb.valuelist = vlist;customValues
A string with the elements in the valuelist. The elements can be separated by line feeds: custom1 custom2
Elements can optionally have real values: custom1|1 custom2|2
The (custom) values can be given via a global scope method instead, if the valuelist type is of global method type...
Type String The custom values defined for the value list, separated by newlines or pipes.
Sample
var vl1 = solutionModel.newValueList("customtext",JSValueList.CUSTOM_VALUES);
vl1.customValues = "customvalue1\ncustomvalue2";
var vl2 = solutionModel.newValueList("customid",JSValueList.CUSTOM_VALUES);
vl2.customValues = "customvalue1|1\ncustomvalue2|2";
var form = solutionModel.newForm("customvaluelistform",controller.getDataSource(),null,true,300,300);
var combo1 = form.newComboBox("scopes.globals.text",10,10,120,20);
combo1.valuelist = vl1;
var combo2 = form.newComboBox("scopes.globals.id",10,60,120,20);
combo2.valuelist = vl2;dataSource
Compact representation of the names of the server and table that are used for loading the data from the database.
Type String The data source associated with the value list.
Sample
var vlist = solutionModel.newValueList('options', JSValueList.DATABASE_VALUES);
vlist.dataSource = 'db:/example_data/parent_table';
vlist.setDisplayDataProviderIds('parent_table_text');
vlist.setReturnDataProviderIds('parent_table_text');displayValueType
Gets the display value
Type Number The data type of the display value in the value list.
Sample
var myValueList = solutionModel.getValueList('myValueListHere')
//set the display value type
myValueList.displayValueType = JSVariable.TEXTfallbackValueList
Gets or sets the fallback valuelist.
Type JSValueList The fallback value list associated with this value list, or null if none is set.
Sample
var myValueList = solutionModel.getValueList('myValueListHere')
//get fallback value list
var fallbackValueList = myValueList.fallbackValueListglobalMethod
The global method of the valuelist is called to fill in or adjust the values of the valuelist. The method returns a dataset with one or two columns, first column is the display value, second column is real value(if present). The valuelist will be filled in with the dataset data. If second column is not present real value and display value will be the same. The method has to handle three different scenarios: 1. 'displayValue' parameter is not null, this parameter should be used to filter the list of values(in a typeahead fashion) 2. 'realValue' parameter is specified, that means value was not found in current list, so must be specified manually. In this case method should return only one row in the dataset, with the missing value, that will be added to the valuelist 3. 'realValue' and 'displayValue' are both null , in this case the complete list of values should be returned.
Scenario 1 and 3 will completely replace any older results in the valuelist while scenario 2 will append results.
In find mode the record will be the FindRecord which is just like a normal JSRecord (DataRecord) it has the same properties (column/dataproviders) but doesnt have its methods (like isEditing())
The last argument is rawDisplayValue which contains the same text as displayValue but without converting it to lowercase.
Type JSMethod The global method used to populate or adjust the value list.
Sample
var listProvider = solutionModel.newGlobalMethod('globals', 'function getDataSetForValueList(displayValue, realValue, record, valueListName, findMode, rawDisplayValue) {' +
' ' +
'var args = null;' +
'var query = datasources.db.example_data.employees.createSelect();' +
'/** @type {JSDataSet} */' +
'var result = null;' +
'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;' +
'}');
var vlist = solutionModel.newValueList('vlist', JSValueList.CUSTOM_VALUES);
vlist.globalMethod = listProvider;lazyLoading
A property, specific for NG & Titanium clients with GlobalValuelist - it helps to query/call the global valuelist method only when it is needed.
This flag has to be set both on the valuelist and in component specification (.spec file), on the valuelist property, in order for it to work correctly (so the developer decides if a valuelist provides this option, and the component decides if it uses this feature or not).
IMPORTANT: Usage of real & display values is not fully supported with lazy loading. Don't set lazy load if your method returns both real and display values. This limitation is in place because, very likely in that case, we do need directly the display value for the current component's data (real value) in order to display it in UI...
Type Boolean Whether lazy loading is enabled for the value list.
Sample
var vlist = solutionModel.newValueList('options', JSValueList.DATABASE_VALUES);
vlist.dataSource = 'db:/example_data/valuelists';
vlist.setDisplayDataProviderIds('valuelist_data');
vlist.setReturnDataProviderIds('valuelist_data');
vlist.lazyLoading = true;
vlist.name = 'two';name
The name of the value list.
It is relevant when the "useTableFilter" property is set.
Type String The name of the value list.
Sample
var vlist = solutionModel.newValueList('options', JSValueList.DATABASE_VALUES);
vlist.dataSource = 'db:/example_data/valuelists';
vlist.setDisplayDataProviderIds('valuelist_data');
vlist.setReturnDataProviderIds('valuelist_data');
vlist.useTableFilter = true;
vlist.name = 'two';realValueType
Gets the real value type
Type Number The data type of the real value in the value list.
Sample
var myValueList = solutionModel.getValueList('myValueListHere')
// set the real value type
myValueList.realValueType = JSVariable.NUMBERrelationName
The name of the relation that is used for loading data from the database.
Type String The name of the relation associated with the value list.
Sample
var rel = solutionModel.newRelation('parent_to_child', 'db:/example_data/parent_table', 'db:/example_data/child_table', JSRelation.INNER_JOIN);
rel.newRelationItem('parent_table_id', '=', 'child_table_parent_id');
var vlist = solutionModel.newValueList('options', JSValueList.DATABASE_VALUES);
vlist.dataSource = 'db:/example_data/parent_table';
vlist.relationName = 'parent_to_child';
vlist.setDisplayDataProviderIds('child_table_text');
vlist.setReturnDataProviderIds('child_table_text');separator
A String representing the separator that should be used when multiple display dataproviders are set, when the value list has the type set to database values.
Type String The separator used for values in the value list.
Sample
var vlist = solutionModel.newValueList('options', JSValueList.CUSTOM_VALUES);
vlist.valueListType = JSValueList.DATABASE_VALUES; // Change the type to database values.
vlist.dataSource = 'db:/example_data/parent_table';
vlist.setDisplayDataProviderIds('parent_table_text');
vlist.setReturnDataProviderIds('parent_table_text', 'parent_table_id');
vlist.separator = ' ## ';
vlist.sortOptions = 'parent_table_text desc';serverName
The name of the database server that is used for loading the values when the value list has the type set to database/table values.
Type String The name of the server associated with the value list.
Sample
var vlist = solutionModel.newValueList('options', JSValueList.CUSTOM_VALUES);
vlist.valueListType = JSValueList.DATABASE_VALUES; // Change the type to database values.
vlist.dataSource = 'db:/example_data/parent_table';
vlist.setDisplayDataProviderIds('parent_table_text');
vlist.setReturnDataProviderIds('parent_table_text', 'parent_table_id');
vlist.separator = ' ## ';
vlist.sortOptions = 'parent_table_text desc';sortOptions
Sort options that are applied when the valuelist loads its data from the database.
Type String The sort options applied to the value list.
Sample
var vlist = solutionModel.newValueList('options', JSValueList.CUSTOM_VALUES);
vlist.valueListType = JSValueList.DATABASE_VALUES; // Change the type to database values.
vlist.dataSource = 'db:/example_data/parent_table';
vlist.setDisplayDataProviderIds('parent_table_text');
vlist.setReturnDataProviderIds('parent_table_text', 'parent_table_id');
vlist.separator = ' ## ';
vlist.sortOptions = 'parent_table_text desc';tableName
The name of the database table that is used for loading the values when the value list has the type set to database/table values.
Type String The name of the table associated with the value list.
Sample
var vlist = solutionModel.newValueList('options', JSValueList.CUSTOM_VALUES);
vlist.valueListType = JSValueList.DATABASE_VALUES; // Change the type to database values.
vlist.dataSource = 'db:/example_data/parent_table';
vlist.setDisplayDataProviderIds('parent_table_text');
vlist.setReturnDataProviderIds('parent_table_text', 'parent_table_id');
vlist.separator = ' ## ';
vlist.sortOptions = 'parent_table_text desc';useTableFilter
Flag that tells if the name of the valuelist should be applied as a filter on the 'valuelist_name' column when retrieving the data from the database.
Type Boolean Whether table filtering is used for the value list.
Sample
var vlist = solutionModel.newValueList('options', JSValueList.DATABASE_VALUES);
vlist.dataSource = 'db:/example_data/valuelists';
vlist.setDisplayDataProviderIds('valuelist_data');
vlist.setReturnDataProviderIds('valuelist_data');
vlist.useTableFilter = true;
vlist.name = 'two';valueListType
The type of the valuelist. Can be one of:
custom values
global method
database values
table based
relation based
Type Number The type of the value list (e.g., custom or database values).
Sample
var vlist = solutionModel.newValueList('options', JSValueList.CUSTOM_VALUES);
vlist.valueListType = JSValueList.DATABASE_VALUES; // Change the type to database values.
vlist.dataSource = 'db:/example_data/parent_table';
vlist.setDisplayDataProviderIds('parent_table_text');
vlist.setReturnDataProviderIds('parent_table_text', 'parent_table_id');
vlist.separator = ' ## ';
vlist.sortOptions = 'parent_table_text desc';Methods Detailed
getDisplayDataProviderIds()
Returns an array of the dataproviders that will be used to display the valuelist value.
Returns: Array An array of Strings representing the names of the display dataproviders.
Sample
var vlist = solutionModel.newValueList('options', JSValueList.DATABASE_VALUES);
vlist.dataSource = 'db:/example_data/parent_table';
vlist.setDisplayDataProviderIds('parent_table_text', 'parent_table_id');
vlist.setReturnDataProviderIds('parent_table_text');
var dispDP = vlist.getDisplayDataProviderIds();
for (var i=0; i<dispDP.length; i++)
application.output(dispDP[i]);
var retDP = vlist.getReturnDataProviderIds();
for (var i=0; i<retDP.length; i++)
application.output(retDP[i]);getReturnDataProviderIds()
Returns an array of the dataproviders that will be used to define the valuelist value that is saved.
Returns: Array An array of Strings representing the names of the return dataprovider.
Sample
var vlist = solutionModel.newValueList('options', JSValueList.DATABASE_VALUES);
vlist.dataSource = 'db:/example_data/parent_table';
vlist.setDisplayDataProviderIds('parent_table_text', 'parent_table_id');
vlist.setReturnDataProviderIds('parent_table_text');
var dispDP = vlist.getDisplayDataProviderIds();
for (var i=0; i<dispDP.length; i++)
application.output(dispDP[i]);
var retDP = vlist.getReturnDataProviderIds();
for (var i=0; i<retDP.length; i++)
application.output(retDP[i]);getUUID()
Returns the UUID of the value list
Returns: UUID The UUID of the value list.
Sample
var vlist = solutionModel.newValueList('options', JSValueList.CUSTOM_VALUES);
application.output(vlist.getUUID().toString());setDisplayDataProviderIds()
Set the display dataproviders. There can be at most 3 of them, combined with the return dataproviders. The values taken from these dataproviders, in order, separated by the separator, will be displayed by the valuelist.
Returns: void
Sample
var vlist = solutionModel.newValueList('options', JSValueList.CUSTOM_VALUES);
vlist.valueListType = JSValueList.DATABASE_VALUES; // Change the type to database values.
vlist.dataSource = 'db:/example_data/parent_table';
vlist.setDisplayDataProviderIds('parent_table_text');
vlist.setReturnDataProviderIds('parent_table_text', 'parent_table_id');
vlist.separator = ' ## ';
vlist.sortOptions = 'parent_table_text desc';setDisplayDataProviderIds(dataprovider1)
Set the display dataproviders. There can be at most 3 of them, combined with the return dataproviders. The values taken from these dataproviders, in order, separated by the separator, will be displayed by the valuelist.
Parameters
String dataprovider1 The first display dataprovider.
Returns: void
Sample
var vlist = solutionModel.newValueList('options', JSValueList.CUSTOM_VALUES);
vlist.valueListType = JSValueList.DATABASE_VALUES; // Change the type to database values.
vlist.dataSource = 'db:/example_data/parent_table';
vlist.setDisplayDataProviderIds('parent_table_text');
vlist.setReturnDataProviderIds('parent_table_text', 'parent_table_id');
vlist.separator = ' ## ';
vlist.sortOptions = 'parent_table_text desc';setDisplayDataProviderIds(dataprovider1, dataprovider2)
Set the display dataproviders. There can be at most 3 of them, combined with the return dataproviders. The values taken from these dataproviders, in order, separated by the separator, will be displayed by the valuelist.
Parameters
String dataprovider1 The first display dataprovider.
String dataprovider2 The second display dataprovider.
Returns: void
Sample
var vlist = solutionModel.newValueList('options', JSValueList.CUSTOM_VALUES);
vlist.valueListType = JSValueList.DATABASE_VALUES; // Change the type to database values.
vlist.dataSource = 'db:/example_data/parent_table';
vlist.setDisplayDataProviderIds('parent_table_text');
vlist.setReturnDataProviderIds('parent_table_text', 'parent_table_id');
vlist.separator = ' ## ';
vlist.sortOptions = 'parent_table_text desc';setDisplayDataProviderIds(dataprovider1, dataprovider2, dataprovider3)
Set the display dataproviders. There can be at most 3 of them, combined with the return dataproviders. The values taken from these dataproviders, in order, separated by the separator, will be displayed by the valuelist.
Parameters
String dataprovider1 The first display dataprovider.
String dataprovider2 The second display dataprovider.
String dataprovider3 The third display dataprovider.
Returns: void
Sample
var vlist = solutionModel.newValueList('options', JSValueList.CUSTOM_VALUES);
vlist.valueListType = JSValueList.DATABASE_VALUES; // Change the type to database values.
vlist.dataSource = 'db:/example_data/parent_table';
vlist.setDisplayDataProviderIds('parent_table_text');
vlist.setReturnDataProviderIds('parent_table_text', 'parent_table_id');
vlist.separator = ' ## ';
vlist.sortOptions = 'parent_table_text desc';setReturnDataProviderIds()
Set the return dataproviders. There can be at most 3 of them, combined with the display dataproviders. The values taken from these dataproviders, in order, separated by the separator, will be returned by the valuelist.
Returns: void
Sample
var vlist = solutionModel.newValueList('options', JSValueList.CUSTOM_VALUES);
vlist.valueListType = JSValueList.DATABASE_VALUES; // Change the type to database values.
vlist.dataSource = 'db:/example_data/parent_table';
vlist.setDisplayDataProviderIds('parent_table_text');
vlist.setReturnDataProviderIds('parent_table_text', 'parent_table_id');
vlist.separator = ' ## ';
vlist.sortOptions = 'parent_table_text desc';setReturnDataProviderIds(dataprovider1)
Set the return dataproviders. There can be at most 3 of them, combined with the display dataproviders. The values taken from these dataproviders, in order, separated by the separator, will be returned by the valuelist.
Parameters
String dataprovider1 The first return dataprovider.
Returns: void
Sample
var vlist = solutionModel.newValueList('options', JSValueList.CUSTOM_VALUES);
vlist.valueListType = JSValueList.DATABASE_VALUES; // Change the type to database values.
vlist.dataSource = 'db:/example_data/parent_table';
vlist.setDisplayDataProviderIds('parent_table_text');
vlist.setReturnDataProviderIds('parent_table_text', 'parent_table_id');
vlist.separator = ' ## ';
vlist.sortOptions = 'parent_table_text desc';setReturnDataProviderIds(dataprovider1, dataprovider2)
Set the return dataproviders. There can be at most 3 of them, combined with the display dataproviders. The values taken from these dataproviders, in order, separated by the separator, will be returned by the valuelist.
Parameters
String dataprovider1 The first return dataprovider.
String dataprovider2 The second return dataprovider.
Returns: void
Sample
var vlist = solutionModel.newValueList('options', JSValueList.CUSTOM_VALUES);
vlist.valueListType = JSValueList.DATABASE_VALUES; // Change the type to database values.
vlist.dataSource = 'db:/example_data/parent_table';
vlist.setDisplayDataProviderIds('parent_table_text');
vlist.setReturnDataProviderIds('parent_table_text', 'parent_table_id');
vlist.separator = ' ## ';
vlist.sortOptions = 'parent_table_text desc';setReturnDataProviderIds(dataprovider1, dataprovider2, dataprovider3)
Set the return dataproviders. There can be at most 3 of them, combined with the display dataproviders. The values taken from these dataproviders, in order, separated by the separator, will be returned by the valuelist.
Parameters
String dataprovider1 The first return dataprovider.
String dataprovider2 The second return dataprovider.
String dataprovider3 The third return dataprovider.
Returns: void
Sample
var vlist = solutionModel.newValueList('options', JSValueList.CUSTOM_VALUES);
vlist.valueListType = JSValueList.DATABASE_VALUES; // Change the type to database values.
vlist.dataSource = 'db:/example_data/parent_table';
vlist.setDisplayDataProviderIds('parent_table_text');
vlist.setReturnDataProviderIds('parent_table_text', 'parent_table_id');
vlist.separator = ' ## ';
vlist.sortOptions = 'parent_table_text desc';Last updated
Was this helpful?