Contents of the dataCombo DropdownThe 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:
- If the %ResultSet has one column, then the contents of this column are used as both the logical and display values within the dropdown.
- If the %ResultSet has two (or more) columns, then the contents of the first column supply the logical value and the contents of the second column supply the display values. You can change which columns are used to provide the logical and display values using the valueColumn and choiceColumn properties.
- If the %ResultSet has more than two columns, then you can use the displayColumns and columnHeaders properties to specify that the dropdown should display multiple columns (only one column will be used for a display value).
Logical and Display ValuesA 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:
This does the following:
<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" />
- 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.
- 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.
Query ParametersThe 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:
- 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.
- 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.
parameter DOMAIN = "%ZEN"; parameter USECACHEDIV = 1;
Indicates that this combobox should cache its dropdown contents.
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. property cached as %ZEN.Datatype.boolean [ InitialExpression = 0 ];
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.
If true (the default is false) then the following behavior occurs:
The clearCache property choiceColumn as %ZEN.Datatype.integer(MINVAL=1,ZENSETTING=0) [ InitialExpression = 2 ];
- 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.
- The client will use these results instead of going back to the server to fetch the contents of the dropdown.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. property clearOnLoad as %ZEN.Datatype.boolean [ InitialExpression = 0 ];
If this value is greater than the number of columns in the query then the second column will be used.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 columnHeaders as %ZEN.Datatype.csv(ZENLOCALIZE=1);If defined, this is a comma-delimited list of column headers displayed in the dropdown list. 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 contentType as %ZEN.Datatype.string(VALUELIST=",text,html") [ InitialExpression = "text" ];Indicates how display values should be rendered: property displayColumns as %ZEN.Datatype.csv(ZENSETTING=0);
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.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 emptyText as %ZEN.Datatype.caption;The text to be displayed in the "empty" item displayed if showEmpty is true. The default is "". property itemCount as %ZEN.Datatype.integer(XMLPROJECTION="none",ZENSETTING=0) [ InitialExpression = 0 ];Number of items in the drop down. property loadingMessage as %ZEN.Datatype.caption;
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.Localized "loading" message displayed by control. property multiColumn as %ZEN.Datatype.boolean [ InitialExpression = 1 ];
This message is temporarily displayed while a server-side query is running.If true (the default), then display multiple columns in the drop down box if the result set contains more than 2 columns. 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 parameters as list of %ZEN.Auxiliary.parameter(XMLNAME="parameter",XMLPROJECTION="ELEMENT");User-defined list of query parameters. property searchKeyLen as %ZEN.Datatype.integer(MINVAL=0) [ InitialExpression = 0 ];
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.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. property showEmpty as %ZEN.Datatype.boolean [ InitialExpression = 1 ];
If zero, then the contents of the input box are not used as a parameter.If true (the default), insert an extra row with the value of emptyText at the top of the dropdown, unless required is true. 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. property sqlLookup as %ZEN.Datatype.sql(ZENSETTING=0);
This is an encrypted value and cannot be set on the client.(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. property valueColumn as %ZEN.Datatype.integer(MINVAL=1,ZENSETTING=0) [ InitialExpression = 1 ];
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.
sqlLookup="SELECT Name FROM MyApp.MyTable WHERE ID = ?"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.
Draw the input box and button for this combobox. method %GetDisplayValue(pValue As %String) as %String
Note that the actual value is placed in a hidden control as the contents of the input box may not be the actual value.
Lookup up the display value for the combobox given a logical value. method %SetDefaultValues()
This is called when the control is initially drawn.
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.
Subclasses may override this to add additional lookup behavior.
Stores the style for trEl, a row in the dropdown table. This is used to handle selected-row style.