Server-side Javascript Quick Start Guide

Verj.io API 1

API variables added to Javascript 1

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

Introduction

This document provides a quick introduction to server-side programming with Javascript and describes how to work with the Verj.io. It does not contain any specific information on Javascript as a programming language or Javascript syntax – see any good Javascript reference for this.

The Javascript Developer’s Guide provides more detailed information.

Events and Scripts

Server-side programming is done by associating Scripts with Server-side Events. Verj.io has an event model that supports a number of different events e.g. click on a button.

Verj.io API

This API provides access to all elements within a running Form, Application Layout, Integration Service or Workflow Job: this includes Fields, Tables, Pages, Controls and Resources. It also provides access to browser client and session data plus many additional programming facilities e.g. transactions, security, files, Velocity templates etc.

For a full list of variables that are provided by the API, see the Javascript Developer’s Guide.

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. See Scripts for more information.

Working with Fields

This uses the fields variable from the Javascript API.

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

This uses the tables variable from the Javascript API.

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

This uses the controls variable from the Javascript API.

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 Verj.io 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

This uses the resources variable from the Javascript API.

resources.Requests.update();

resources.Email1.sendmail();

resources.Hr_Get_Employee_Details_Ws.call();

Issuing Error and Warning Messages

This uses the event variable from the Javascript API.

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.