Client API Reference
See Also: Client API Guide
|
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 |
|
Syntax: |
|||||||||||||||||||||
|
|
|
||||||||||||||||||||
|
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:
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 |
|
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:
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 |
|
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:
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 |
|
Syntax: |
|||||||||||||||||
|
|
|
||||||||||||||||
|
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:
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 |
|
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:
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 |
|
Syntax: |
|||||||||||||||||
|
|
|
||||||||||||||||
|
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:
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 |
|
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 |
|
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. fromRow – int: 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 |
|
Syntax: |
|
|
|
|
|
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 |
|
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 |
|
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 |
|
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:
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 |
|
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: fieldName
– string: 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 |
|
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 |
|
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.
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 |
|
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 |
|
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:
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 |
|
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 |
|
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 |
|
Syntax |
table.getElementName() |
|
|
|
|
Description: |
Returns: The name of the table. |
|
|
|
|
Example: |
$eb.getTable(“TABLE1”).getElementName(); |
|
|
|
|
Since: |
V4.5 |
|
Syntax |
table.getCurrentRow() |
|
|
|
|
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 |
|
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 |
|
Syntax |
table.getRowCount() |
|
|
|
|
Description: |
Returns: The number of rows in the table. |
|
|
|
|
Example: |
var rows = $eb.getTable(“TABLE1”).getRowCount(); |
|
|
|
|
Since: |
V4.5 |
|
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 |
|
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 |
|
Syntax |
table.getColumn(columnName) |
|
|
|
|
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 |
|
Syntax |
table.getColumns() |
|
|
|
|
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 |
|
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:
|
||||||||||||||||||||
|
|
|
||||||||||||||||||||
|
Example: |
var value = $eb.getTable("TABLE1").getColumnValueOnRow("ORDER_VALUE", 5); |
||||||||||||||||||||
|
|
|
||||||||||||||||||||
|
Since: |
V4.5 |
|
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 |
|
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 |
|
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 |
|
Syntax |
tablecolumn.getElementName() |
|
|
|
|
Description: |
Returns: The name of the table column. |
|
|
|
|
Example: |
var columnName = $eb.getTable(“TABLE1”).getColumn(“ONE”).getElementName(); |
|
|
|
|
Since: |
V4.5 |
|
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:
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |