wwHtmlHelpers::HtmlListBox - West Wind Web Connection

wwHtmlHelpers::HtmlListBox

Creates an HTML Listbox. The listbox can be populated from a data source of a cursor, array or collection and by binding an evaluated expression for text and value displays of each list item.

<%= HtmlListBox("lstCustomers",TRANSFORM(poModel.Pk),"TT_Cust",
                "TRANSFORM(Pk)",
                "Company + [(] + Careof + [)]",
                "","--- Select a Company") %>

Creates an HTML listbox. The list can be populated from a data source of a cursor, array or collection and by binding an evaluated expression for text and value displays of each list item and you can add an initial first item.

The first value is the name of the control. The second parameter is the single value that is bound and matches the selected value of the control.

The third, fourth and fifth parameters describe the list data source, and the value and display fields that are displayed when the cursor or collection is iterated.

Instead of a fixed value for binding you can also bind to Request.FormOrValue() which uses the value the form value first (in a POST operation) and the supplied value next:

<%= HtmlListBox("lstCustomers",
                [Request.FormOrValue("lstCustomers",poModel.ItemPk)],
                "TT_Cust","TRANSFORM(ttCust.pk)","Company + [(] + ttCust.Careof + [)]",
                "","--- Select a Company") %>

HtmlListBox(lcName,lcSelectedValue,lcDataSource, lcDataValueField,
            lcDataTextField, lcAttributes, 
            lcInitialText, lcInitialValue)

Return Value

Html string for an HTML listbox

Parameters

lcName
The name/id of the listbox

lcSelectedValue
The selected value for the listbox. This value should a be string.

On a Postback operation lcSelectedValue is automatically read from Request.Form() if available

You can override this behavior, and always force the value provided in this parameter explicitly to be used by postfixing the expression :FORCED to the end of the value string (ie: TRANSFORM(lnSelectedPk) + ":FORCED").

lcDataSource
The data source. Can be:

Table/Cursor Alias
A cursor that is specified as a string. Use lcDataValueField and lcDataTextField to specify which fields are used for the value and text content of the <option> element that is created.
Collection
Can contain either single column of values or a collection of objects. Pass in the object instance. If using objects specify lcDataValueField and lcDataTextField to specify which fields are used for the value and text content of the <option> element that is created.
One or two dimensional array
One dimensional array can be either single values, or an array of objects. Two dimension arrays treat the first column as the bound key and the second field as the text field. Pass the array by reference (@laItems).

lcDataValueField
An expression that is used binding the value field in each <option> element.

lcDataTextField
An expression that is used for the text content in each <option> item. If not specified the same value as lcDataValueField is used.

lcAttributes
Any extra HTML attributes you want to use on the list.

lcInitialText
Determines the first item displayed in the list for something like "--- Please select ---". If specified the value for the first item is an empty string.

lcInitialValue
The value for that first injected item.

Example

<%= HtmlListBox("lstCustomers","","TT_Cust","Trim(Company)",;
                "Company + [(] + Careof + [)]","","--- Select a Company") %>

<!-- Always explicitly assign lnSelectedPk -->
<%= HtmlListBox("lstCustomers",TRANS(lnSelectedPk) + ":FORCED","TT_Cust","Trim(Company)",;
                "Company + [(] + Careof + [)]","","--- Select a Company") %>

In more detail here are different bindings:

*** Selected value to select in listbox
lcSelectedValue = "Item2"

*** Cursor Binding - Key Value
CREATE CURSOR TITEMS (Key  varchar(40), Value varchar(100) )
INSERT INTO TItems VALUES ("Item1","First Item #1 Db")
INSERT INTO TItems VALUES ("Item2","Second Item #2 Db")

? HtmlListBox("lstItemsCursor",lcSelectedValue,"TItems","Key","Value")


*** Array Binding  - Single Item
DIMENSION laItems[2]
laItems[1] = "Item1"
laItems[2] = "Item2"

? HtmlListBox("lstItemsArray",lcSelectedValue,@laItems)

*** Collection Binding - Single Item
loCol = CREATEOBJECT("Collection")
loCol.Add("Item1")
loCol.Add("Item2")
  
? HtmlListBox("lstItemsCollection",lcSelectedValue,loCol)

*** Object Binding for arrays and collections
loObj1 = CREATEOBJECT("EMPTY")
ADDPROPERTY(loObj1,"Key","Item1")
ADDPROPERTY(loObj1,"Value","First Item #1")

loObj2 = CREATEOBJECT("EMPTY")
ADDPROPERTY(loObj2,"Key","Item2")
ADDPROPERTY(loObj2,"Value","Second Item #2")

?
? loObj1.Key
? loObj1.Value
? loObj2.Key
? loObj2.Value
?

*** Array of Objects Binding
DIMENSION laItems[2]
laItems[1] = loObj1
laItems[2] = loObj2

? HtmlListBox("lstItemsArray2",lcSelectedValue,@laItems,"Key","Value")

*** Collection of Objects Binding
loCol = CREATEOBJECT("Collection")
loCol.Add(loObj1)
loCol.Add(loObj2)
  
? HtmlListBox("lstItemsCollection",lcSelectedValue,loCol,"Key","Value")

Return Value

Parameters

Example

See also: