wwHtmlHelpers::HtmlDropDown - West Wind Web Connection

wwHtmlHelpers::HtmlDropDown

Creates an HTML Drop Down list. The DropDown 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.

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

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:

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

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

Return Value

Html string for a Dropdown list.

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").

You can also use Request.FormOrValue("lstItems", [Request.FormOrValue("lstItems", poModel.ItemPk)]) whic automatically bind the value

lcDataSource
The list data source of the items displayed in the list. 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 for binding the value field in each <option> element for each item. This expression is evaluated for each item in the data source list.

lcDataTextField
An expression that is used for the display 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

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

<!-- Always explicitly assign lnSelectedPk -->
<%= HtmlDropdown("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")

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


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

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

*** Collection Binding - Single Item
loCol = CREATEOBJECT("Collection")
loCol.Add("Item1")
loCol.Add("Item2")
  
? HtmlDropdown("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

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

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

Return Value

Parameters

Example

See also: