Class Reference
%ZEN.Component.dataCombo
Server:basexml
Instance:SOAXML
User:UnknownUser
  
-
  [BASEXML] >  [%ZEN] >  [Component] >  [dataCombo]
Private  Storage

class %ZEN.Component.dataCombo extends abstractComboBox, 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.

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
2 20 21


Summary

Properties
%condition %import %includeFiles %page
%resource OnCreateResultSet OnExecuteResultSet align
aux auxColumn buttonCaption buttonImage
buttonImageDown buttonTitle cached choiceColumn
clearOnLoad clientType columnHeaders columnName
comboType composite conditions containerStyle
contentType controlClass controlStyle countRows
dataBinding delay disabled displayColumns
dragEnabled dropEnabled dropdownHeight dropdownWidth
editable enclosingClass enclosingStyle error
groupByClause height hidden hint
hintClass hintStyle hzScroll id
index invalid invalidMessage isDropdownVisible
itemCount label labelClass labelDisabledClass
labelStyle loadingMessage maxRows maxlength
multiColumn name onafterdrag onbeforedrag
onblur onchange onclick ondblclick
ondrag ondrop onfocus onhide
onkeydown onkeypress onkeyup onmousedown
onmouseout onmouseover onmouseup onrefresh
onshow onshowDropdown onsubmit onupdate
onvalidate orderByClause originalValue parameters
parent queryClass queryName readOnly
required requiredMessage scrollIntoView searchKeyLen
selectedIndex showEmpty showLabel showQuery
size slice sql sqlLookup
tabIndex tableName text title
tuple unrestricted valign value
valueColumn visible whereClause width
window

Methods
%%OIDGet %AddToSaveSet %Attr %BindExport
%ClassIsLatestVersion %ClassName %ConstructClone %CreateResultSet
%DispatchClassMethod %DispatchGetModified %DispatchGetProperty %DispatchMethod
%DispatchSetModified %DispatchSetMultidimProperty %DispatchSetProperty %DrawComponentHTML
%DrawHTML %DrawJSStrings %EnclosingDivId %Eval
%Extends %ForceClientRender %GetDisplayValue %GetEventHandlers
%GetForm %GetParameter %GetXMLName %IsA
%IsModified %MakeId %Name %New
%NormalizeObject %ObjectModified %OnAddToPageAfter %OnAddToPageBefore
%OnCreateResultSet %OnDrawEnclosingDiv %OnDrawObjectProperties %OnExecuteResultSet
%OnObjectSynch %OnZENDeserialize %OriginalNamespace %PackageName
%QuoteValue %QuoteValueL10N %RemoveFromSaveSet %Self
%SerializeObject %SetDefaultValues %SetModified %ValidateObject
XMLDTD XMLExport XMLExportToStream XMLExportToString
XMLNew XMLSchema XMLSchemaNamespace XMLSchemaType
adjustDropdownPosition clearCache comboboxButtonDown comboboxButtonUp
comboboxMouseOut comboboxMouseOver dragFinishHandler dragHandler
dragNotifyHandler dragStartHandler dropHandler dropStartHandler
executeQuery exposeComponent findDisplayValue findElement
findSelectedItem fireOnUpdateEvent focus formatValue
getAuxValue getCacheDiv getDisabled getDragData
getDropDownDiv getEnclosingDiv getForm getHidden
getHintElement getInvalidReason getItemEl getLabelElement
getOptionAux getOptionCount getOptionText getOptionValue
getProperty getReadOnly getSettings getType
getValue inputKeyHandler invokeSuper isModified
isOfType isValid makeId normalizeValue
onCreate onDelete onDisplayHandler onEndModalHandler
onPopupAction onRefreshContents onSerialize onStartModalHandler
onchangeHandler onloadHandler onresizeHandler onunloadHandler
onupdateHandler refreshContents render renderContents
renderSVG restoreConditionalStyle select selectItem
setDisabled setHidden setOverlayMode setProperty
setReadOnly setValue showDropdown startProgressBar
stopProgressBar storeConditionalStyle sysName unformatValue
validationHandler


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 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 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 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 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:
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 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 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 loadingMessage as %ZEN.Datatype.caption;
Localized "loading" message displayed by control.
This message is temporarily displayed while a server-side query is running.
• 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 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.
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 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 showEmpty as %ZEN.Datatype.boolean [ InitialExpression = 1 ];
If true (the default), insert an extra blank row (with value = "") at the top of the dropdown, unless required is true.
• property showQuery as %ZEN.Datatype.boolean(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);
(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 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.

Methods

• method %DrawHTML()
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. A logical value of "", must have a display value of "".
• method %SetDefaultValues()
This method fills in reasonable default values for this control. Used by tools (such as Control Tester) to dynamically create controls.
• method 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.
• method 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.
• method 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.
• method getAuxValue() [ Language = javascript ]
Return the current auxiliary value (if any) for the dropdown list.
• method getOptionAux(idx) [ Language = javascript ]
Return the auxiliary value for the given item (0-based) in the dropdown list.
• method getOptionCount() [ Language = javascript ]
Return the current number of items within in the dropdown list.
• method getOptionText(idx) [ Language = javascript ]
Return the display value for the given item (0-based) in the dropdown list.
• method getOptionValue(idx) [ Language = javascript ]
Return the logical value of the given item (0-based) in the dropdown list.
• method restoreConditionalStyle(trEl) [ Language = javascript ]
Retores the conditional style for trEl, a row in the dropdown table. This is used to handle selected-row style.
• method 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.
• method setProperty(property, value, value2) [ Language = javascript ]
Set the value of a named property.
• method storeConditionalStyle(trEl) [ Language = javascript ]
Stores the style for trEl, a row in the dropdown table. This is used to handle selected-row style.