This tutorial applies for Classic ASP, JSP, and PHP but not for ASP.NET. ASP.NET developers should see the ASP.NET tutorials instead.
The Nitobi Combobox is defined on the page by a custom tag that resembles other HTML tags you may be familiar with. Here is an example of a Combobox tag that is unbound:
The combo tag contains severall member objects like ComboTextBox and ComboList that each have their own properties. Not everything has to be defined every time - it depends on what you want out of your combo.
ntb:Combo Object
General Description:
The main tag that contains all other combo objects like ComboTextBox, ComboList, etc. This is a required tag.
Tag Example:
Attributes:
Attribute
Description
Expected Value(s)
Required
CSSClassName
The name of the CSS class to associate with the entire combo box.
string
No
DataTextField
The name of the field in the dataset that provides text for the list to display. Use this if you only want one column, and you don"t want to use the ListColumnDefinition tag.
string
No
DataValueField
The name of the field in the dataset that provides data for the list. Use this if you only want one column, and you don"t want to use the ListColumnDefinition tag.
string
No
Enabled
Specifies whether the combo is enabled for user interaction.
boolean
No
Height
The height of the combo in html units, e.g. 100px or 100%.
string
No
InitialSearch
Defines the initial value to "select" from the dataset, in bound search modes.
string
No
ListZIndex
Specifies the order of combo lists on the page along the Z axis.
Specifies the function that is called when the user makes a selection but before any action has been taken in response to this.
string
No
OnBlurEvent
Specifies the function called when the textbox of the combo loses focus.
string
No
OnFocusEvent
The name of the function (as a string - i.e. "OnFocusEvent()" - note the brackets) that is called when the textbox of the combo again focus.
string
No
OnSelectEvent
Specifies the function called when the user makes selects an item within the combobox.
string
No
OnTabEvent
The handler for the event triggered when the user tabs outside of the combo.
string
No
SmartListSeparator
Defines the character used to separate selected list records, in SmartList mode. Default value is "," (comma).
character
No
TabIndex
Specifies the HTML tab index of the combo box.
numeric
No
Width
The width of the combo in html units, e.g. 100px or 100%.
string
No
ntb:ComboTextBox Object
General Description
Defines specifically the textbox element of the combo. This is a required tag.
Tag Example:
Attributes:
Attribute
Description
Expected Value(s)
Required
CSSClassName
The name of the CSS class that defines the textbox portion of the combobox.
string
No
DataFieldIndex
The column that is used as a datasource for the textbox. When the user types in the textbox, the combo will search this column for a match. Similarly, when the user clicks a row, the column"s value will be entered into the textbox.
numeric
Yes
Editable
Specifies whether the textbox is able to be modified by the user. True, if the textbox is editable and false otherwise.
boolean
No
Height
The height of the text box. It can be in % or px, e.g., 100px or 90%.
numeric
No
OnEditKeyUpEvent
Specifies the function called upon release of a pressed key.
string
No
Value
Defines a value to be placed inside the textbox.
string
No
Width
The width of the text box. It can be in % or px, e.g., 100px or 90%.
numeric
No
ntb:ComboList Object
Description:
The tag that describes the list element. This is a required tag for all modes except the compact mode.
Tag Example:
Attributes:
Attribute
Description
Expected Value(s)
Required
AllowPaging
If set to true, the list supports large database access. It will get one page at a time. You must also set PageSize if you want to use this feature.
boolean
No
BackgroundHighlightColor
An HTML color that changes the background of a row when highlighted, e.g., #FFFFFF or red, etc. You can also use HighlightCSSClassName for more control but setting only the color yields better performance.
hex triplet
No
ClipLength
Length of clipping used in SmartList, SmartSearch and Filter modes.
numeric
No
CustomHTMLHeader
Optional. Specify a custom HTML definition for the list header. If this is used, the HeaderLabels from the ListColumnDefinition tag will not be used.
string
No
DatasourceUrl
A URL to a page that returns compressed XML. This is used for populated the ComboBox as well as for paging and lookup. The page is given the following arguments: StartingRecordIndex - The next record in the data subset that the combo wants. PageSize - Size of the page. SearchSubstring - [Optional] The string the user is looking for. ComboId - The Id of the combo making the request.
string
Yes
ForegroundHighlightColor
An HTML color that specifies the foreground (text) of a row when highlighted, e. g. #FFFFFF or red, etc. You can also use HighlightCSSClassName for more control but setting only the color yields better performance.
hex triplet
No
Height
The height of the list body. This must be an HTML measurement, e.g., 100px.
numeric
No
HighlightCSSClassName
The CSS style applied to the row when the user highlights it. You can also use BackgroundHighlightColor for better performance.
string
No
ListColumnDefinitions
The objects that define how the list columns look and behave. Not used if CustomHTMLDefinition is used.
string
No
OffsetX
DEPRECATED. Used to correct HTML glitches in the placement of the list. The number of pixels to move the list in the x direction.
numeric
No
OffsetY
DEPRECATED. Used to correct HTML glitches in the placement of the list. The number of pixels to move the list in the y direction.
numeric
No
OnAfterSearchEvent
The handler for the event that occurs after the combobox is searched (due to the user typing in something into the textbox). This string should be a JavaScript function, e.g. "OnAfterSearchEvent()". Note the brackets.
string
No
OnBeforeSearchEvent
The handler for the event that occurs before the combobox is searched (due to the user typing in something into the textbox). This string should be a JavaScript function, e.g. "OnBeforeSearchEvent()". Note the brackets.
string
No
OnHideEvent
The handler for the event that occurs when the list is hidden. This string should be a JavaScript function, e.g. SetOnHideEvent("OnHide()"). Note the brackets. If you want you can also return the List object by using SetOnHideEvent("OnHide(this)").
string
No
OnShowEvent
The handler for the event that occurs when the list is shown. This string should be a JavaScript function, with the () brackets. If you want you can also return the List object by using SetOnShowEvent("OnShow(this)").
string
No
PageSize
Used with paging. The number of records retrieved at a time. Only used if AllowPaging is set to true.
numeric
No
Width
The width of the list in either pixels or percent.
numeric
No
ntb:ComboColumnDefinition Object
Description:
Defines specific columns inside the list. These tags are not required but are recommended.
Tag Example:
Attributes:
Attribute
Description
Expected Value(s)
Required
Align
Alignment of text in this column.
"left", "right", "center"
No
ColumnType
The type of the column. It can be one of TEXT or IMAGE. If IMAGE is used, you must also specify the ImageHandlerURL property.
string
No
CSSClassName
The name of the CSS class that defines the style for this column.
string
No
DataFieldIndex
The index of the data field that populates this column. If you leave this field empty, it will use the ordinal position of the ListColumnDefinition within the List.ListColumnDefinitions collection.
numeric
Yes
HeaderLabel
The string displayed as the column header in the list.
string
No
HTMLPrefix
HTML code that will be added before the column value.
string
No
HTMLSuffix
HTML code that will be added after the column value.
string
No
ImageHandlerURL
If the ColumnType is IMAGE this property must be specfied. It contains the URL of a page that will serve up an image given an argument. That is, the database column will contain image identifiers; this identifier will be used as an argument to the page, e.g. if the URL is http://localhost/ImageServer.aspx?YourArgs=Arg, then combo will call it as follows http://localhost/ImageServer. aspx?YourArgs=Arg&Image=DataFromColumn. It will expect a binary image to be written out by the page.
string
No
TextColor
Color of the text in this column.
hex triplet
No
Width
The width of the column. This can be an absolute pixel value, e.g., 15px or a percentage of the list width, e.g., 50%.
numeric
No
ntb:ComboValues Object
Description:
In unbound mode, you can define a data island much like you would with an HTML listbox. The ComboValues tag can contain records as ntb:ComboValue. See below for an example.
Tag Example:
Attributes:
fields
Defines the data columns seperated by "|". In the ntb:ComboValue tags these are references by alphabetical labels. The first column (in the above example "City") is "a". The 2nd column ("Population") is "b". Required.
