The JavaScript Libraries

Composer has several JavaScript libraries. These are exposed in the Advanced Mode of the Structure Panel ("<Form> -> Composer Framework ->")

 

•formBridge.js (included in PDF forms)

•htmlFormBridge.js

•sfmSupport.js
which supports

osfc.js

▪This defines the methods in the Composer public API.

•json.js
for JSON support.

 

The Public API

Documentation

You can access the API documentation at anytime in Composer, through the Online Documentation dropdown at the top right-hand corner of the Composer User Interface.

 

OnlineDocSelectxcf

Select the "Javascript Documentation" option.

 

This opens a webpage in a new tab in your browser, listing the methods in the public API. (Avoka does have a set of internal APIs, but these are subject to frequent change. We strongly recommend not using these.)

 

Calls

The sfc calls are designed to work both for HTML and PDF. This is the reason sfc framework originally came into being.

 

Most of the sfc methods are static: you just call the method, specify the parameters and the method returns some value. Some typical examples:

 

•sfc.getDaysDifference(startDate, endDate)

•sfc.convertToString(value)

•sfc.formatDate(dateObject, dateFormat)

•sfc.getRawValue(noderef)

 

Others are dynamic, such as the sfcInstanceManager which operates on a delegate (i.e. an event that is being listened to). You also can make use of Composer's Business Rules widgets to listen to events.

 

However, Composer provides "parameters" which are convenient constructs to refer to form objects with a minimum of coding.

 

Using JavaScript's Built-in Functions

You can use the standard JavaScript functions, though you should make preferentially use of any sfc method instead of the standard JavaScript method as a general rule. But there are far more JavaScript functions for you to draw on.

 

There are many references for these:

 

•https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects

•http://www.w3schools.com/jsref/jsref_obj_global.asp

•http://www.tutorialspoint.com/javascript/javascript_builtin_functions.htm

 

For example:

 

var n = 12345;

var x = n.toExponential(); // x will be 1.2345e+4

 

Parameters

In the Script Editor

The above examples of sfc static methods calls have a number of parameters, such as "startDate", "endDate" and so forth. Composer' Script Editor can conveniently refer to fields on the form for these calls.

SimpleScriptDemo

 

Refereing to form elements becomes a simple matter of point-and-shoot to elements in the Structure Panel on the bottom-left of the Script Editor. The field is referenced in the JavaScript in the scripting text field by its field name in curly brackets. The Dependencies panel in the dialog gives the Parameter Name (the name within the curly brackets), the data type (about which, more later) and the Field Reference (which is the field's position in the structure, relative to the field for which the script is being created).

 

So, we could use an sfc call on such a parameter:

 

sfc.convertToString({Amount1})

 

You should not merely type the parameter name into some curly brackets in the script: the editor works best if you insert your cursor into the point of the JavaScript and double-click on the parameter listed in "Dependencies".

 

A useful byproduct of using these Script Editor parameters is that Composer is able to keep track of form elements when they are moved within the form, so that you do not have to re-point to these elements in their new locations.

 

Edit Parameter Data

Clicking on the Edit icon in the right-hand column of the Dependencies panel (see immediately above) brings up the Edit Parameter Data dialog where you can:

 

•edit the parameter name (i.e. the name that goes into the curly brackets

•Choose the parameter type via a dropdown:

ostring

oBoolean

onumber

oIs Selected

onode

oraw value

oUID

•Trigger Type

oStatic

oDynamic

 

We will discuss the Trigger Type further in Optimizing Performance.

 

Parameter Types

Parameter Type

Explanation

RawValue

Always returns a String representing the "raw" value of an object. Does no conversion, so it returns dates, booleans and other values as the underlying string that the value is stored as. Uninitialized values may return a null.

String

Always returns a string. Nulls will be converted to empty strings. (This gives you one less thing to "worry" about in your calculations - you don't have to test for both null and empty string.)

Number

Always returns a number. It will do its best to convert any parameter to a number. If it cannot convert it, it will return zero.

Boolean

Takes anything that resembles a true value, and return the boolean value "true". This includes "1", "T", "true", "Y", "yes", "on", and is case insensitive. Otherwise it returns the boolean value "false". Blank or Null is false.

IsSelected

Only used for checkboxes and radio buttons. Returns Boolean true if the checkbox/radio-button is selected.

Node

Returns the internal node object that represents an object. If you point at anything in a repeat from outside the repeat, this returns null (because it's really multiple nodes). If you refer to any object inside a repeat from within the same repeat, it returns the node. Nodes can be passed to internal SFC functions to perform operations on the object itself.

UID

Provides a reference to a node. Similar to a node, but can be used to reference an object in a particular row within a repeat.

 

Node Reference

There are three ways to refer to a node (or "form element", the terminology we have been using consistently so far):

 

•The Script Editor parameter

•the relative path (as seen in the "Field Reference" column value in the Dependencies panel)

•the Full Path (or "Absolute Path" from the form's root, usually by default "$record")

•The field's UID (Unique Identifier)

 

Obtaining the Fullpath

If you do not avail yourself of the convenience of this point-and-shoot construct, you will have to refer to the form field using the Data Model tab by double-clicking on the field in either the left- or right-hand panels and copying the "Fullpath" from the Data Model Binding panel in the properties dialog.

 

For example

•$record.GettingStarted.FirstName.data

 

Obtaining the UID

You could get this from "Edit Properties -> Overview tab -> Basic Information panel -> field UID"

 

For example:

•/GettingStarted/_outerArea/_contentArea/FirstName/data

 

Or you can use the sfc call:

•sfc.convertToUid(noderef)