initialize()

It initializes the Select and List controls by pre-filling them with the data provided.

Syntax

Script

controlID.initialize(oModelID , sReference);

Parameters

Parameter	Description
oModelID	This parameter is optional. Object denotes the model from which the Select or List control is initialized. If not specified, the control is initialized with the model that is specified for pre-filling.
sReference	This is an optional parameter. String denotes the starting point for data reference from which the Select or List control is initialized. The starting point is generally the response present in a model. For Transactional models, the starting point is the business object. The default value is "*".

Return Value

No value is returned.

Remarks

A control can use data from only one model at any given point of time. However, the Select and List controls can use two models, one for pre-filling the control with data, and the other for the model that is bound to it and is used to select a value. The initialize() method is used for pre-filling controls.
For pre-filling a Select or List control, you must specify the description and value as follows:

In the control's Properties dialog box, for the Existing Model and Custom Content dataset sources.
Manually, by defining the labelXQL (description) and valueXQL (value) properties of the control and using the initialize() method.

The initialize() method call also triggers the xforms-beforefill event.

A Select or List control cannot be initialized with a model that is used to bind data. You need to provide the sReference parameter if the binding data is placed deep inside the XML document hierarchy. For other scenarios (such as transactional data where data is simple and starts with a business object), the sReference parameter is automatically set as "*".

Example

The following is the response stored for the EmployeesModel data model:

<dataset>
    <data>
        <EmployeesResponse xmlns="http://some-namespace/">
            <tuple>
                <old>
                    <Employees>
                        <EmployeeID>1</EmployeeID>
                        <FirstName>Nancy</FirstName>
                    </Employees>
                </old>
            </tuple>
            <tuple>
                <old>
                    <Employees>
                        <EmployeeID>2</EmployeeID>
                        <FirstName>Andrew</FirstName>
                    </Employees>
                </old>
            </tuple>
        </EmployeesResponse>
    </data>
</dataset>

This example uses the initialize() method to insert options into the Select control using the above model.

//select1 is the ID of the select box

//set the description and value
select1.labelXQL = "FirstName";
select1.valueXQL = "EmployeeID";

//Initialize the select box
select1.initialize(EmployeesModel);

The sample XML given below represents a complex XML object, where the binding object (item) is placed well inside the document hierarchy.

<dataset>
    <data>
        <Response xmlns="http://some-namespace/">
            <ItemCollection>
                <Items>
                    <item>Item1</item>
                    <cost>1</cost>
                </Items>
                <Items>
                    <item>Item2</item>
                    <cost>2</cost>
                </Items>
                <Items>
                    <item>Item3</item>
                    <cost>3</cost>
                </Items>
            </ItemCollection>
        </Response>
    </data>
</dataset>

Use the following code to initialize the Select control for all items, with value and code as description:

//select1 is the ID of the select box

//set the description and value
select1.labelXQL = "item";
select1.valueXQL = "cost";

//Initialize the select box
select1.initialize(TestModel, "ItemCollection/Items");

Applies to

Select, List