FormCalc reference syntax shortcuts

To make accessing object properties and values easier, FormCalc includes shortcuts to reduce the effort required to create references. This section describes the reference syntax shortcuts for FormCalc.

Current field or object

Refers to the current field or object

Notation

$

Example

$ = "Tony Blue"

The above example sets the value of the current field or object to Tony Blue.

Data model root of xfa.datasets.data

Represents the root of the data model xfa.datasets.data.

Notation

$data

Example

$data.purchaseOrder.total

is equivalent to

xfa.datasets.data.purchaseOrder.total

Form object event

Represents the current form object event.

Notation

$event

Example

$event.name

is equivalent to

xfa.event.name

For more information see Working with the Event Model.

Form model root

Represents the root of the form model xfa.form.

Notation

$form

Example

$form.purchaseOrder.tax

is equivalent to stating

xfa.form.purchaseOrder.tax

Host object

Represents the host object.

Notation

$host

Example

$host.messageBox("Hello world")

is equivalent to

xfa.host.messageBox("Hello world")

For more information, see Working with a Host Application.

Layout model root

Represents the root of the layout modelxfa.layout.

Notation

$layout

Example

$layout.ready

is equivalent to stating

xfa.layout.ready

Collection of data record

Represents the current record of a collection of data, such as from an XML file.

Notation

$record

Example

$record.header.txtOrderedByCity

references the txtOrderedByCity node within the header node of the current XML data.

Template model root

Represents the root of the template model xfa.template.

Notation

$template

Example

$template.purchaseOrder.item

is equivalent to

xfa.template.purchaseOrder.item

Data model root of xfa.datasets

Represents the root of the data modelxfa.datasets.

Notation

!

Example

!data

is equivalent to

xfa.datasets.data

Select all form objects

Selects all form objects within a given container, such as a subform, regardless of name, or selects all objects that have a similar name.

You can use the ‘*’ (asterisk) syntax with JavaScript if it used with the resolveNode method.

Notation

*

Example

For example, the following expression selects all objects named item on a form:

xfa.form.form1.item[*]

Search for objects that are part of a subcontainer

You can use two dots at any point in your reference syntax to search for objects that are a part of any subcontainer of the current container object, such as a subform.

You can use the ‘..’ (double period) syntax with JavaScript if it used with the resolveNode method.

Notation

..

Example

The expressionSubform_Page..Subform2means locate the nodeSubform_Page(as usual) and find a descendant ofSubform_PagecalledSubform2.

Using the example tree above,

Subform_Page..TextField2

is equivalent to

Subform_Page.Subform1[0].Subform3.TextField2[0]

becauseTextField2[0]is in the firstSubform1node that FormCalc encounters on its search. As a second example,

Subform_Page..Subform3[*]

returns all fourTextField2objects.

Denote an unnamed object or specify a property

The number sign (#) notation is used to denote one of the following items in a reference syntax:

  • An unnamed object

  • Specify a property in a reference syntax if a property and an object have the same name

You can use the ‘#’ (number sign) syntax with JavaScript if it used with the resolveNode method.

Notation

#

Example

The following reference syntax accesses an unnamed subform:

xfa.form.form1.#subform

The following reference syntax accesses the name property of a subform if the subform also contains a field named name:

xfa.form.form1.#subform.#name

Occurrence value of an object

The square bracket ([ ]) notation denotes the occurrence value of an object.

In language-specific forms for Arabic, Hebrew, Thai, and Vietnamese, the reference syntax is always on the right (even for right-to-left languages).

Notation

[ ]

Example

To construct an occurrence value reference, place square brackets ([ ]) after an object name, and enclose within the brackets one of the following values:

  • [ n ], where n is an absolute occurrence index number beginning at 0. An occurrence number that is out of range does not return a value. For example,

    xfa.form.form1.#subform.Quantity[3]

    refers to the fourth occurrence of the Quantity object.

  • [ +/- n ], where n indicates an occurrence relative to the occurrence of the object making the reference. Positive values yield higher occurrence numbers, and negative values yield lower occurrence numbers. For example,

    xfa.form.form1.#subform.Quantity[+2]

    This reference yields the occurrence of Quantity whose occurrence number is two more than the occurrence number of the container making the reference. For example, if this reference was attached to the Quantity[2]object , the reference would be the same as

    xfa.template.Quantity[4]

    If the computed index number is out of range, the reference returns an error.

    The most common use of this syntax is for locating the previous or next occurrence of a particular object. For example, every occurrence of the Quantity object (except the first) might use Quantity[-1] to get the value of the previous Quantity object.

  • [*] indicates multiple occurrences of an object. The first named object is found, and objects of the same name that are siblings to the first are returned. Note that using this notation returns a collection of objects. For example,

    xfa.form.form1.#subform.Quantity[*]

  • This expression refers to all objects with a name ofQuantitythat are siblings to the first occurrence ofQuantityfound by the reference.

Using the tree for reference, these expressions return the following objects:

  • Subform_Page.Subform1[*]returns bothSubform1objects.

  • Subform_Page.Subform1.Subform3.TextField2[*]returns twoTextField2objects.Subform_Page.Subform1resolves to the firstSubform1object on the left, andTextField2[*]evaluates relative to theSubform3object.

  • Subform_Page.Subform1[*].TextField1 returns both of theTextField1instances.Subform_Page.Subform1[*]resolves to bothSubform1objects, andTextField1evaluates relative to theSubform1objects.

  • Subform_Page.Subform1[*].Subform3.TextField2[1]returns the second and fourthTextField2objects from the left.Subform_Page.Subform1[*]resolves to bothSubform1objects, andTextField2[1]evaluates relative to theSubform3objects.

  • Subform_Page.Subform1[*].Subform3[*]returns both instances of theSubform3object.

  • Subform_Page.*returns bothSubform1objects and theSubform2object.

  • Subform_Page.Subform2.*returns the two instances of theNumericField2object.

  • You can use the ‘ [ ]’ (square bracket) syntax with JavaScript if it used with the resolveNode method.

// Ethnio survey code removed