Advanced Scripting

   Composer This topic is related to Transact Composer.  |   Form Builder |  v4.3 & Higher   This feature is related to v4.3 and higher.

JavaScript in Composer

Composer uses JavaScript as its scripting language. The only differences are some Composer-related libraries which contain Composer classes to, for example, reference fields in a Composer form or for other Composer integrations.
This section of the Guide focuses on form input scripting. Elsewhere we will cover the XML code used to tweak the format the form's output for some special purpose (such as to accommodate some integration point with the Enterprise's backend).

Syntax

The syntax for Composer's scripts is that of JavaScript. JavaScript is maintained by the Mozilla Foundation. Here are the canonical references:
{+}https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide+{+}https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference+
Other authoritative references are:
{+}http://www.w3schools.com/js/js_syntax.asp+{+}http://www.w3schools.com/jsref/default.asp+{+}http://www.tutorialspoint.com/javascript/javascript_syntax.htm+{+}http://javascript.info+{+}http://www.java.com/en/download/faq/java_javascript.xml+

"Me" Instead of "This"

In JavaScript, the "this" object generally refers to the current object receiving the event. Never use the "this" object in Composer scripts.
All Composer JavaScript (for rules, click action scripts, etc.) are embedded in a function, rather than being coded directly under an event. (The reasons for this are beyond this document's scope.) The commonly used "this" object, which refers to the current object, is not available in functions. Instead, Composer provides a "me" object. The me object refers to the object where the business rule is located.
If you have some existing JavaScript code that works correctly in either PDF or HTML, you can generally simply replace every occurrence of "this" with "me" for the same code to work in Composer.

Other Departures from Standard JavaScript

If you want to reuse a legacy script in Composer and want it to work correctly across platforms, you must modify it to use the technology-independent Composer Framework JavaScript library instead of the native libraries. For example, use sfc.getRawValue(me) rather than me.rawValue. See the Avoka Composer Framework link on Composer's Welcomepage.
Here, in the context of Composer, "across platforms" specificity means that the sfc calls work for both PDF and HTML.

Classes and Functions

Many of the Composer functions, which are defined in sfcFunctions.js library, have been designed for your convenience — to accomplish a lot with little code. Many of these are embodied in the function buttons in the ScriptEditor.

The function buttons insert the corresponding function code into the Script tab's text window. That code ("$SUM(...)" for example) gets expanded further at runtime (to "sfcFunction.sum(...)" for example
We will also use the terminology "sfc classes" interchangeably with "Composer functions". We will mention here a few of these sfc classes created for you convenience:
sfc.copyValues (srcBlockNodeRef, targetBlockNodeRef);
though note that this does not work recursively, i.e. to blocks within blocks.
Composer also uses conveniently has a number of scripting conventions, such as parameters, which reduce the amounts of code needed to refer to form elements and their values. For more, see the Composer Framework.

Syntax Checking

There are a number of JavaScript tools on the web for checking syntax:
{+}http://www.javascriptlint.com/online_lint.php+
A simple webpage, where you paste your JavaScript fragment into a textarea field and you get back a report of any simple syntax errors. Note that this tool is somewhat limited in scope, but this makes it very useful for quick checks.
Most modern browsers have JavaScript tools {+}https://developers.google.com/chrome-developer-tools/docs/javascript-debugging+ documentation for Chrome's inbuilt checker
{+}https://developer.mozilla.org/en-US/docs/Tools/Debugger+{+}https://developer.mozilla.org/en/docs/Debugging_JavaScript+ These document Firefox's inbuilt Web Console tool
{+}https://developer.apple.com/library/mac/documentation/AppleApplications/Conceptual/+Safari_Developer_Guide/Debugger/Debugger.html
The documentation for Apple's Safari on OS X

Composer Framework

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
o sfc.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.

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 BusinessRules 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_Objectshttp://www.w3schools.com/jsref/jsref_obj_global.asphttp://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.


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 parametertype via a dropdown:
o string

• Boolean

o number

• Is Selected

o node
o raw value o UID Trigger Type o Static

• Dynamic

We will discuss the Trigger Type further in OptimizingPerformance.

Parameter Types

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)

Data Types

Overview

Data Typing is used throughout Information Technology. In Composer, there are two sets of data types:
Composer's own typing, as embodied in parameterdatatypes

• which are used by Composer internally. Some of these are exclusive to Composer:
  • • Node
    • UID
    • Is Selected JavaScript'styping
• not to be confused with the Composer types, though some do resemble Composer's

The Composer types, as you would expect, were designed to handle data for both HTML and PDF forms.
JavaScript is looser in its data typing, which means that you usually do not explicitly specify some data's type. Circumstances, however, may require you to type data in order to get desired results.

JavaScript Types

JavaScript has less types than Composer. For example, there is no such thing as a Date type. All JavaScript has are:

String

which is a sequence of characters, usually delimmited by straight quote marks for example: "To be or not to be"

Number

and there is no distinction made between inegers or decimals for example: 2, 3.142, 123e5 (scientific notation for 12300000)

Boolean

that is: true or false JavaScript arrays JavaScriptObjects
for example: JSON objects

Undefined

A variable with no value

Null

An empty variable
Note: undefined is not the same type as null. This is a subtle distinction, but it does have relevance to Composer scripting, as in the a scripting example given in VisibilityinCollaboration.

Raw Data

This is a Composer internal data type. All data is held internally in Composer as a string of characters, be it a number, date, string and so on. This can be tricky: for example there is a difference between the integer 2, the floating point value 2 and the string "2". JavaScript handles the calculation of adding an integer to a floating point gracefully, but can mishandle adding an integer to a string.
Dates are a potential source of problems. Please refer to the Dates topic.

Conversions

Because of JavaScript's loose typing, the need to convert form values hardly ever arises for Script Editor parameters. Composer looks after this for you.
However, if you are writing your own field references manually, you may have to convert the field's value from its native raw data value. The Public API has a number of methods to do this:
sfc.convertToBoolean(value) sfc.convertToFloat(value) sfc.convertToInteger(value) sfc.convertToString(value)
Converts a number value (or Boolean?) into a Composer string data type. sfc.formatDate(dateObject, dateFormat)
see Dates sfc.getFormattedValue(noderef)
returns the value of the node according to its Composer data type sfc.getRawValue(noderef)
the opposite of the formatted value: retaurns the raw value, irrespective of the Composer data type.

Explicit Conversions

You can convert String values using the public API's functions (listedabove). For example:
var myvalue = sfc.convertToNumber(sfc.getRawValue(me));
This code will convert the raw value of the current field ("me") to a Number.

Implicit Conversion

JavaScript is a loosely typed language, and will attempt to convert data for you. The rules are a little complicated, which is why we suggest that you always try to convert to the appropriate type before you use them.
One simple example is a way to convert any data type into a string - simply concatenate an empty string to it. For example:
var var1 = 18; // var1 is a number
var var2 = var1+""; var2 is a string, because we concatenated "" to it.

Comparisons

Be careful when making comparisons between different data types. JavaScript will attempt to convert them for you, but the results may not always be the expected.
In JavaScript, the "this" object generally refers to the current object receiving the event. Never use the "this" object in Composerscripts.
All Composer JavaScripts are embedded in a function (see Advanced Scripting), rather than being coded directly under an event. (The reasons for this are out-of-scope.) The commonly used "this" object to refer to the current object, is not available in functions. Instead, Composer provides a "me" object. The "me" object refers to the object where the Composer script is located, i.e. the form element whose Edit Properties dialog holds
the script.
If you have some existing JavaScript code that works correctly in either PDF or HTML, you can generally simply replace every occurrence of "this" with "me" for the same code to work in Composer.
Note: If you want the script to work correctly across different technologies, you must also rewrite it to use Composer's technology independent JavaScript library rather than the native libraries. for example, use sfc.getRawValue(me) rather than me.rawValue. See the Avoka Composer Framework.

Dates

Date Formats and Patterns

There are a number of different ways in which data is stored, displayed, edited and validated in Composer forms. These are mostly useful for dates and numeric values, which can be represented in different ways. When you are using Composer, you can specify these different formats by using data patterns, such as DD/ MM/YYYY or $#,###.##.
The different formats are:

Usually, you don't need to be aware of these patterns because they are specified in your organizational stylesheets. However, you may need to occasionally override these patterns for particular fields.
In most cases, users will enter dates using pop-up date editors, and so date edit format patterns are not so important. However, some users, especially "power" users and visually impaired users may prefer to enter dates using the keyboard.

Recommendation for Dates

For dates, we recommend that the most useful Data Format is:
North America: date{M/D/YYYY}|date{M/D/YY}
Elsewhere: date{D/M/YYYY}|date{D/M/YY}
These format will:
accept single digit days and months with or without a leading zero (flexible)
accept 2 digit or 4 digit years (flexible)
for editing, will always display days and years without leading zeros (simpler)
for editing, will always display years including the century (no ambiguity) Working with Dates
Composer uses theJavalibrarymoment.js (freely distributable under the terms of the MIT license) to handle dates.
The date clases in the AvokaComposerFramework are:
sfc.formatDate(dateObject, dateFormat)
where "dateObject" is is the raw value of the form element, sfc.getRawValue(someFormElement)
sfc.getDaysDifference(startDate, endDate) Where the startDate and endDate are raw values.
sfc.getTodaysDate()
Returns today's date as YYYY-MM-DD
This is not the generation date of the form (which you access in scripts with the property formula
$GENERATION{DATE} instead)
This call returns only the calendar date. To get the time of day and timezone as well, use this native JavaScript call instead, where "x" will be your date object.
var x = new Date();
sfc.isLeapYear(year)
Where "year" is a 4-digit value. Returns true or false.
sfc.isPastDate(date)
Where "date" is the raw value. Returns true or false
sfc.isToday(date)
Where "date" is the raw value.
sfc.parseDate(dateString, dateFormat)
Parses a date according to the given date format. Both parameters are strings. Returns a raw value.

Advanced Date Output Formats

The sfc methods for date handling depend on the Moment.js library. This JavaScript library can output dates in various formats, as specified by this table:

You parse an input date with sfc.parseDate (dateString, dateFormat), using the formats in the Input column of the table immediately below. The output of this call gives you a properly formatted raw date format.
You can use these to build the full input format specification, using other characters as punctuation. For example: YYYY-MM-DD or YYYY/MM/DD or DD/MM/YYYY or MM/DD/YYYY. Internally, Composer's raw date format is YYYY-MM-DD, or for more precision to include time of day, timezones along with the date, it uses the ISO DateFormat.
You also can control how a date object displays using sfc.formatDate(dateObject, dateFormat), using the formats displayed in the right-hand "Output" column. As with inputs, you can concatenate these together using characters as punctuation. For example: "MMMM Do, YYYY, HH:mm a, timezone Z" formats as "May 19th, 2014, 13:27 pm, timezone +10:00", where the Z specifies the timezone as the timezone offset from GMT.
To return the precise time and timezone, use
var x= new Date;
and get the formatted time with our sample format with the call
sfc.formatDate(x, "MMMM Do, YYYY, HH:mm a, timezone Z")

Regular Expressions

Overview

A regular expression is a sophisticated, industry-standard way of specifying a validation pattern. An explanation of regular expressions is beyond the scope of this document, but there are numerous books and web sites that you can refer to. You can also use search engines to find standard regular expressions for common types of data. An example of some regular expression patterns are:
^[a-zA-Z0-9_-\.]@[a-zA-Z0-9_-\.]\.[a-zA-Z]{2,4}$ the pattern for email addresses
^http\://[a-zA-Z0-9-\.]+\.[a-zA-Z]{2,3}(/\S*)?$
the pattern for HTTP:// URLs

RegEx References

https://developer.mozilla.org/en/docs/Web/JavaScript/Guide/Regular_Expressionshttps://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/RegExphttp://www.regular-expressions.info/javascript.html
http://regex101.comhttp://regexpal.com
A good resource for regular expressions is: http://regexlib.com/.

Online regular expression editor and evaluator can be found at: http://gskinner.com/RegExr/ and http://www.debuggex.com/.

How to Use Regular Expressions

There are two ways to use patterns in JavaScript:
var patt = new RegExp(pattern,modifiers); or more simply:
var patt = /pattern/modifiers;
The modifiers (also called "flags" in the documentation) are:

g

global match

i

ignore case

m

multiline; treat beginning and end characters (^ and $) as working over multiple lines (i.e., match the beginning or end of each line (delimited by \n or \r), not only the very beginning or end of the whole input string)
y
sticky; matches only from the index indicated by the lastIndex property of this regular expression in the target string (and does not attempt to match from any later indexes). This allows the match-only-at-start capabilities of the character "^" to effectively be used at any location in a string by changing the value of the lastIndex property.
In other words, in most cases where you are not using a modifier, just use the pattern as follows:
/^[a-zA-Z0-9_-\.]@[a-zA-Z0-9_-\.]\.[a-zA-Z]{2,4}$/
in your JavaScript code.

Using Property Formulae

Overview

The following scripting constructs, the property formulae, only apply while the form is being generated. When generation is complete, the fom is then delivered to the user, either as HTML the browser or as XFA to Acrobat reader (or some other reader) or to a pdf browser internal module or plugin.
These property formulae allow you to query the build environment, to inspect a form field, to find a field in the form hierarchy, perform some string manipulations, and other useful functions.
They do not trigger anything while the form is running and only affect the time it takes to serve a form.

$BUILD

$CHAR

$CHAR is a convenience to specify characters, in a text field for example, that would normally are parsed in JavaScript.

$DATA

$ENCODE

Note: $ENCODE is unique among the property formulae, in that you can specify multiple values, pipe- delimited. For example: "$ENCODE{TRIM|UPPER,value}", will first trim the string (i.e. remove any leading or trailing space characters) offered as the "value" and then convert the characters to upper case. The order of these pipe-separated arguments is important, as changing the order of them my affect the output. Note that these are executed from left to right.

$FIELD

$FIND

$FLOAT

TBA

$FORM

$GENERATION

$IF

TBA

$INFO

$LIST

$LOCALE

$LOOKUP

TBA

$MATH

$RULE

$SEQUENCE

$STRING

$TEST