Server-Side Javascript Quick Start Guide

API variables added to Javascript 1

Linkage to form. 2

Using code-assist (Intellisense) 2

Working with Fields 2

Working with Tables 3

Working with Controls 4

Working with Resources 4

Issuing Error and Warning Messages 5

This document provides a quick introduction to server-side programming with Javascript and describes how to work with the Ebase API to access form elements such as fields, tables, controls etc. It does not contain any specific information on Javascript as a programming language or Javascript syntax – see any good Javascript reference for this. Also see the Javascript Developer’s Guide which provides more detailed information.

Events and Scripts

Server-side programming is achieved by associating scripts with events. Ebase forms have an event model (see Ebase events) that support a number of different events e.g. click on a button.

Ebase API

This API provides access to all elements within an executing Ebase form, integration service or workflow job: this includes fields, tables, pages, controls, external resources etc. In addition, it also provides access to browser client and session data plus many additional programming facilities e.g. transactions, security, files, Velocity templates etc.

Click here for the API javadoc.

API variables added to Javascript

The API is provided to Javascript scripts via a number of variables which are added automatically to each script:

Variable Name	Description
form	This acts as the core object for the form API and provides methods to access all other form elements. It also provides a number of methods to perform user actions such as: go to page, call form, call URL, generate PDF, upload file etc.
event	Access to the controlling event e.g. Button Control on-click event, before page event
fields	Access to all fields in the form or integration service, or process attributes in a workflow process
tables	Access to all tables in the form, integration service or workflow process
pages	Access to all pages (only applies to forms)
controls	Access to all controls on all pages (only applies to forms)
resources	Access to all resources within the business view of the form, integration service or workflow process
texts	Access to all local texts plus and linked Texts entities
components	Access to all elements for a deployed component – this supports changing the context so that elements are accessed as if from a specific deployed component e.g. to load data from a table defined within a component.
system	Access to many additional system services: includes system variables, transactions, sequences, security etc
client	Access to information and methods pertaining to the browser client and session

Access to individual fields, tables, controls, resources, pages is via the individual element name (see examples below).

Linkage to form

Each script is linked to a form and this linkage is shown on the toolbar at the top of the editor. The linked form determines the list of available fields, tables, controls etc shown using code-assist features. Usually, this will show the correct form, but occasionally it may need to be changed.

Using code-assist (Intellisense)

Code-assist is activated in the Javascript Editor via Ctrl+Space. It will also display automatically when a period (.) is entered after a variable or method call.

The code-assist feature is extremely useful for showing lists of form fields, tables, controls etc and showing available methods and properties. However, Javascript is a language that supports dynamic types and it isn’t always possible to know accurately which type a variable or expression resolves to. For this reason, the methods and properties shown by the code-assist feature should not be interpreted as the limit of what is available. As a programmer, you may know that a certain variable is of a certain type and therefore you can invoke any methods applicable for that type.

Working with Fields

Getting a field value:

// get the value of the Requestor field

var val = fields.Requestor.value;

// computation based on value of the GROSS and NET fields

var margin = fields.GROSS.value – fields.NET.value;

Setting a field value:

fields.Department.value = "Finance";

fields.N1.value = 123.5;

fields.requestId = system.sequenceManager.sequence("REQUESTS");

The value property returns a (Java) Object when read, and accepts a variety of different Object types when set. The object types vary according to the field type – see the Field getValue() and setValue() method documentation for details. For character and numeric types, any type conversions usually occur automatically and work as expected. Fields of type DATE, TIME and DATETIME are a bit different and can be used in conjunction with the Javascript Date object as shown below:

fields.TodaysDate.value = new Date();

fields.CurrentTime.value = new Date();

// add a day to a date

var d1 = new Date(fields.D1.value);

d1.setDate(d1.getDate() + 1);

fields.D1.value = d1;

Click here for more details on how different form field types can be manipulated with Javascript.

Fields also have a displayValue property. This can be useful for fields of type DATE, TIME and DATETIME where the Java object returned with the value property is not something that can be displayed e.g.

var d1 = fields.OrderDate.value; // returns the date as the number of milliseconds since 1^st Jan 1970

var d2 = fields.OrderDate.displayValue; // returns a displayable date with local formatting e.g. 25/12/2012, 12/25/2012, 25.12.2012 etc

You can also use the DateServices helper class to format a date.

There is also a stringValue property which should be used when passing a field value to a called form, a called Integration Service or to a workflow job. The value of all form field types can be passed using this property including fields of type Object.

// calling a form passing an object field

var parms = {};

parms.objParm1 = fields.OBJ1.stringValue;

form.callForm("Form1", parms);

// opening a workflow job passing an object field

var parms = {};

parms.objParm1 = fields.OBJ1.stringValue;

system.workflow.openJob("TestProcess", parms);

Working with Tables

Loading a table via its backing resource:

tables.Requests.fetchTable();

Getting and setting column values:

Each table holds a current row number internally. When a reference is made to a column, this always means the column on the current row. Click here for more info on the table current row concept.

Columns are referred to using the column name (minus the table prefix), and values are get/set in the same way as for fields (TableColumn extends Field):

tables.OrderItems.item_id.value = ++itemNo;

tables.OrderItems.item_amount.value = fields.Amount.value;

var d1 = tables.Requests.RequestDate.value;

Looping through table rows:

var rows = tables.Requests.rows;

// rows.next() iterates through all table rows, changing the table’s current row as it goes

while ( rows.next() )

{

fields.Total.value += tables.Requests.Amount.value;

}

If the iteration through all rows completes, the current row is reset to the value it held when the row iterator was created. This is because the current row may have been set by a user action e.g. the user has clicked on a button or link on a certain table row within a Table Control. If the iteration through the rows does not complete (i.e. a break or return statement is used), the current row remains set with its value at the break point.

Inserting data into a table:

// insertRow() sets the current row to the inserted row

tables.ExpenseItems.insertRow();

tables.ExpenseItems.ItemId.value = ++itemNo;

tables.ExpenseItems.Type.value = "Travel";

These examples illustrate using the table’s current row to manipulate table data. Note that this can also be done by using explicit row numbers.

Working with Controls

Almost all of the properties that can be configured for a control can be changed dynamically using the appropriate property name. For information on the available properties, see the documentation displayed with the code-assist using the Javascript Editor; or in the Form Editor click on the Help icon in the Properties View when a control’s properties are displayed. For some controls (e.g. Table Control, second example below), the properties are organised into sub-groups. As well as properties, controls also have a number of methods such as show(), hide(), requestFocus() etc.

controls.Button1.backgroundColor = "Yellow";

controls.Table1.columnHeaderStyleProperties.borderWidth = "3px";

controls.Panel5.hide();

fields.Name.fieldControl.requestFocus();

Controls can also be found using their Modifiers property:

for each (var ctrl in pages.PAGE1.getControlsByModifier("FIN")

{

if (!system.securityManager.hasRole("AUDIT"))

{

ctrl.hide();

}

Note the for each in syntax used above. This syntax (not commonly implemented with client-side Javascript) is very useful for iterating through arrays returned using the Ebase API and for iterating through Javascript native arrays and objects.

Accessing control text properties

All control text properties are represented by a Text object, which has properties including a text property.

e.g. to set a text property:

controls.Button1.buttonText.text = "New text";

controls.Text1.text.text = "Hello";

This represents a difference from the FPL programming language which does not have this additional Text object.

Working with Resources

All resources in a form’s Resources View can be accessed using the resources variable:

resources.Requests.update();

resources.Email1.sendmail();

resources.Hr_Get_Employee_Details_Ws.call();

Issuing Error and Warning Messages

Error and warning messages can be added directly to a specific control or page (page messages are shown at the bottom of a page):

pages.Page1.addErrorMessage("Mandatory fields are required..");

controls.FieldControl1.addWarningMessage("This is a warning message..");

Alternatively, it is often more convenient to refer to the event owner (the event owner is the control or a page to which the script is attached e.g. a Button Control for a button click event):

event.owner.addErrorMessage("Your input is invalid..");

event.owner.addWarningMessage("Additional charges apply for this service..");

You can also choose whether processing should stop immediately so that the message can be displayed to the user. By default processing stops for error messages and continues for warning messages, but this behaviour can be overridden:

event.owner.addErrorMessage("First error message..", false);

event.owner.addErrorMessage("Second error message..", false);

If multiple error messages are accumulated in this way, processing can be explicitly stopped a some later point using:

event.stopExecution();

For example this might be necessary in the scenario where the user has clicked on a commit button and error messages have been issued. Then the requirement is to display the messages to the user, but not to continue with the rest of the commit processing.