Server-Side Javascript Quick Start Guide
API
variables added to Javascript
Using
code-assist (Intellisense)
Issuing
Error and Warning Messages
See also: Javscript Scripting Menu, Javascript Developer’s Guide, Javascript Editor, API Javadoc
This document provides a quick introduction to server-side programming with Javascript and describes how to work with the Verj.io 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.
Server-side programming is achieved by associating scripts with events. Verj.io forms have an event model (see Verj.io events) that support a number of different events e.g. click on a button.
This API provides access to all elements within an executing Verj.io 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.
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).
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.
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.
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 1st 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);
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.
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.
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();
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.