Client API Reference

Documentation home

 

 

Functions 2

getComponentPrefix 2

getField. 2

getFieldValue. 3

getFields 5

setField. 6

setFieldValue. 8

setFields 10

getTable. 12

getTableFilteredByRows 13

getTables 14

executeFunction. 15

executeFunctionAsynchronously. 17

registerEventHandler 19

Objects 21

Field. 21

getElementName. 21

getValue. 22

getDisplayValue. 22

setValue. 23

setDisplayValue. 24

Table. 25

getElementName. 25

getCurrentRow. 25

setCurrentRow. 26

getRowCount 26

getLastRowId. 26

getRows 27

getColumn. 27

getColumns 28

getColumnValueOnRow. 28

getColumnDisplayValueOnRow. 29

findRow. 29

TableColumn. 30

getElementName. 30

getValue. 30

getDisplayValue. 31

TableRowIterator 32

next 32

previous 33

first 33

last 34

getSize. 34

 

See Also: Client API Guide

 

Functions

getComponentPrefix

 

Syntax:

$eb.getComponentPrefix()

 

 

Description:

Returns the component prefix when a client event is triggered by a control that is part of a component, returns null if no component context exists.

 

In most circumstances the system correctly determines when a client event is part of a component, and the component prefix is then automatically passed to the server on $eb.executeFunction() calls so that the server can set the component context appropriately. But there are some circumstances where this does not work. The example below shows code that might be added to a control’s ready event and is executed each time the page is displayed. The component prefix is available in the ready event, but it will not normally be available in the click function which runs some time later.  In this circumstance we need to explicitly pass the component prefix to the server as shown in the example.

 

 

 

Example:

 

var pfx = getComponentPrefix();

$('xxxx').click(function() {

   $eb.executeFunction('myfunction', null, false, false, null, pfx);

});

 

 

Since:

V5.5

getField

 

Syntax:

$eb.getField(fieldname, failureCallBack)

 

 

Description:

Retrieves a Field from the server.

 

Params:

    fieldname - string: the name of the Field to get from the server.

 

    failureCallBack(optional) – a function: a call back function can be provided which will be called in the case where there is a failure during communication with the server, or when the server itself cannot retrieve the Field. A textual representation of the error (if known) is passed in as a parameter.

 

Returns:

    A $eb.Field representing the Field on the server. Can be null or undefined (this usually denotes that there was an error communicating with the server or the server was unable to get the Field).

 

    The value of the returned $eb.Field has a different representation depending on the type of the Field on the server:

 

Field Type

Javascript object

Boolean

a boolean

Character

a string

Integer

a number

Numeric

a number

Currency

a number

Date

a number representing the number of milliseconds since 1st January 1970, where the time portion is initially set to 00:00

Datetime

a number representing the number of milliseconds since 1st January 1970

Time

a number representing the number of milliseconds since midnight

Object

a Javascript representation of the object. Note that this object will have been sent via a JSON representation thus contains publicly available data of the server-side object (i.e. no methods/functions)

 

The Field must have been marked as accessible in the designer otherwise the method will return null (see Client Accessible Fields and Tables for more information).

 

This function is synchronous - that is it requests, waits and returns the Field from the server. During this time the browser will be unresponsive to user activity.

 

 

Example:

var field1 = $eb.getField("FIELD1");

if(field1.value == field1.getValue())

{

    alert("This is always true");

}

 

 

Since:

V4.5

  

getFieldValue

 

Syntax:

$eb.getFieldValue(fieldname, failureCallBack)

 

 

Description:

Retrieves the Field's value from the server.

 

Params:

    fieldname - string: the name of the Field to get from the server.

 

    failureCallBack(optional) – a function: a call back function can be provided which will be called in the case where there is a failure during communication with the server, or when the server itself cannot retrieve the Field. A textual representation of the error (if known) is passed in as a parameter.

 

Returns:

    The value of the Field on the server. Can be null or undefined (this usually denotes that there was an error communicating with the server or the server was unable to get the Field).

 

    The returned value has a different representation depending on the type of the Field on the server:

 

Field Type

Javascript object

Boolean

a boolean

Character

a string

Integer

a number

Numeric

a number

Currency

a number

Date

a number representing the number of milliseconds since 1st January 1970, where the time portion is initially set to 00:00

Datetime

a number representing the number of milliseconds since 1st January 1970

Time

a number representing the number of milliseconds since midnight

Object

a Javascript representation of the object. Note that this object will have been sent via a JSON representation thus contains publicly available data of the server-side object (i.e. no methods/functions)

 

The Field must have been marked as accessible in the designer otherwise the method will return null (see Client Accessible Fields and Tables for more information).

 

This function is synchronous - that is it requests, waits and returns the Field from the server. During this time the browser will be unresponsive to user activity.

 

 

Example:

var fieldvalue = $eb.getFieldValue("FIELD1");

alert(fieldvalue); // shows the value of FIELD1

 

 

Since:

V4.5

 

getFields

 

Syntax:

$eb.getFields(fieldnamearray, failureCallBack)

 

 

Description:

Retrieves the Fields with the given names from the server.

 

Params:

    fieldnamearray - an array of strings: the names of the Fields to get from the server.

 

    failureCallBack(optional) – a function: a call back function can be provided which will be called in the case where there is a failure during communication with the server, or when the server itself cannot retrieve the Field. A textual representation of the error (if known) is passed in as a parameter.

 

Returns:

    An object representing each Field requested as an $eb.Field, keyed by its name. If a Field named in the array cannot be found on the server then it will be undefined in the returned object.

 

Each $eb.Field's value representation varies depending on the type of the Field on the server:

 

Field Type

Javascript object

Boolean

a boolean

Character

a string

Integer

a number

Numeric

a number

Currency

a number

Date

a number representing the number of milliseconds since 1st January 1970, where the time portion is initially set to 00:00

Datetime

a number representing the number of milliseconds since 1st January 1970

Time

a number representing the number of milliseconds since midnight

Object

a Javascript representation of the object. Note that this object will have been sent via a JSON representation thus contains publicly available data of the server-side object (i.e. no methods/functions)

 

The Field must have been marked as accessible in the designer otherwise the method will return null (see Client Accessible Fields and Tables for more information).

 

This function is synchronous - that is it requests, waits and returns the Field from the server. During this time the browser will be unresponsive to user activity.

 

 

Example:

var fields = $eb.getFields(["FIELD1","FIELD2"]);

var field1 = fields.FIELD1;

var field2 = fields.FIELD2;

var field1val = fields.FIELD1.value;

var field1val = fields.FIELD1.getValue();

 

 

Since:

V4.5

 

setField

 

Syntax:

$eb.setField(field,autorefresh,failureCallBack)

 

 

Description:

Sets the corresponding Field on the server.

 

Params:

    field - a $eb.Field: The given Field’s value must be in a representation compatible with the type of the Field on the server, see below.

 

    autorefresh(optional) – boolean: true/false (false by default). Before returning from this method, the system will refresh any control that has been changed as a result of the change to the field value. Note that this may substantially alter the page, and any variables pointing to data before this function was run may now be out of date. It is strongly recommended that the Form be configured to use ajax communication when using the autorefresh feature.

 

    failureCallBack(optional) – a function: a call back function can be provided which will be called in the case where there is a failure during communication with the server, or when the server itself cannot retrieve the Field. A textual representation of the error (if known) is passed in as a parameter.

 

Returns:

    true if successfully set, otherwise false

 

The given $eb.Field's value must be in a form compatible with the type of Field being set on the server:

 

Field Type

Allowable JavaScript representations

Boolean

boolean: any value

string: true values are "true", "Y", "Yes", "1", false values are "false", "N", "No", "0"

number: 1 is true, 0 is false

Character

string: any value

boolean: true becomes "Y", false becomes "N"

number: any number

Integer

Number

Currency

string: any numeric value

number: any value

Date

date: JavaScript Date objects can be used

string: must be in the format specified in parameter Ufs.dateFormat in file UFSSetup.properties. Note that these strings do not contain timezone information and therefore there may be differences between the given and the created value.

number: represents the number of milliseconds since 1st January 1970

Datetime

date: JavaScript Date objects can be used

string: Date followed by a space then Time. Date must be in the format specified in parameter Ufs.dateFormat in file UFSSetup.properties. Time is in the format hh:mm:ss.ttt. Note that as a string does not contain timezone information and therefore there may be differences between the given and the created value.

number: represents the number of milliseconds since 1st January 1970

Time

date: JavaScript Date objects can be used

string: must be in the format hh:mm:ss.ttt. Note that as a string does not contain timezone information there may be differences between the given and the created value.

number: represents the number of milliseconds since midnight

Object

a JavaScript object. Note that this object will have been sent via a JSON representation thus contains publicly available data of the object (i.e. no methods/functions). Basic JavaScript arrays and objects are sent as-is and will be set as such.

 

The Field must have been marked as Read/Write accessible in the designer otherwise the method will return null (see Client Accessible Fields and Tables for more information).

 

This method cannot be used to create new Fields on the server - it can only update existing ones. If the Field has not been marked as read/write in the designer this method will return false (and a textual representation of the error will be passed to the failureCallBack function if one has been supplied) and the Field will not have been set.

 

This function is synchronous - that is it requests, waits and returns the Field from the server. During this time the browser will be unresponsive to user activity.

 

 

Example:

var messageField = new $eb.Field("MESSAGE_FIELD", "This is a message", null);

$eb.setField(messageField); (which is equivalent to $eb.setField(messageField, null, null);

 

 

Since:

V4.5

 

setFieldValue

 

Syntax:

$eb.setField(fieldname, value, autorefresh, failureCallBack)

 

 

Description:

Sets the corresponding Field on the server.

 

Params:

    field – string: the name of the Field on the server.

 

    value – a type or object: the value to set the corresponding Field to. This value must be in a representation compatible with the type of the Field on the server, see below

 

    autorefresh(optional) – boolean: true/false (false by default). Before returning from this method, the system will refresh any control that has been changed as a result of the change to the field value. Note that this may substantially alter the page, and any variables pointing to data before this function was run may now be out of date. It is strongly recommended that the Form be configured to use ajax communication when using the autorefresh feature.

 

    failureCallBack(optional) – a function: a call back function can be provided which will be called in the case where there is a failure during communication with the server, or when the server itself cannot retrieve the Field. A textual representation of the error (if known) is passed in as a parameter.

 

Returns:

    true if successfully set.

 

The value must be in a form compatible with the type of Field being set on the server:

 

Field Type

Allowable JavaScript representations

Boolean

boolean: any value

string: true values are "true", "Y", "Yes", "1", false values are "false", "N", "No", "0"

number: 1 is true, 0 is false

Character

string: any value

boolean: true becomes "Y", false becomes "N"

number: any number

Integer

Number

Currency

string: any numeric value

number: any value

Date

date: JavaScript Date objects can be used

string: must be in the format specified in parameter Ufs.dateFormat in file UFSSetup.properties. Note that these strings do not contain timezone information and therefore there may be differences between the given and the created value.

number: represents the number of milliseconds since 1st January 1970

Datetime

date: JavaScript Date objects can be used

string: Date followed by a space then Time. Date must be in the format specified in parameter Ufs.dateFormat in file UFSSetup.properties. Time is in the format hh:mm:ss.ttt. Note that as a string does not contain timezone information and therefore there may be differences between the given and the created value.

number: represents the number of milliseconds since 1st January 1970

Time

date: JavaScript Date objects can be used

string: must be in the format hh:mm:ss.ttt. Note that as a string does not contain timezone information there may be differences between the given and the created value.

number: represents the number of milliseconds since midnight

Object

a JavaScript object. Note that this object will have been sent via a JSON representation thus contains publicly available data of the object (i.e. no methods/functions). Basic JavaScript arrays and objects are sent as-is and will be set as such.

 

The Field must have been marked as Read/Write accessible in the designer otherwise the method will return null (see Client Accessible Fields and Tables for more information).

 

This method cannot be used to create new Fields on the server - it can only update existing ones. If the Field has not been marked as read/write in the designer this method will return false (and a textual representation of the error will be passed failureCallBack function if one has been supplied) and the Field will not have been set.

 

This function is synchronous - that is it requests, waits and returns the Field from the server. During this time the browser will be unresponsive to user activity.

 

 

Example:

$eb.setFieldValue("STRING_FIELD1", "Set the value to this string");

$eb.setFieldValue("STRING_FIELD1", "Set the value to this string", true);

$eb.setFieldValue("STRING_FIELD1", "Set the value to this string", true, function(failureMessage){alert failureMessage;});

 

 

Since:

V4.5

 

setFields

 

Syntax:

$eb.setField(fieldarray, autorefresh, failureCallBack)

 

 

Description:

Sets the corresponding Field on the server.

 

Params:

    fieldarray - an array of $eb.Field. Each Field’s value must be in a representation compatible with the type of the Field on the server, see below.

 

    autorefresh(optional) – boolean: true/false (false by default). Before returning from this method, the system will refresh any control that has been changed as a result of the change to the field values. Note that this may substantially alter the page, and any variables pointing to data before this function was run may now be out of date. It is strongly recommended that the Form be configured to use ajax communication when using the autorefresh feature.

 

    failureCallBack(optional) – a function: a call back function can be provided which will be called in the case where there is a failure during communication with the server, or when the server itself cannot retrieve the Field. A textual representation of the error (if known) is passed in as the first parameter. An array of the Field names that could not be retrieved will be passed (if not a communication error) as the second parameter.

 

Returns:

    true if one or more of the given Fields are correctly set.

 

Each $eb.Field's value must be in a form compatible with the type of Field being set on the server:

 

Field Type

Allowable JavaScript representations

Boolean

boolean: any value

string: true values are "true", "Y", "Yes", "1", false values are "false", "N", "No", "0"

number: 1 is true, 0 is false

Character

string: any value

boolean: true becomes "Y", false becomes "N"

number: any number

Integer

Number

Currency

string: any numeric value

number: any value

Date

date: JavaScript Date objects can be used

string: must be in the format specified in parameter Ufs.dateFormat in file UFSSetup.properties. Note that these strings do not contain timezone information and therefore there may be differences between the given and the created value.

number: represents the number of milliseconds since 1st January 1970

Datetime

date: JavaScript Date objects can be used

string: Date followed by a space then Time. Date must be in the format specified in parameter Ufs.dateFormat in file UFSSetup.properties. Time is in the format hh:mm:ss.ttt. Note that as a string does not contain timezone information and therefore there may be differences between the given and the created value.

number: represents the number of milliseconds since 1st January 1970

Time

date: JavaScript Date objects can be used

string: must be in the format hh:mm:ss.ttt. Note that as a string does not contain timezone information there may be differences between the given and the created value.

number: represents the number of milliseconds since midnight

Object

a JavaScript object. Note that this object will have been sent via a JSON representation thus contains publicly available data of the object (i.e. no methods/functions). Basic JavaScript arrays and objects are sent as-is and will be set as such.

 

Each Field must have been marked as Read/Write accessible in the designer otherwise the method will return null (see Client Accessible Fields and Tables for more information).

 

This method cannot be used to create new Fields on the server - it can only update existing ones. If the Field has not been marked as read/write in the designer this method will return false (and a textual representation of the error will be passed failureCallBack function if one has been supplied) and the Field will not have been set.

 

This function is synchronous - that is it requests, waits and returns the Field from the server. During this time the browser will be unresponsive to user activity.

 

 

Example:

var field1 = $eb.getField(“FIELD1”);

field1.value = “New Value”;

 

var field2 = new $eb.Field(“FIELD2”, “A Value”, “”);

 

$eb.setFields([field1, field2], true);

 

 

Since:

V4.5

 

getTable

 

Syntax:

$eb.getTable(tablename, failureCallBack)

 

 

Description:

Retrieves a Table from the server.

 

Params:

    tablename - string: the name of the Table to get from the server.

 

    failureCallBack(optional) – a function: a call back function can be provided which will be called in the case where there is a failure during communication with the server, or when the server itself cannot retrieve the Table. A textual representation of the error (if known) is passed in as a parameter.

 

Returns:

    A $eb.Table representing the Table on the server. Can be null or undefined (this usually denotes that there was an error communicating with the server or the server was unable to get the Table).

 

The Table must have been marked as accessible in the designer otherwise the method will return null (see Client Accessible Fields and Tables for more information). Furthermore, if the Table has been marked as read only it will only contain columns that have also been marked as read only.

 

The Table returned is a representation of the table as in the server - the server does not perform a fetch on the Table first.

 

The rows are in same order as in the server.

 

This function is synchronous - that is it requests, waits and returns the Table from the server. During this time the browser will be unresponsive to user activity.

 

 

Example:

var table = $eb.getTable("TABLE1");

var column1value = table.COLUMN1().value;

table.setCurrentRow(2);

var column2Value = table.getColumn("COLUMN2").getValue();

var column2DisplayValue = table.COLUMN2().getDisplayValue();

var column3Row5value = table.getColumnValueOnRow("COLUMN5", 5);

 

 

Since:

V4.5

 

getTableFilteredByRows

 

Syntax:

$eb.getTableFilteredByRows(tablename, fromRow, numberOfRows, failureCallBack)

 

 

Description:

Retrieves a Table from the server, containing a specified number of rows from a given row id.

 

Params:

    tablename - string: the name of the Table to get from the server.

 

    fromRowint: the rowid to start from. Null denotes the first row of the table.

 

    numberOfRows - int: the maximum number of rows to return.

 

    failureCallBack(optional) – a function: a call back function can be provided which will be called in the case where there is a failure during communication with the server, or when the server itself cannot retrieve the Table. A textual representation of the error (if known) is passed in as a parameter.

 

Returns:

    A $eb.Table representing the Table on the server. Can be null or undefined (this usually denotes that there was an error communicating with the server or the server was unable to get the Table).

 

The Table must have been marked as accessible in the designer otherwise the method will return null (see Client Accessible Fields and Tables for more information). Furthermore, if the Table has been marked as read only it will only contain columns that have also been marked as read only.

 

The Table returned is a representation of the table as in the server - the server does not perform a fetch on the Table first.

 

The rows are in same order as in the server.

 

The parameters fromRow and numberOfRows can be used to limit the number of rows returned from the server so that the entire table data isn’t transmitted to the client. The rows returned will start with the row with the fromRow id and contain the specified number of rows or the number of rows left in the table if there are too few rows remaining to fulfil the requested number of rows. If the Table on the server has been sorted then the returned row ids may not be sequential.

 

This function is synchronous - that is it requests, waits and returns the Table from the server. During this time the browser will be unresponsive to user activity.

 

 

Example:

var table = $eb.getTableFilteredByRows("TABLE1", 4, 6);

var column1value = table.COLUMN1().value; // the value on the first row (rowid 4)

table.setCurrentRow(2); // there is no rowid 2 in the returned table in this example

table.COLUMN1() == undefined;

 

 

Since:

V4.5

 

getTables

 

Syntax:

$eb.getTables(tablenamearray,failureCallBack)

 

 

Description:

Retrieves the Tables with the given names from the server.

 

Params:

    tablenamearray - an array of strings: the names of the tables to get from the server.

 

    failureCallBack(optional) – a function: a call back function can be provided which will be called in the case where there is a failure during communication with the server, or when the server itself cannot retrieve the Table. A textual representation of the error (if known) is passed in as a parameter. An array of the field names that could not be retrieved will be passed (if not a communication error) as the second parameter.

 

Returns:

    A JavaScript object with a $eb.Table representing each requested Table, keyed by its name. Individual Tables requested but not found on the server are not present (undefined) in the returned object. Can return undefined, which usually denotes that there was an error communicating with the server.

 

Each Table must have been marked as accessible in the designer otherwise it will not be present in the returned object (see Client Accessible Fields and Tables for more information). Furthermore, if the Table has been marked as Read Only it will only contain columns that have also been marked as read only.

 

Each Table returned is a representation of the table as in the server - the server does not perform a fetch on the Table first.

 

The rows are in same order as in the server. All rows from each table are returned.

 

This function is synchronous - that is it requests, waits and returns the Table from the server. During this time the browser will be unresponsive to user activity.

 

 

Example:

var tables = $eb.getTables(["TABLE1","TABLE2"]);

var table1 = tables.TABLE1;

var table2 = tables.TABLE2;

var col1Value = tables.TABLE1.COL1().value;

 

 

Since:

V4.5

 

executeFunction

 

Syntax:

$eb.executeFunction(functionName, parameter, autorefresh, fullsubmit, failureCallBack, componentPrefix)

 

 

Description:

Executes the named Client Callable Function on the server.

 

Params:

    functionName – string: the name of the function for execute.

 

    parameter (optional) - a javascript object/value/array. This parameter will be passed into the named function on the server as its first parameter. It is your responsibility to ensure that the function accepts a parameter in the server-side script e.g. myfunction(param1){...}.

 

    autorefresh (optional)boolean (false by default): Before returning from this method, the system may refresh any control in the HTML that might have changed as a result of the function execution. Note that this may substantially alter the page, and variables pointing to data before this function was executed may now be out of date. It can also mean that the whole page has to be refreshed, (for example when changing the language of a form) and if this occurs current Javascript execution will be terminated immediately. It is strongly recommended that the Form be configured to use ajax communication when using the autorefresh feature.

 

    fullsubmit (optional) - boolean (false by default): By default there is no automatic synchronisation or validation between the client and the server as part of an executeFunction call. When you (for example) click on a normal Button with a configured on click event, the system transmits the current state of any input fields to the server which then validates and updates its field state accordingly. Setting this parameter to true means that the executeFunction call will perform this input->field synchronisation and validation before executing the function. Note that all the fields on the page are validated and if proven to be invalid (e.g. mandatory fields not filled in or they break the validation rules for the corresponding field) then the executeFunction will not run. It is strongly recommended that when setting this parameter to true that the autorefresh option is also set to true as the browser will then be updated with validation messages.

 

    failureCallBack (optional) – a function: a call back function can be provided which will be called in the case where there is a failure during communication with the server, or when the server itself cannot execute the requested function. A textual representation of the error (if known) is passed in as a parameter.

 

    componentPrefix (optional) –sets the component context on the server, if null is specified the form context is used. See getComponentPrefix().

 

 

Returns:

    Within the server-side function it is possible to return a value/object/array and this will be returned as a result of this method.

 

When executeFunction() is issued as a result of a jQuery event on a control within a Table Control or a Repeater Control, the current row of all parent tables on the server is set prior to executing the function. The event owner (accessed via server-side Javascript: “event.owner”) is also set to the owning control.

 

The Client Callable Function has complete access to the form and behaves in the same way as a normal script. Any functions defined in library scripts associated with the form are available within the called function, but are not available to the Client API directly and attempts to execute one will result in an error.

 

It’s important to note when passing objects from and to the server, only the data within that object is passed - methods and function are not.

 

This function is synchronous - that is it requests, waits for the result of the function execution from the server before returning to the calling code. During this time the browser will be unresponsive to user activity.

 

 

Example:

client side:

  var result = $eb.executeFunction("addition", [2,3]);

 

server side (defined in a Client Callable Function script associated with the form):

  function addition(params)

  {

    return params[0]+params[1];

  }

 

  function returnTheSameObjectAsReceived(params)

  {

    return params;

  }

 

client side:

  alert(result);  // this will display a popup with the result - 5

 

 

Since:

V4.5

 

executeFunctionAsynchronously

 

Syntax:

$eb.executeFunctionAsynchronously(successCallBack, failureCallBack, functionName, parameter, autorefresh, fullsubmit, componentPrefix)

 

 

Description:

Executes the named Client Callable Function on the server asynchronously.

 

Params:

    successCallBack – a function: called when the execution has been successful and a result has been returned from the server. The result is passed into the function at its first parameter.

 

    failureCallBack – a function: a call back function which will be called in the case where there is a failure during communication with the server, or when the server itself cannot execute the named function. A textual representation of the error (if known) is passed in as a parameter.

 

    functionName – string: the name of the function for execute.

 

    parameter (optional) - a javascript object/value/array. This parameter will be passed into the named function on the server as its first parameter. It is your responsibility to ensure that the function accepts a parameter in the server-side script e.g. myfunction(param1){...}.

 

    autorefresh (optional)boolean (false by default): Before returning from this method, the system may refresh any control in the HTML that might have changed as a result of the function execution. Note that this may substantially alter the page, and variables pointing to data before this function was executed may now be out of date. It can also mean that the whole page has to be refreshed, (for example when changing the language of a form) and if this occurs current Javascript execution will be terminated immediately. It is strongly recommended that the Form be configured to use ajax communication when using the autorefresh feature.

 

    fullsubmit (optional) - boolean (false by default): By default there is no automatic synchronisation or validation between the client and the server as part of an executeFunction call. When you (for example) click on a normal Button with a configured on click event, the system transmits the current state of any input fields to the server which then validates and updates its field state accordingly. Setting this parameter to true means that the executeFunctionAsynchronously call will perform this input->field synchronisation and validation before executing the function. Note that all the fields on the page are validated and if proven to be invalid (e.g. mandatory fields not filled in or they break the validation rules for the corresponding field) then the executeFunction will not run. It is strongly recommended that when setting this parameter to true that the autorefresh option is also set to true as the browser will then be updated with validation messages.

 

    componentPrefix (optional) –sets the component context on the server, if null is specified the form context is used. See getComponentPrefix().

 

Returns:

    Nothing (undefined). The supplied successCallBack function will be called with the value/array/object returned from the server as its parameter.

 

When executeFunctionAsynchronously() is issued as a result of a jQuery event on a control within a Table Control or a Repeater Control, the current row of all parent tables on the server is set prior to executing the function. The event owner (accessed via server-side Javascript: “event.owner”) is also set to the owning control.

 

The Client Callable Function has complete access to the form and behaves in the same way as a normal script. Any functions defined in library scripts associated with the form are available within the called function, but are not available to the Client API directly and attempts to execute one will result in an error.

 

It’s important to note when passing objects from and to the server, only the data within that object is passed - methods and function are not.

 

This method makes it calls to the server asynchronously. That means it makes a call to the server and immediately finishes. The user can continue to interact with the web page - it does not become 'frozen' as a non-synchronous call might. When the server eventually returns, the supplied call back function (successCallBack) will be executed with the result of the execution passed in as its first parameter. Should there be an error (either a communication to the server failure, or a failure on the server itself) then the specified failure call back function (failureCallBack) is called instead of the success call back.

 

 

Example:

client side:

   var successCallBack = function(data){ alert(data) };

   var failureCallBack = function(reason){ alert(reason) };

   $eb.executeFunctionAsynchronously(successCallBack, failureCallBack, "addition", [2,3]);

   // more code which is immediately executed – the results of the function execution are not waited for.

 

server side (defined in script: SCRIPT_WITH_FUNCTIONS):

    function addition(params)

    {

        return params[0]+params[1];

    }

 

    function returnTheSameObjectAsReceived(params)

    {

        return params;

    }

 

client side:

   alert(data)

    The call back function supplied is invoked, along with the data returned from the server as its first argument. An alert would pop up with 5 in it (the server-returned result of the addition). If there was an error, the failureCallBack would be called instead of the successCallBack, and an alert containing a reason for the failure (if available) will be shown.

 

 

Since:

V4.5

 

registerEventHandler

 

Syntax:

$eb.registerEventHandler(jqueryElement, eventName, eventHandler)

 

 

Description:

Registers a jQuery event. This function exists to address a problem that occurs in the following specific circumstances:

 

  • A jQuery event is registered using Javascript code i.e. it is not registered by configuring an event using HTML Element properties on a control.
  • The event is part of a component deployed into a form.
  • The code executed at the event will call this client API using $eb.xxx at some point e.g. to execute a function on the server.

 

In these circumstances, the system is unable to intercept the client API call and apply the component prefix. The symptoms of this problem can be: a client callable function configured on the server as part of a component is not found, fields or tables referred to using their component names are not found.

 

If you think that you are experiencing this problem, then the jQuery event should be registered using this function.

 

 

Params:

    jqueryElement – a jQuery element – typically obtained by using $(selector).

 

    eventName – the name of the jQuery event e.g. “click”.

 

    eventHandler – the function to be executed.

 

 

 

 

Example:

$eb.registerEventHandler(

      $("#id123"),

      "click",

      function() {$eb.executeFunction("func1");}

);

 

 

Since:

V4.5.4

 

Objects

Field

Syntax

new $eb.Field(fieldName, value, displayValue);

 

 

Description:

The Client API’s representation of a Field, consisting of a name, a value and a display value.

 

Params:

    fieldNamestring: the name of the field.

 

    value – a Javascript representation of the value of this field.

 

    displayValue (optional) – string: A textual representation of the value of the field, with any default formatting applied.

 

When constructing a field, care must be taken to use a value which is compatible with the form field that it represents on the server - see setField for a detailed break down on the supported representations for each field type. It should be noted that the Client API cannot create new Fields on the server, it can only update existing ones.

 

When a field has been constructed in response to a $eb.getField() call then the value will have a different representation depending on the type of Field.

 

 

Example:

var field = new $eb.Field("FIELD1", "This represents a text field", "This represents a text field");

alert(field.elementName == field.getElementName()); // shows true

alert(field.value == field.getValue()); // shows true

alert(field.displayValue == field.getDisplayValue()); // shows true

 

 

Since:

V4.5

 

getElementName

Syntax

field.getElementValue()

 

 

Description:

Returns:

    The name of the field.

 

This is equivalent to field.elementValue.

 

 

Example:

var field = new $eb.Field("FIELD1", "This represents a text field", "This represents a text field");

field.elementName; // returns: FIELD1

field.getElementName(); // returns: FIELD1

 

 

Since:

V4.5

 

getValue

Syntax

field.getValue()

 

 

Description:

Returns:

    The value of the field.

 

When a field has been constructed in response to a $eb.getField call then the value will have a different representation depending on the type of Field.

 

Field Type

Javascript object

Boolean

a boolean

Character

a string

Integer

a number

Numeric

a number

Currency

a number

Date

a number representing the number of milliseconds since 1st January 1970, where the time portion is initially set to 00:00

Datetime

a number representing the number of milliseconds since 1st January 1970

Time

a number representing the number of milliseconds since midnight

Object

a Javascript representation of the object. Note that this object will have been sent via a JSON representation thus contains publicly available data of the server-side object (i.e. no methods/functions)

 

This is equivalent to field.value.

 

 

Example:

var field = new $eb.Field("FIELD1", "This represents a text field", "This represents a text field");

field.value; // returns: This represents a text field

field.getValue(); // returns: This represents a text field

 

 

Since:

V4.5

 

getDisplayValue

Syntax

field.getDisplayValue()

 

 

Description:

Returns:

    The display value of the field.

 

This is equivalent to field.displayValue.

 

When a $eb.Field has been constructed in response to a $eb.getField call, the display value is a textual representation of the value of the field, with any default formatting applied.

 

When the Field on the server is of type Object, the display value is a serialized value for the object which can be used to pass the object across mediums that only support character data e.g. a URL, as part of an XML document.

 

The default formatting for date fields is specified in parameter Ufs.dateFormat in file UFSSetup.properties.

 

When the Field on the server is associated with a list, the display value is the value displayed to the user. This is in contrast to method getValue() which provides the list return value as opposed to the list display value e.g. a static list entry might have a return value "M" and a display value "Male", in which case this method will return "Male" and method getValue() will return "M".

 

 

Example:

var field = new $eb.Field("FIELD1", "This represents a text field", "This represents a text field");

field.displayValue; // returns: This represents a text field

field.getDisplayValue(); // returns: This represents a text field

 

 

Since:

V4.5

 

setValue

Syntax

field.setValue(value)

 

 

Description:

Sets the value of the field.

 

Params:

    value – a JavaScript object, value or array. Care must be taken to use a value which is compatible with the Field that it represents on the server:

 

Field Type

Allowable JavaScript representations

Boolean

boolean: any value

string: true values are "true", "Y", "Yes", "1", false values are "false", "N", "No", "0"

number: 1 is true, 0 is false

Character

string: any value

boolean: true becomes "Y", false becomes "N"

number: any number

Integer

Number

Currency

string: any numeric value

number: any value

Date

date: JavaScript Date objects can be used

string: must be in the format specified in parameter Ufs.dateFormat in file UFSSetup.properties. Note that these strings do not contain timezone information and therefore there may be differences between the given and the created value.

number: represents the number of milliseconds since 1st January 1970

Datetime

date: JavaScript Date objects can be used

string: Date followed by a space then Time. Date must be in the format specified in parameter Ufs.dateFormat in file UFSSetup.properties. Time is in the format hh:mm:ss.ttt. Note that as a string does not contain timezone information and therefore there may be differences between the given and the created value.

number: represents the number of milliseconds since 1st January 1970

Time

date: JavaScript Date objects can be used

string: must be in the format hh:mm:ss.ttt. Note that as a string does not contain timezone information there may be differences between the given and the created value.

number: represents the number of milliseconds since midnight

Object

a JavaScript object. Note that this object will have been sent via a JSON representation thus contains publicly available data of the object (i.e. no methods/functions). Basic JavaScript arrays and objects are sent as-is and will be set as such.

 

This is equivalent to field.value = value;

 

This function only updates the field locally - to send the changes to the server the setField, setFieldValue and setFields functions should be used.

 

 

Example:

dateField.setValue(new Date().getTime());

dateField.value = new Date().getTime();

 

 

Since:

V4.5

 

setDisplayValue

Syntax

field.setDisplayValue(displayValue)

 

 

Description:

Sets the DisplayValue of the field.

 

Params:

    displayValue – string: the new displayValue of the field

 

This is equivalent to field.displayValue = “Some Text”;

 

The display value is not sent to the server as part of a setField, setFieldValue or setFields function call – the server is responsible for generating a display value based on the current value of its field.

 

 

Example:

dateField.setDisplayValue(“The current time is 12:00”);

dateField.displayValue = “The current time is 12:00”;

 

 

Since:

V4.5

 

Table

 

Description:

The Client APIs representation of a Table.

 

Unlike a $eb.Field a $eb.Table can only be created by the Client API itself in response to either a getTable or getTables function call and the Client API is unable to send them to the server.

 

 

Since:

V4.5

 

getElementName

Syntax

table.getElementName()

 

 

Description:

Returns:

    The name of the table.

 

 

Example:

$eb.getTable(“TABLE1”).getElementName();

 

 

Since:

V4.5

 

 

getCurrentRow

Syntax

table.getCurrentRow()

 

 

Description:

Returns:

    The current row number of the table.

 

The current row represents an important concept - a current row exists for all tables that are not empty.

 

All references to the table’s columns and their values that do not explicitly specify a row number are interpreted as referring to the corresponding table cell for the column on the current row.

 

For example, in the following line of code, values for the ORDER_VAT and ORDER_VALUE columns are obtained from the current row:

    val order.ORDER_VAT().value = orders.ORDER_VALUE().value * vatRate;

 

The current row is set by the system while traversing table rows using a TableRowIterator, the current row is set each time its next or previous function is invoked.

 

When all rows have been processed by the TableRowIterator, the current row is returned to its original value.

 

If all rows are not processed by the TableRowIterator, the current row remains set to the last row iterated to.

 

 

Example:

$eb.getTable(“TABLE1”).getCurrentRow();

 

 

Since:

V4.5

 

setCurrentRow

Syntax

table.setCurrentRow(rowid)

 

 

Description:

Sets the current row of the table

 

Params:

      rowid – number: The new current row for the table.

 

See the getCurrentRow function for details about the effect of setting the current row on a table.

 

 

Example:

$eb.getTable(“TABLE1”).setCurrentRow(12);

 

 

Since:

V4.5

 

getRowCount

Syntax

table.getRowCount()

 

 

Description:

Returns:

    The number of rows in the table.

 

 

Example:

var rows = $eb.getTable(“TABLE1”).getRowCount();

 

 

Since:

V4.5

 

getLastRowId

Syntax

table.getLastRowId

 

 

Description:

Returns:

    The id of the last row in the $eb.table.

 

If the table was fetched using the getTableFilteredByRows function, the last row id will be the id of the final table fetched from the server as a result of that request. This id could then be used to obtain more rows from the server starting with the id of last row.

 

 

Example:

var tableData = $eb.getTableFilteredByRows(“TABLE1”, 0, 10);

var moreTableData = $eb.getTableFilteredByRows(“TABLE1”, tableData.getLastRowId(), 11); // return the last row id from the first getTableFilteredByRows call plus an additional 10 rows.

 

 

Since:

V4.5

 

 

getRows

Syntax

table.getRows()

 

 

Description:

Returns:

    A TableRowIterator that can be used to traverse all the rows in the table.

 

 

Example:

var table = $eb.getTable("TABLE1");

var iter = table.getRows();

while(iter.next())

{

    alert(table.ORDER_VALUE().value * vatRate);

}

 

 

Since:

V4.5

 

getColumn

Syntax

table.getColumn(columnName)

 

 

Description:

Gets the TableColumn at the current row of the table.

 

Returns:

    The specified TableColumn at the current row, or null if the column does not exist.

 

Note there is a shorthand way of getting the column, which is to use the column name as if it was a function: table.columnName();

 

 

Example:

var table = $eb.getTable("TABLE1");

var col = table.getColumn("ONE");

col == table.ONE(); // instead of calling getColumn() we can use the column name as if it was a function on the table.

 

 

Since:

V4.5

 

getColumns

Syntax

table.getColumns()

 

 

Description:

Returns:

    An array TableColumns representing all of the columns in the table.

 

 

Example:

var ORDERS = $eb.getTable("ORDERS");

var cols = ORDERS.getColumns();

for each (var col in cols) // note 'for each' will not work in IE 6, 7 & 8

{

    log(col.elementName + ": " + col.value + ": " + col.displayValue);

}

 

 

Since:

V4.5

 

 getColumnValueOnRow

Syntax

table.getColumnValueOnRow(columnName, row)

 

 

Description:

Gets the current value in the specified column name on the given row.

 

Params:

    columnName – string: The new current row for the table.

 

    row – number: the row to look at (0-indexed)

 

Returns:

    A JavaScript object representing the value of the table cell at the specified column and row. Can be null or undefined.

 

The returned value has a different representation depending on the type of the Field on the server:

 

Field Type

Javascript object

Boolean

a boolean

Character

a string

Integer

a number

Numeric

a number

Currency

a number

Date

a number representing the number of milliseconds since 1st January 1970, where the time portion is initially set to 00:00

Datetime

a number representing the number of milliseconds since 1st January 1970

Time

a number representing the number of milliseconds since midnight

Object

a Javascript representation of the object. Note that this object will have been sent via a JSON representation thus contains publicly available data of the server-side object (i.e. no methods/functions)

 

 

 

 

Example:

var value = $eb.getTable("TABLE1").getColumnValueOnRow("ORDER_VALUE", 5);

 

 

Since:

V4.5

 

getColumnDisplayValueOnRow

Syntax

table.getColumnValueOnRow(columnName, row)

 

 

Description:

Gets the current display value in the specified column name on the given row.

 

Params:

    columnName – string: The new current row for the table.

 

    row – number: the row to look at (0-indexed)

 

Returns:

    A string representing the value of the column at that specified row. Can be null or undefined.

 

 

Example:

var value = $eb.getTable("TABLE1").getColumnValueOnRow("ORDER_VALUE", 5);

 

 

Since:

V4.5

 

findRow

Syntax

table.findRow(columnName, value)

 

 

Description:

Finds the first row number with the specified column value.

 

Params:

    columnName – string: The name of the columns whose value we are looking for

 

    value – the value of the table column, should be the same type as the underlying column object.

 

Returns:

    The first row number with the specified column value, or -1 if no match is found.

 

 

Example:

var ORDERS = $eb.getTable(“ORDERS”);

var row = ORDERS.findRow(“ORDER_ID”, “123123”);

if (row != -1)

{

    ORDERS.setCurrentRow(row);

}

 

 

Since:

V4.5

 

 

TableColumn

Description:

The Client APIs representation of the Field value of a Table’s column at a specific row. Like a $eb.Field a TableColumn contains a value and a display value.

 

A TableColumn is created by the Client API as part calls to the getColumn and getColumns functions and when the equivalent shorthand notation is used (the column name can be used as if it was a function – see the getColumn method for more information).

 

 

Example:

var table = $eb.getTable(“TABLE1”):

 

var tableColumn = table.getColumn(“ONE”); // gets the column at the tables current row (the first row)

var value = tableColumn.getValue(); // this is the value of column ‘ONE’ at the current row.

 

table.setCurrentRow(5); // change the current row

 

var tableColumn3 = table.ONE() // gets the table column at the table’s current row (the 5th row).

var value3 = table.ONE().value // this is equivalent to table.getColumn(“ONE”).getValue();

 

 

Since:

V4.5

 

getElementName

Syntax

tablecolumn.getElementName()

 

 

Description:

Returns:

    The name of the table column.

 

 

Example:

var columnName = $eb.getTable(“TABLE1”).getColumn(“ONE”).getElementName();

 

 

Since:

V4.5

 

getValue

Syntax:

tablecolumn.getValue()

 

 

Description:

Gets the value of the table column.

 

Returns:

    The value of the table column. This returned value has a different representation depending on the type of the Column on the server:

 

Field Type

Javascript object

Boolean

a Boolean

Character

a string

Integer

a number

Numeric

a number

Currency

a number

Date

a number representing the number of milliseconds since 1st January 1970, where the time portion is initially set to 00:00

Datetime

a number representing the number of milliseconds since 1st January 1970

Time

a number representing the number of milliseconds since midnight

Object

a Javascript representation of the object. Note that this object will have been sent via a JSON representation thus contains publicly available data of the server-side object (i.e. no methods/functions)

 

This is equivalent to tablecolumn.value;

 

 

Example:

var table = $eb.getTable(“TABLE1”);

 

var d1 = new Date(table.DATE_FIELD().value);

var d2 = new Date(table.getColumn(“DATE_FIELD”).getValue();

 

// d1 is the same as d2.

 

 

Since:

V4.5

 

getDisplayValue

Syntax

tablecolumn.getDisplayValue()

 

 

Description:

Returns:

    The display value of the table column.

 

The display value is a textual representation of the value of the table column, with any default formatting applied.

 

When the Table Column on the server is of type Object, the display value is a serialized value for the object which can be used to pass the object across mediums that only support character data e.g. a URL, as part of an XML document.

 

The default formatting for dates is specified in parameter Ufs.dateFormat in file UFSSetup.properties.

 

When the Table Column on the server is associated with a list, the display value is the value displayed to the user. This is in contrast to function getValue which provides the list return value as opposed to the list display value e.g. a static list entry might have a return value "M" and a display value "Male", in which case this function will return "Male" and tablecolumn.getValue() will return "M".

 

This function is equivalent to tablecolumn.displayValue.

 

 

Example:

var tablecolumn = $eb.getTable(“TABLE1”).ONE();

 

if(tablecolumn.displayValue == tablecolumn.getDisplayValue())

{

    // is always true.

}

 

 

Since:

V4.5

 

TableRowIterator

Syntax

new $eb.TableRowIterator(table);

 

 

Description:

The table row iterator object, used to navigate through the rows of a table

 

Params:

    table – a $eb.Table object.

 

Can be constructed manually by passing in the $eb.Table to iterate over, or by calling getRows on it.

 

If the underlying table's rows are changed (either their number or their ordering) after this has been created, then unexpected behaviour will be experienced by further calls to this object and it is recommended that a new TableRowIterator is be obtained from the table.

 

 

Example:

var rows = $eb.getTable(“TABLE1”).getRows();

var samerows = new $eb.TableRowIterator($eb.getTable(“TABLE1”));

 

 

Since:

V4.5

 

next

Syntax

tablerowiterator.next()

 

 

Description:

Sets the table's current row to point to the next table row.

 

Returns:

    false when all rows have been processed, true otherwise.

 

All table rows referenced by an iterator can be processed within a loop within while (iter.next()) as shown in the example below.

 

When all rows have been processed by repeated calls to next(), this method returns false and the current row is reset to its original value i.e. the current row number before any methods on this TableRowIterator were invoked. Further calls to the previous function (see below) have no effect will return false.

 

If all rows are not processed (this method does not return false) the current row is not reset.

 

 

Example:

var table = $eb.getTable("TABLE1");

var iter = table.getRows();

while(iter.next())

{

    alert(table.ORDER_VALUE().value * vatRate);

}

 

 

Since:

V4.5

 

previous

Syntax

tablerowiterator.previous()

 

 

Description:

Sets the table's current row to point to the previous table row.

 

Returns:

    false when there are no more previous rows to go back to or if the next function has processed all of the rows, otherwise true.

 

The current row can be positioned to the last row using the last function.

 

The current row of the table is never restored by this method - it must be done by the caller if required.

 

 

Example:

var table = $eb.getTable("TABLE1");

var rows = table.getRows();

rows.last(); // move to the last row in the table

while(iter.previous()) // moves through each row in the table in reverse order

{

    alert(table.ORDER_VALUE().value * vatRate);

}

 

 

Since:

V4.5

 

first

Syntax

tablerowiterator.first()

 

 

Description:

Sets the table's current row to point to the first row.

 

Returns:

    when no rows exist or if the next function has processed all of the rows, otherwise true.

 

 

Example:

var table = $eb.getTable("TABLE1");

var rows = table.getRows();

if(rows.first()) // move to the first row in the table

{

    alert(table.ORDER_VALUE().value * vatRate); // pops up information about the first row if one exists

}

 

 

Since:

V4.5

 

last

Syntax

tablerowiterator.last()

 

 

Description:

Sets the table's current row to point to the last row.

 

Returns:

    when no rows exist or if the next function has processed all of the rows, otherwise true.

 

 

Example:

var table = $eb.getTable("TABLE1");

var rows = table.getRows();

if(rows.last()) // move to the last row in the table

{

    alert(table.ORDER_VALUE().value * vatRate); // pops up information about the last row if one exists

}

 

 

Since:

V4.5

 

getSize

Syntax

tablerowiterator.getSize()

 

 

Description:

Returns:

    The number of rows within the iterator.

 

 

Example:

var table = $eb.getTable("TABLE1");

var rows = table.getRows();

alert(rows.getSize()) // pops up the number of rows in the iterator.

 

 

Since:

V4.5