Skip to main content

%ZEN.Component.dataCombo

deprecated class %ZEN.Component.dataCombo extends %ZEN.Component.abstractComboBox, %ZEN.Component.querySource

A dataCombo is a specialized type of abstractComboBox that presents the user with a set of options that are provided by querying the database.

Contents of the dataCombo Dropdown
The contents of the dataCombo dropdown are provided by creating, executing, and fetching from a %ResultSet object on the server.
Initially the contents of the dropdown are empty until the user causes the dropdown to appear at which point a call to the server is made to fetch the dropdown contents. You can change this behavior by setting the cached property.
You can specify how this %ResultSet object is created using the properties inherited from the querySource class.
The number of columns returned by the %ResultSet determines what is displayed within the dropdown list in the following way:
Logical and Display Values
A combobox has two current values: a logical value (its internal value returned by the getValue() method), and a display value (the value displayed to the user). (In some cases, the logical and display values may be the same).
Unlike a traditional HTML select control, the ZEN dataCombo does not contain every possible logical/display value within its dropdown list. Instead it constructs the contents of its dropdown list on demand. This behavior makes it much better suited for database applications (where the set of possible values can be long and unwieldy).
When an application sets the value of a dataCombo control, it sets the logical value of the control. Internally, the dataCombo tries to find the display value that best matches this logical value. On the server, this works by executing the SQL statement defined by the sqlLookup property of the dataCombo.
On the client, the dataCombo first looks for a match for a given logical value within its dropdown cache. If it does not find a match, then it executes a server method to execute the sqlLookup query.
For example: suppose we want to define a dataCombo to show a set of Customer names; the display value will be Name while the logical value is the ID of the Customer. To do this we define a dataCombo using 2 SQL statements: 
 <dataCombo id="MyCombo"
 		sql="SELECT ID,Name FROM MyApp.Customer WHERE Name %STARTSWITH ? ORDER BY Name"
 		sqlLookup="SELECT Name FROM MyApp.Customer WHERE ID = ?"
 		editable="true"
 		searchKeyLen="10"
 	/>
This does the following:
  1. The query defined by sql is called when the dropDown list is displayed. It provides a set of logical (ID) and display (Name) values. The ? parameter is supplied by the contents of the combobox text area at the time the dropdown appears (up to the first 10 characters are used, as specified by searchKeyLen). The dataCombo remembers the results of the last query it ran in a local cache.
  2. The query defined by sqlLookup is used to find a specific display value for a specific logical value. The ? in this case is a logical value. This query should only return one row.
If, at run-time, the application tries to set the logical value of this combobox, then (if the answer is not in the cache) the sqlLookup query will be executed.

Query Parameters
The query used to provide the contents of the dropdown list may contain one or more run-time ? parameters (e.g., WHERE Name %STARTSWITH ?). If this is the case, the values for query parameters are provided as follows:
  1. The dataCombo can define a parameters list. The values of these parameters are used as query parameters when executing the query to fill the dropdown list. The parameter values will replace ? parameters in the order in which they appear in the SQL query.
    It is possible to modify the values of these parameters within client code, if desired. The application should call the dataCombo's clearCache() in this case to make sure that the dropdown query is re-executed with the new values.
  2. If the searchKeyLen property is set to a non-zero value, and the dataCombo is editable, then the current contents (the first searchKeyLen characters) of the combo input box are used as the value for the first query parameter. (first ? appearing within the query). In this case, additional members of the parameters list are treated as if they start from the second position within the list (the first being the search key). Any additional ? parameters within the SQL are provided from the parameters list, with one exception: if any parameter value is equal to "?", then the current search key value (i.e., the value used for the first parameter) will also be used for this query parameter.

Property Inventory

Method Inventory

Parameters

parameter DOMAIN = %ZEN;
parameter USECACHEDIV = 1;
Indicates that this combobox should cache its dropdown contents.

Properties

property auxColumn as %ZEN.Datatype.string [ InitialExpression = "1" ];
Optional. If there are multiple data columns displayed in the dropdown list this is the comma-delimited (1-based) list of the column numbers that will provide additional auxiliary values for this control.
This provides a way to supply an additional value that is not the display or logical value.
If this value is not a valid column number, then no auxiliary data will be provided.
Property methods: auxColumnDisplayToLogical(), auxColumnGet(), auxColumnIsValid(), auxColumnLogicalToDisplay(), auxColumnLogicalToOdbc(), auxColumnNormalize(), auxColumnSet()
property cached as %ZEN.Datatype.boolean [ InitialExpression = 0 ];
If true (the default is false) then the following behavior occurs:
  1. When the page is first displayed, a query is executed to fetch the initial contents of the dropdown. The itemCount property will be set to the number of items within the dropdown.
  2. The client will use these results instead of going back to the server to fetch the contents of the dropdown.
The clearCache()
Property methods: cachedDisplayToLogical(), cachedGet(), cachedIsValid(), cachedLogicalToDisplay(), cachedLogicalToOdbc(), cachedLogicalToXSD(), cachedNormalize(), cachedSet(), cachedXSDToLogical()
property choiceColumn as %ZEN.Datatype.integer (MINVAL = 1, ZENSETTING = 0) [ InitialExpression = 2 ];
If there are multiple data columns displayed within the dropdown list this is the column number (1-based) of the column that will provide the display value for this control.
If this value is greater than the number of columns in the query then the second column will be used.
Property methods: choiceColumnDisplayToLogical(), choiceColumnGet(), choiceColumnIsValid(), choiceColumnLogicalToDisplay(), choiceColumnLogicalToOdbc(), choiceColumnNormalize(), choiceColumnSet()
property clearOnLoad as %ZEN.Datatype.boolean [ InitialExpression = 0 ];
If this is set true and this dataCombo is bound to a data controller, then the contents of this combo box will be cleared whenever a new instance is loaded into the controller.
Property methods: clearOnLoadDisplayToLogical(), clearOnLoadGet(), clearOnLoadIsValid(), clearOnLoadLogicalToDisplay(), clearOnLoadLogicalToOdbc(), clearOnLoadLogicalToXSD(), clearOnLoadNormalize(), clearOnLoadSet(), clearOnLoadXSDToLogical()
property columnHeaders as %ZEN.Datatype.csv (ZENLOCALIZE = 1);
If defined, this is a comma-delimited list of column headers displayed in the dropdown list.
Property methods: columnHeadersDisplayToLogical(), columnHeadersGet(), columnHeadersIsValid(), columnHeadersLogicalToDisplay(), columnHeadersLogicalToOdbc(), columnHeadersNormalize(), columnHeadersSet()
property conditions as list of %ZEN.Auxiliary.condition (XMLPROJECTION = "ELEMENT", XMLREF = 1, XMLTYPECONSTRAINT = "CHOICE");
A list of conditions. These are special expression objects that are evaluated to add data-dependent styles to the dataCombo.
Property methods: conditionsBuildValueArray(), conditionsCollectionToDisplay(), conditionsCollectionToOdbc(), conditionsDisplayToCollection(), conditionsGet(), conditionsGetObject(), conditionsGetObjectId(), conditionsGetSwizzled(), conditionsIsValid(), conditionsOdbcToCollection(), conditionsSet(), conditionsSetObject(), conditionsSetObjectId()
property contentType as %ZEN.Datatype.string (VALUELIST = ",text,html") [ InitialExpression = "text" ];
Indicates how display values should be rendered:
If contentType is "text" (the default) then the display values will be HTML-escaped before being rendered.
If contentType is "html" then the display values will not be HTML-escaped before being rendered. Use this when your display values contain HTML markup that you do not want escaped.
Property methods: contentTypeDisplayToLogical(), contentTypeGet(), contentTypeIsValid(), contentTypeLogicalToDisplay(), contentTypeLogicalToOdbc(), contentTypeNormalize(), contentTypeSet()
property displayColumns as %ZEN.Datatype.csv (ZENSETTING = 0);
If there are multiple data columns displayed in the dropdown list, this optional property defines a comma-delimited list of the column numbers of the column that should be displayed.
Property methods: displayColumnsDisplayToLogical(), displayColumnsGet(), displayColumnsIsValid(), displayColumnsLogicalToDisplay(), displayColumnsLogicalToOdbc(), displayColumnsNormalize(), displayColumnsSet()
property emptyText as %ZEN.Datatype.caption;
The text to be displayed in the "empty" item displayed if showEmpty is true. The default is "".
Property methods: emptyTextDisplayToLogical(), emptyTextGet(), emptyTextIsValid(), emptyTextLogicalToDisplay(), emptyTextLogicalToOdbc(), emptyTextNormalize(), emptyTextSet()
property itemCount as %ZEN.Datatype.integer (XMLPROJECTION = "none", ZENSETTING = 0) [ InitialExpression = 0 ];
Number of items in the drop down.
Note that this value is set as a side effect of populating the dropdown list. When a dataCombo is first displayed, it typically has no entries in its dropdown list until the user causes the dropdown to appear. After this, itemCount will be set to the current number of items in the dropdown.
If you set the cached to true, then the dropdown list will be populated when the control is initially displayed and itemCount will be set. Note that in this case, the value is set after the page's %OnAfterCreatePage callback method is invoked.
Property methods: itemCountDisplayToLogical(), itemCountGet(), itemCountIsValid(), itemCountLogicalToDisplay(), itemCountLogicalToOdbc(), itemCountNormalize(), itemCountSet()
property loadingMessage as %ZEN.Datatype.caption;
Localized "loading" message displayed by control.
This message is temporarily displayed while a server-side query is running.
Property methods: loadingMessageDisplayToLogical(), loadingMessageGet(), loadingMessageIsValid(), loadingMessageLogicalToDisplay(), loadingMessageLogicalToOdbc(), loadingMessageNormalize(), loadingMessageSet()
property multiColumn as %ZEN.Datatype.boolean [ InitialExpression = 1 ];
If true (the default), then display multiple columns in the drop down box if the result set contains more than 2 columns.
Property methods: multiColumnDisplayToLogical(), multiColumnGet(), multiColumnIsValid(), multiColumnLogicalToDisplay(), multiColumnLogicalToOdbc(), multiColumnLogicalToXSD(), multiColumnNormalize(), multiColumnSet(), multiColumnXSDToLogical()
property onshowDropdown as %ZEN.Datatype.eventHandler;
onshowDropdown event handler: This event is fired just before the dropdown is displayed. If the event handler returns a value, then this value is used as the filter value for the dropdown query instead of the value typed into the input box.
Property methods: onshowDropdownDisplayToLogical(), onshowDropdownGet(), onshowDropdownIsValid(), onshowDropdownLogicalToDisplay(), onshowDropdownLogicalToOdbc(), onshowDropdownNormalize(), onshowDropdownSet()
property parameters as list of %ZEN.Auxiliary.parameter (XMLNAME = "parameter", XMLPROJECTION = "ELEMENT");
User-defined list of query parameters.
These values are passed on to the user callback function that provides the query for this component in order to provide values for any run-time query parameters.
Property methods: parametersBuildValueArray(), parametersCollectionToDisplay(), parametersCollectionToOdbc(), parametersDisplayToCollection(), parametersGet(), parametersGetObject(), parametersGetObjectId(), parametersGetSwizzled(), parametersIsValid(), parametersOdbcToCollection(), parametersSet(), parametersSetObject(), parametersSetObjectId()
property searchKeyLen as %ZEN.Datatype.integer (MINVAL = 0) [ InitialExpression = 0 ];
If non-zero, this is the maximum number of search characters taken from the combo input box and passed as a parameter to the query (defined by sql that provides the contents of the dropdown box.
If zero, then the contents of the input box are not used as a parameter.
Property methods: searchKeyLenDisplayToLogical(), searchKeyLenGet(), searchKeyLenIsValid(), searchKeyLenLogicalToDisplay(), searchKeyLenLogicalToOdbc(), searchKeyLenNormalize(), searchKeyLenSet()
property showEmpty as %ZEN.Datatype.boolean [ InitialExpression = 1 ];
If true (the default), insert an extra row with the value of emptyText at the top of the dropdown, unless required is true.
Property methods: showEmptyDisplayToLogical(), showEmptyGet(), showEmptyIsValid(), showEmptyLogicalToDisplay(), showEmptyLogicalToOdbc(), showEmptyLogicalToXSD(), showEmptyNormalize(), showEmptySet(), showEmptyXSDToLogical()
property showQuery as %ZEN.Datatype.boolean (ZENENCRYPT = 1, ZENEXPRESSION = 1) [ InitialExpression = 0 ];
Server-side diagnostic flag. If true, display the query used to get data for the dropdown.
This is an encrypted value and cannot be set on the client.
Property methods: showQueryDisplayToLogical(), showQueryGet(), showQueryIsValid(), showQueryLogicalToDisplay(), showQueryLogicalToOdbc(), showQueryLogicalToXSD(), showQueryNormalize(), showQuerySet(), showQueryXSDToLogical()
property sqlLookup as %ZEN.Datatype.sql (ZENSETTING = 0);
(optional) SQL statement that, given a value, finds a display value to show in the combo box. If present, this is used to find a display value for a given logical value.
The value of this property should be an SQL statement that returns a single row containing a display value for a given logical value. When this query is executed, a logical value is provided as a query input parameter (i.e., as a ? within the SQL statement.
For example:
 sqlLookup="SELECT Name FROM MyApp.MyTable WHERE ID = ?"
Property methods: sqlLookupDisplayToLogical(), sqlLookupGet(), sqlLookupIsValid(), sqlLookupLogicalToDisplay(), sqlLookupLogicalToOdbc(), sqlLookupNormalize(), sqlLookupSet()
property valueColumn as %ZEN.Datatype.integer (MINVAL = 1, ZENSETTING = 0) [ InitialExpression = 1 ];
If there are multiple data columns displayed in the dropdown list this is the column number (1-based) of the column that will provide the logical value for this control.
If this value is greater than the number of columns in the query then the first column will be used.
Property methods: valueColumnDisplayToLogical(), valueColumnGet(), valueColumnIsValid(), valueColumnLogicalToDisplay(), valueColumnLogicalToOdbc(), valueColumnNormalize(), valueColumnSet()

Methods

method %DrawHTML()
Inherited description: Draw the input box and button for this combobox.
Note that the actual value is placed in a hidden control as the contents of the input box may not be the actual value.
method %GetDisplayValue(pValue As %String) as %String
Lookup up the display value for the combobox given a logical value.
This is called when the control is initially drawn.
method %SetDefaultValues()
This method fills in reasonable default values for this control. Used by tools (such as Control Tester) to dynamically create controls.
clientmethod clearCache() [ Language = javascript ]
Clears any cached data held by this control. This will force the dropdown to re-execute its query the next time the dropdown is displayed.
clientmethod executeQuery(param) [ Language = javascript ]
Execute the server-side associated with this dataCombo using param as an input parameter.
Note: the results of running this query are not displayed, instead the results are written to the cache div element maintained by the dataCombo.
The searchKeyLen property is used to truncate the value of param.
The query is executed asynchronously, so results may not be available immediately.
clientmethod findDisplayValue(value) [ Language = javascript ]
Given a logical value, lookup the display value within the current set of options. Returns null if no match is found.
Subclasses may override this to add additional lookup behavior.
clientmethod getAuxValue() [ Language = javascript ]
Return the current auxiliary value (if any) for the dropdown list.
clientmethod getOptionAux(idx) [ Language = javascript ]
Return the auxiliary value for the given item (0-based) in the dropdown list.
clientmethod getOptionCount() [ Language = javascript ]
Return the current number of items within in the dropdown list.
clientmethod getOptionText(idx) [ Language = javascript ]
Return the display value for the given item (0-based) in the dropdown list.
clientmethod getOptionValue(idx) [ Language = javascript ]
Return the logical value of the given item (0-based) in the dropdown list.
clientmethod restoreConditionalStyle(trEl) [ Language = javascript ]
Retores the conditional style for trEl, a row in the dropdown table. This is used to handle selected-row style.
clientmethod selectItem(idx, show, update) [ Language = javascript ]
User has selected an item in the DropDown box. If show is true, make item visible. If update is true, update value of control.
clientmethod setProperty(property, value, value2) [ Language = javascript ]
Set the value of a named property.
clientmethod storeConditionalStyle(trEl) [ Language = javascript ]
Stores the style for trEl, a row in the dropdown table. This is used to handle selected-row style.

Inherited Members

Inherited Properties

Inherited Methods

Subclasses

FeedbackOpens in a new tab