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).


The syntax for Composer's scripts is that of JavaScript. JavaScript is maintained by the Mozilla Foundation. Here are the canonical references:
Other authoritative references are:

"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:
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 {+} documentation for Chrome's inbuilt checker
{+}{+} These document Firefox's inbuilt Web Console tool
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


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.)


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:
For example:
var n = 12345;
var x = n.toExponential(); // x will be 1.2345e+4


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:
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

Parameter Type



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.


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.)


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.


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.


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


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.


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

Obtaining the UID

You could get this from "Edit Properties -> Overview tab -> Basic Information panel -> field UID"
For example:
Or you can use the sfc call: sfc.convertToUid(noderef)

Data Types


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:
  • 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:


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


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


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


A variable with no value


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.


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.


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.


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:



Edit Format

This is the format that is used when the user types into the field. For example, 3/27/2012, or 49.99. It is possible to have multiple alternate edit formats - for example, allowing either 2 or 4 digit years.

Display Format

This is the format that is displayed when the user exits the field. It can be more readable than the edit format, and clarifies the interpretation. For example, 27th March 2012 or $49.99

Raw Format

This is the value that is actually stored within the form at runtime. It's the value you get from calling the getRawValue(). This is standardized to make programming easier

  • it doesn't matter what your formats are used for the form users, you always get a consistent value in any code you write. For dates, this is ISO format, such as 2012- 03-27.

XML Format

This is the format that is used to actually store the data in the XML file. Composer will use this format for pre-population data, and will convert to this format on submission.

Validation Pattern

PDF forms allow a separate validation pattern that is used to ensure that the data is valid. In Composer, the Validation Pattern is always identical to the Edit Pattern.

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.
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
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();
Where "year" is a 4-digit value. Returns true or false.
Where "date" is the raw value. Returns true or false
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:




Month Number (1 - 12)


Month Name


Quarter (1 - 4) – sets the month to the first month in that quarter


Day of month


Ordinal day of month (from 2.6.0)


Day of year

d, dd, ddd, dddd

Day of week (NOTE: these formats only make sense when combined with "ww")


Day of week (locale) (NOTE: these formats only make sense when combined with "ww")


Day of week (ISO) (NOTE: this format only make sense when combined with "WW")



w, ww

Week of the year (NOTE: combine this format with "gg" or "gggg" instead of "YY" or "YYYY")


Week of the year (NOTE: combine this format with "GG" or "GGGG" instead of "YY" or "YYYY")


2 digit year (see below)


4 digit year


2 digit week year (if greater than 68 will return 1900's, otherwise 2000's)


4 digit week year


2 digit week year (ISO) (if greater than 68 will return 1900's, otherwise 2000's)


4 digit week year (ISO)

a, A



24 hour time

h, hh

12 hour time (use in conjunction with a or A)

m, mm


s, ss



Deciseconds (1/10th of a second)


Centiseconds (1/100th of a second)


Milliseconds (1/1000th of a second)


Timezone offset as +07:00 or +0700


Unix timestamp


Locale dependent date and time representation

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


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
the pattern for HTTP:// URLs

RegEx References
A good resource for regular expressions is:

Online regular expression editor and evaluator can be found at: and

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:


global match


ignore case


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)
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:
in your JavaScript code.

Using Property Formulae


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.





Returns the values of the called arguments: ENVIRONMENT







Returns a comma character ','


Returns a dot character '.'


Returns a slash character '/'

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





Returns the root element of the form:
E.g. "/AvokaSmartForm"





Encodes the value so it can placed in a javascript string literal


Replaces richtext markup with its form specific implementation


URL encodes the supplied value


Encodes the value with XML markup entities


Removes richtext markup


Removes cr, lf characters, leading and trailing spaces


Converts the value to uppercase


Converts the value to lowercase


Converts the value to a valid javascript function name by replacing invalid chars with _

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.





returns the type of the current field



if any


returns the type of the field at the relative uid

$FIELD{TYPE,relativeUid,type Name}

returns 'true' if the type of the field at the relative uid is an instance of the supplied type name


returns the value of the current property of the current field


returns the value of the current property as defined in the specified type


For radio buttons only, indicates whether the buttons value is controlled by the group or by the button
returns 'group' for group controlled buttons (case 1&2) returns 'button' for button controlled buttons (case 3)


For radio buttons only
returns true if the button type (as deternmined by
$FIELD{RBTYPE}) matches the supplied type.


returns the relative uid of the closest parent instance manager or blank if not found


returns the number of repeat instances this field is nested inside of


returns the index of the field as a child of its parent


returns the reverse index of the field wrt its parent


returns true if this field is the first child of its parent


returns true if this field is the last child of its parent


returns the number of child fields


returns true if the field has at least 1 child


returns the contents of the given resource applying formula substitutions with the context of the current field.





Searches from the current context up the hierachy for a property with the given name



and returns the value of the first one found. If a property isn't found then a blank string is returned.

E.g. $FIND{} returns the section name from within any child field of the section


Sames as $FIND{propertyname} but the upwards search begins from the field found at the relative path provided. If no field can be found at the supplied path then a blank string is returned.

e.g. $FIND{../../someField,label}







Returns the form's values of the called argument























Returns the form's info values of the called arguments













$LIST{CONTAINS,list,value,sepa rator}

Returns true if the list contains the value

$LIST{INDEXOF,list,value,separ ator}

Returns the 0 based index of the value within the list

$LIST{ITEMAT,list,index,separat or}

Returns the item at 0 based index position within the list


Returns the size of the list





Returns the form's locale values of the called arguments









Converts the value to pixels and strips the units


Converts the value to inches and strips the units


Converts the value to millimetres and strips the units


Returns the largest value - if the first value has units then the result is returned in those units


Returns the smallest value - if the first value has units then the result is returned in those units


Returns the sum of the supplied values - if the first value has units then the result is returned in those units


Returns the product of the supplied values (multiplies them together) - if the first value has units then the result is returned in those units


Returns half of the supplied value - if the value has units then the result is returned in those units


Returns twice of the supplied value - if the value has units then



the result is returned in those units


Converts a composer margin to a technology supported margin





Returns the trigger width in pixels for the given rule




$SEQUENCE{Sequence argument, Sequence argument1, ......, RESET)

Resets the named sequences.




$STRING{CONTAINS,value,patt ern}

Returns true if the value contains the pattern as a substring

$STRING{INDEXOF,value,patter n}

Returns the 0 based index of the pattern within the value or -1 if not found.





Returns true if the supplied value is blank


Returns true if the supplied value is not blank


Returns true if value1 and value2 are the same

$TEST{NOTEQUALS,value1,valu e2}

Returns true if the value1 and value2 are not the same


Returns true if value is the literal false otherwise returns false


Returns true if value1 and value2 are both the literal true


Returns true if value1 or value2 are the literal true

$TEST{LESSTHAN,value1,value 2}

Returns true if value1 as a number is less than value 2 as a number


Returns true if value1 as a number is greater than value 2 as a number