CallGuide Databinding

The CallGuide application provides a framework that allows elements contained on a web page to be bound. Elements may be bound to rostrvm CLIPboard, a Database table or Persisted allowing manipulation within the CallGuide.custom file.

This section provides advanced details of CallGuide databinding.

The following sections describe:

•	database and persisted bound elements;

•	rostrvm CLIPboard data binding;

•	database data binding.

Database and Persisted Bound Elements

Database table or Persisted elements are bound to a Data Source Object (DSO) ActiveX object embedded on the same page as the bound elements.

When a web page containing a DSO is loaded, a request is made to CallGuide to load any available data into the DSO. Loading data into the DSO automatically propagates the data to the bound elements on the page.

When an agent modifies an element's data, the Data Source is automatically updated and CallGuide is informed of the change. The change is then propagated to the appropriate database table or persisted storage by CallGuide.

CallGuide_databinding1

Configuring a Database DSO

In order to bind an element to a database table column the following must be added.

<head>

<?IMPORT NAMESPACE="databinding" IMPLEMENTATION="../js/DataBinding.htc">

</head>

…

<html>

A Database binding object (XML DSO) must be present within the HTML document for database binding to work. To add a Database binding object the following line (in bold) must be added to each HTML document (.htm) requiring database binding.

<head>

<databinding:dataSrc Name="Information" />

…

</head>

Multiple database binding objects may be embedded into a single HTML document. Each Database Binding object must have a unique name.

Each Database binding object maps onto a dataset defined within the rostrvm Data Binding Web Services (see ref 5). Once mapped the columns defined in the dataset are available to the HTML document for binding.

The procedure for binding a single-valued HTML element to data is the same regardless of the element. Elements are bound to data using the dataSrc, dataFld and class attributes.

Binding an Input (Text) Element to a Database

To bind an HTML text box element the following line would be added to a CallGuide .htm file:

The dataSrc attribute in this example specifies the name of the Database Binding object, prefixed by a hash mark (#) embedded on the page. The hash mark is required.

The dataFld attribute identifies the database table column name to which the text box should be bound.

The class attribute must be set to DataElement for a Database bound element.

Binding a Table Element to a Database

To bind an HTML table element it must be remembered that the table element is a tabular data consumer, it relies on the elements that it contains to bind to the individual fields in the data set provided by the Database Binding object.

The contained elements serve as a template, and they are repeated once for each record in the data set.

The table specifies the dataSrc attribute. The contained elements specify the dataFld attribute and inherit the dataSrc from the table.

When binding a table to data, it is not possible to databind to a tr if it is contained by a tFoot or tHead.

Here's a simple example:

<tr>

</tr>

</table>

Read Only Bindable Elements

Bindable HTML elements that supply read-only functionality include; a, button, div, img, frame, iframe, label, marquee and span.

Read/Write Bindable Element

The input (with the exception of the button type), select, textArea, object and applet elements support updating the data to which they are bound.

For examples on how to bind these HTML elements see the Database Data Binding section

Persisting HTML Control Element data

HTML control element data may be bound to temporary storage elements. This allows HTML control element data to be maintained even after the document has been re-loaded by the browser. The temporary storage elements are maintained for the life of the current CallGuide script.

CallGuide Persist binding is implemented using XML data islands in a similar fashion to CallGuide data binding.

To Persist HTML control element data binding for a given HTML page the following lines must be added.

<head>

<?IMPORT NAMESPACE=”persistbinding” implementation="../js/PersistBinding.htc" />

</head>

…

<html>

A Persist binding object (XML DSO) must be present within the HTML document for persist binding to work. To add a Persist binding object the following line (in bold) must be added to each HTML document (.htm) requiring persist binding.

<head>

<persistbinding:dataSrc Name="Example2" />

…

</head>

Multiple persist binding objects may be embedded into a single HTML document. Each Persist Binding object must have a unique name. The procedure for binding a single-valued HTML element is the same regardless of the element. Elements are bound using the dataSrc, dataFld and class attributes.

To bind an HTML text box element the following line would be added to a CallGuide .htm file:

The dataSrc attribute in this example specifies the name of the Database Binding object, prefixed by a hash mark (#) embedded on the page. The hash mark is required.

The dataFld attribute specifies a unique data source field name to which the text box should be bound.

The class attribute must be set to PersistElement for a Persist bound element.

Bound HTML elements data can be manipulated from the CallGuide .custom or from java script contained within the page using a set of access functions provided by CallGuide.

The following functions are available from javascript (within an HTML page) or vbscript (from CallGuide .custom file).

PersistData_DeleteRow(dataSrc, index)	Used when binding a table to delete a given row from a table.
PersistData_Refresh(dataSrc, doc)	Reload DSO with persisted data. If Persisted data has been modified programmatically a refresh is required to display updated bound data.
PersistData_Update(dataSrc, dataFld, value)	Programmatically updates a bound persisted data value. The last row is updated in a multi-row persist control.
PersistData_NewRow(dataSrc)	Create a new row in a multi-row persist control (such as a table)
PersistData_NumRows(dataSrc)	Returns the number of persist rows in a persist bound control.
PersistData_GetValue(dataSrc, rowIndex, dataFld)	Returns the value contained within a persist bound control.

rostrvm CLIPboard Binding

HTML control elements (normally text boxes) may be bound to rostrvm CLIPboard elements.

CallGuide_databinding2

To bind an HTML Text Box control element to the rostrvm CLIPboard element +AccountName the following should be specified:

The element class property must be set to ClipElement. The name property specifies the CLIPboard element to bind to.

Database Data Binding

Input HTML Element

The input element represents a set of HTML intrinsic controls. Each of the types that support data binding <input type=checkbox, input type=hidden, input type=password, input type=radio, and input type=text> is detailed below.

Input HTML Element – CHECKBOX

Although check boxes allow a value attribute that is used when submitting an HTML form on a page, Internet Explorer MSHTML uses check boxes as simple Boolean selections. Check boxes generate the Boolean values true or false depending on whether they are checked or not. The binding agent coerces the values to and from the underlying data set. The following coercions are supported, based on the type of the bound column.

The following table describes the values that a bound check box expects a DSO to supply for various data types.

Data type	Expected True value	Expected False value
String	"True" \| "1" \| <nonempty string>	"False" \| "0" \| <zerolength string>
Integer	nonzero	0
Float	nonzero	0
Date	invalid	invalid
Currency	nonzero	0

The following is an example of a bound check box.

Input HTML Element – HIDDEN

The HIDDEN type is used to store information in the page that isn't displayed to the user. The element is populated with data from the current record, but it cannot be modified. The following is an example of a bound hidden field.

Input HTML Element – PASSWORD

The PASSWORD type is basically the same as the TEXT type except that the bound text is not displayed to the user. Be careful when using this input type, because the associated data is fully accessible to scripts through the data-binding object model, as well as directly through the element's value. The following is an example of a bound password.

Input HTML Element – RADIO

Radio buttons are used to select a single value from a set of alternatives. They can be used to select the value for an enumerated field in a database. One radio button is specified for each of the alternatives using a separate input. The name attribute on the input determines the logical grouping of alternatives. One value is bound for all the inputs with the same name attribute. All members of a group must specify the corresponding dataSrc and dataFld attributes. The following is an example of a bound radio button group.

<INPUT TYPE="RADIO" NAME="cards" VALUE="mc"

DATASRC="#dsoOrders" DATAFLD="cardname" CLASS=”DataElement”>MasterCard

<INPUT TYPE=RADIO NAME="cards" VALUE="amex"

DATASRC="#dsoOrders" DATAFLD="cardname" CLASS=”DataElement”>American Express

<INPUT TYPE="RADIO" NAME="cards" VALUE="visa"

DATASRC="#dsoOrders" DATAFLD="cardname" CLASS=”DataElement”>Visa

Input HTML Element – TEXT

The TEXT type is used as a simple text box. The value of the text box can be bound to a field in the data source using the dataSrc and dataFld attributes. The following is an example of a bound text box.

Input HTML Element – OBJECT

When dataSrc and dataFld are specified on an object, Internet Explorer attempts to bind to the object's default property. The defaultbind attribute specified in an object's type information uniquely identifies the default property. If a default property is not specified in this way, Internet Explorer uses the property with DISPID 0.

The following is an example of binding the default value on the object tag.

<OBJECT ID=oControl1 WIDTH=100 HEIGHT=100

CLASSID="CLSID:xxxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxxx"

DATASRC="#DSC1" DATAFLD="controlData">

</OBJECT>

Additionally, Internet Explorer supports binding to arbitrary object properties through the object's contained param tags. To do this, apply the dataSrc and dataFld attributes to the param tag. The property's value is initialized with the data supplied by the DSO. The following is an example of binding the params on the object tag.

<OBJECT ID="oControl1" WIDTH=100 HEIGHT=100

CLASSID="CLSID:xxxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxxx">

</OBJECT>

Bindings can be applied simultaneously to the object's default value as well as to its param tags.

Input HTML Element – SELECT

A select element supplies the functionality of a drop-down combo box or a list box. Internet Explorer supports binding to a single selected element, but not to multiple selections.

The items in a select control are specified using option tags. The DHTML Object Model defines an options array that corresponds to the collection of option tags for a select. Each option has a corresponding index, text, and value. select has a selectedIndex property that corresponds to the index of the option currently selected. If no item is selected, the selectedIndex is set to -1. The text attribute of an option corresponds to the text that follows the tag and represents the string that is displayed for that option tag in the select. The value attribute provides the value that is to be returned when the HTML form is submitted. Value is also what is stored into the bound column of the data source.

Initially, the selectedIndex property of a bound select element will be set to the index of the value in the options array that corresponds to the field of the data source. If the value is not a member of the options array, the index property is set to -1 and, if the select is a combo, no value is displayed. When the user changes the selected item, the corresponding option value (attribute) is used to update the value of the bound field of the data source. Validation events are fired as with other controls.

If a select element is bound to an empty record, the selectedIndex property is not available. This scenario can arise when using the Remote Data Service (RDS) DSO if a select element databinds to a blank record. By updating the selected option, the blank databound record is updated and RDS returns the modified record to the server.

The following is an example of a bound select.

<OPTION VALUE=mc>MasterCard

<OPTION VALUE=amex>American Express

<OPTION VALUE=visa>Visa

</SELECT>

Input HTML Element – TEXTAREA

A textArea is a multirow text box for data input, similar to the input type=text intrinsic. As such, it supports the update of the data if the DSO supports the update feature. The following is an example of a bound textArea.

APPLET

Internet Explorer supports binding to the param tags of an applet. The following example specifies a binding on the xyz property of the application.

</APPLET>