DocumentationAEM 6.5User Guide

Scripting support for HTML5 forms scripting-support-for-html-forms

Last update: Thu Dec 21 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

JavaScript, FormCalc properties, and methods supported in HTML5 forms are as listed below:

$event event

Property
Description
Exception
prevText
Specifies the content of the field before it changes in response to the actions of a user. This value can be recalled, similar to an undo feature.

Does not work for drop-downs and list boxes. PrevText does not work correctly for the following cases:

  • On typing some special character keys (for example, $ or , or & or @ and more) in Numeric fields on the iPad, and
  • For the Date field (when date is entered through calendar).

Setting value through script is not supported.

target
Specifies the object upon which the event is acting.
Setting value through script is not supported.
newtext
Specifies the content of the field after it changes in response to user actions.

The newText property does not work properly for following cases :

  • On selecting-replacing texts
  • On deleting, copying, and pasting texts.
  • On typing some special character keys (for example, $ or , or & or @ and more) in Numeric fields
  • On using shift+alphanumeric combination.
  • On using date/time fields.

Setting value through script is not supported.

change
Specifies the value that a user types or pastes into a field immediately after they perform the action.

The change property does not work properly for following cases:

  • On selecting-replacing texts
  • On deleting, copying, and pasting texts.
  • On typing some special character keys (for example, $ or , or & or @ and more) in Numeric fields
  • On using shift+alphanumeric combination.
  • On using date/time fields.

Setting value through script is not supported.

keydown
Determines whether a user is pressing an arrow key to make a selection. This property is available only for list boxes and drop-down lists.
None
modifier
Determines whether the modifier key (for example, Ctrl on Microsoft® Windows®) is held down when a particular event executes.
None

$host host

Property
Description
Exception
apptype
Returns the application type of the host. Available only for client applications.
Returns HTML 5.
name
Returns the name of the current application.
Returns the browser name and its version. For example, in Chrome browser, the value returned is Chrome <version>.
numPages
Returns the number of pages in the document.
Pagination policy of HTML5 forms is not identical to PDF forms pagination policy. So the numPages API can return a different values in both the cases.
platform
Returns a string representing the platform of the computer running the script.
None
title
Specifies the title of the document. It is available only for client applications.
It returns title of HTML document in form, rather than the form metadata title as if there are PDF Forms.
version
Returns a string representing the version number of the current application.
It returns the version of the form.
calculationsEnabled
Specifies whether calculate scripts will execute.
None
validationsEnabled
Specifies whether validation scripts will execute.
None
pageUp
Goes to the previous page.
HTML5 forms do not follow the same pagination policy as PDF Form, so the previous page of an HTML5 form is different from previous page of a PDF Form.
pageDown
Moves to the next page of a form. Use the pageDown method at runtime.
setFocus
Sets the keyboard focus to the field specified. The field is specified as an object, or by the SOM expression of the field. It is available only for client applications.
resetdata
Resets the fields to their default values within a document.
Clears all data in a form with merged data, rather than restoring it to default values.
messageBox
Displays a dialog box on the screen. It is available only for client applications
Message box of type Yes/No is converted to OK/Cancel. Message box with three buttons is not supported.
currentPage

Sets the currently active page of a document at runtime.

Page values are 0-based, so the first page of a document returns a value of 0.

The currentPage property is available when layout:ready executes on a client. However, it is not available when layout:ready executes on the server because the property will not execute until the form layout executes.

None

field field

Property
Description
Exception
presence
Controls the participation of the associated object in different phases of processing. If the object is a container, the contents of the container inherit whatever restrictions this control applies.
None
access
Controls user access to the contents.
Does not work for the exclusion group. Moreover, HTML5 forms gives same treatment to non-interactive and protected objects.
name
An identifier that is used to identify this element in script expressions.
HTML5 forms do not allow setting name property for objects. It is read-only property for HTML5 forms.
value
A content element that encloses a single unit of data content.
None
rawValue
Specifies the unformatted value for this field.
None
formattedValue
Specifies the formatted value for this field.
Setting formattedValue through script is not supported.
editValue
Specifies the edit value for this field.
Setting editValue through script is not supported.
formatMessage
Specifies the format validation message string for this field.
Setting formatMessage through script is not supported.
fillcolor
Specifies the background color value for this field. You need to set the border.fill.presence property to visible separately.
It does not correctly return default color of the field.
border
The border object describes the border surrounding an object.
ui
The ui object encloses the user interface description of a form object.
mandatory
Specifies the nullTest value for the field.
borderColor
Specifies the border color value for this field. You need to set the border.edge.presence property to visible separately.
It does not correctly return default border color of the field.
length
The number of items in the list.
None
addItem
Adds new items to the current field.
None
clearItem
Removes all the items from the field.
None
boundItem
Gets the bound value of a specific display item of a drop-down list or list box.
None
execCalculate
Executes the calculate script of the field.
None
execValidate
Executes the validate script of the field.
None
execEvent
Executes the event script of the object.
None
getItemState
Returns the selection state of the specified item
None
setItemState
Sets the selection state of the specified item.
None
getDisplayItem
Retrieves the item display text for the specified item index.
None
getSaveItem
Retrieves the data value for the specified item index.
None
deleteItem
Deletes the item at the specified index.
None
setItems
Sets the specified items in the current field. It replaces pre-existing items.
None
h
A measurement of the height for the layout.
None
w
A measurement specifying the width for the layout.
None
x
Specifies the x coordinate of the container's anchor point relative to the upper-left corner of the parent container when placed with positioned layout.
None
y
Specifies the y coordinate of a container's anchor point relative to the upper-left corner of the parent container when placed with positioned layout.
None
caption
The caption object describes a descriptive label associated with a form design object.
None
validate
The validate object controls validation of user-supplied data on a form. The validate object can be activated multiple times during the life of a form.
None
parentSubform
Specifies the parent subform (page) of this field.
Always returns parent subform instead of returning first non-scoping parent subform.
selectedIndex
The index of the first selected item.
None

Form form

Property
Description
Exception
formNodes
Returns a list of all form model objects that are bound to a specified data object.

InstanceManager instancemanager

Property
Description
name
An identifier that is used to identify this element in script expressions.
occur
Describes the constraints over the number of allowable instances for its enclosing container.
min
Specifies the minimum number of instances that can be instantiated.
max
Specifies the maximum number of instances that can be instantiated.
count
Specifies the current number of instances instantiated.
setInstances
Adds or removes the specified subforms or subform sets from this node.
addInstance
Adds a new instance of a subform or subform set to this node.
removeInstance
Removes a subform or subform set from this node.
moveInstance
Moves a child object of a form model object to another specified location within the form model. The corresponding data model information for the object is also relocated within the data model.
insertInstance
Inserts a new instance of a subform or subform set to this node.

list list

Property
Description
length
The number of elements in the list.
item
A zero-based index into the collection.
append
Appends a node to the end of the node list.
remove
Removes a node from the node list.
insert
Inserts a node before a specific node in the node list.

node node

Property
Description
Exception
createNode
Creates new node based on a valid class name.
None
isContainer
Specifies whether this object is a container object.
None
isNull
Indicates whether the current data value is a null value.
None
resolveNode
Evaluates the specified SOM expression, beginning with the current XML form object model object, and returns the value of the object specified in the SOM expression.
None
resolveNodes
Evaluates the specified SOM expression, beginning with the current XML form object model object, and returns the value of the object specified in the SOM expression.
None
oneOfChild
Creates new node based on a valid class name.
None
getElement
Returns a specified child object.
None
getAttribute
Gets a specified property value.
None
setAttribute
Sets the value of a specified property.
None

model model

Property
Description
Exception
NA
NA
NA

Subform subform

Property
Description
Exception
instanceIndex
Specifies the index of the object, relative to the other instantiated instances.
None
execEvent
Executes the event script of the object.
None
getInvalidObjects
Returns a list of nodes contained within the subform (inclusive), that have failed the validation test.
None
border
The border object describes the border surrounding an object.
None
borderColor
Specifies the border color value for this field. You need to set the border.edge.presence property to visible separately.
None
h
A measurement of the height for the layout.
None
w
A measurement specifying the width for the layout.
None
x
Specifies the x coordinate of the container's anchor point relative to the upper-left corner of the parent container when placed with positioned layout.
None
y
Specifies the y coordinate of a container's anchor point relative to the upper-left corner of the parent container when placed with positioned layout.
None
validate
The validate object controls validation of user-supplied data on a form. The validate object can be activated multiple times during the life of a form.
None
name
An identifier that is used to identify this element in script expressions.
None
presence
Specifies an object's visibility.
None
access
Controls user access to the contents of a container object, such as a subform.
None
execValidate
Calculates the index of a subform or subform set based on where it is located relative to other instances of the same form object.
None
instanceManager
The instanceManager object manages the instance creation, removal, and movement of form model objects.
None

submit submit

Property
Description
target
The URL to which the data is submitted. Omission of this attribute implies the XFA processing application obtains the URI using a product-specific technique, such as accessing product-specific information in the config object.

tree tree

Property
Description
Exception
nodes
Returns a list of all child objects of the current object.
  • Not supported for xfa.nodes, desc
  • Number of nodes reported for PDF and HTML are different.
name
Specifies the name of this node.
Setting the name using scripts is not allowed in HTML.
parent
Gets the parent for this node.
None
index
Returns the position of this node in its collection of like-named, in-scope, like-child relationship nodes.
None
somExpression
Gets the SOM expression for this node.
None
resolveNode
Evaluates the specified SOM expression, beginning with the current XML form object model object, and returns the value of the object specified in the SOM expression.
None
resolveNodes
Evaluates the specified SOM expression, beginning with the current XML form object model object, and returns the value of the object specified in the SOM expression.
None

subformset subformset

Property
Description
Exception
instanceManager
The instanceManager object manages the instance creation, removal, and movement of form model objects.
None

content content

Property
Description
Exception
isNull
Indicates whether the current data value is the null value.

dataValue datavalue

Property
Description
Exception
isNull
Indicates whether the current data value is the null value.

edge edge

Property
Description
Exception
color
The color property describes a unique color for the pattern object.
  • The default value cannot be retrieved.
  • The changes are reflected in Model and are available for scripting but are not synced to HTML elements. Hence, the changes are not reflected in the UI.

fill fill

Property
Description
Exception
color
The color properties define a unique color of fill.
  • The default value cannot be retrieved.
  • The changes are reflected in Model and are available for scripting but are not synced to HTML elements. Hence, the changes are not reflected in the UI.

linear linear

Property
Description
Exception
color
The color property describes a unique color for a linear gradient fill on a form.
  • The default value cannot be retrieved.
  • The changes are reflected in Model and are available for scripting but are not synced to HTML elements. Hence, the changes are not reflected in the UI.

line line

Property
Description
Exception
edge
The edge object describes an arc, line, or one side of a border or rectangle.
Attributes such as color, cap, and more are not supported.

pattern pattern

Property
Description
Exception
color
The color property describes a unique color for the pattern object.
  • The default value cannot be retrieved.
  • The changes are reflected in Model and are available for scripting but are not synced to HTML elements. Hence, the changes are not reflected in the UI.

radial radial

Property
Description
Exception
color
The color property describes a unique color for the radial object
  • The default value cannot be retrieved.
  • The changes are reflected in Model and are available for scripting but are not synced to HTML elements. Hence, the changes are not reflected in the UI.

stipple stipple

Property
Description
Exception
color
The color property describes a unique color for the stipple object.
  • The default value cannot be retrieved.
  • The changes are reflected in model and are available for scripting but are not synced to HTML elements. Hence, the changes are not reflected in the UI.

draw draw

Property
Description
Exception
ui
The ui object encloses the user interface description of a form object.
caption
The caption object describes a descriptive label associated with a form design object.
presence
Specifies an object's visibility.
name
Specifies an identifier that may be used to specify this object or event in script expressions.
Setting the value at the runtime is not supported
value
The value object encloses a single unit of data content.

corner corner

Property
Description
Exception
color
The color property describes a unique color for the corner object.
  • The default value cannot be retrieved.
  • The changes are reflected in model and are available for scripting but are not synced to HTML elements. Hence, the changes are not reflected in the UI.

checkButton checkbutton

Property
Description
Exception
border
The border object describes the border surrounding checkButton object.
The changes are reflected in model and are available for scripting but are not synced to HTML elements. Hence, the changes are not reflected in the UI.

choiceList choicelist

Property
Description
Exception
border
The border object describes the border surrounding choiceList object.

dateTimeEdit datetimeedit

Property
Description
Exception
border
The border object describes the border surrounding dateTimeEdit object.

Image image

Property
Description
Exception
contentType
Specifies the type of content in the referenced document, expressed as a MIME type.
None
name
An identifier that is used to identify this element in script expressions.
None

imageEdit imageedit

Property
Description
Exception
border
The border object describes the border surrounding imageEdit object.

numericEdit numericedit

Property
Description
Exception
border
The border object describes the border surrounding an object.
none

object object

Property
Description
Exception
className
Determines the name of the class of this object.
none

rectangle rectangle

Property
Description
Exception
edge
The edge object describes an arc, line, or one side of a border or rectangle.
Attributes such as color, cap, and more are not supported.

textEdit textedit

Property
Description
Exception
border
The border object describes the border surrounding an object.
None

exclGroup exclgroup

Property
Description
Exception
layout
Specifies the layout strategy to be used by this object.
None
border
Specifies the border surrounding this field.
None
mandatory
Specifies the nullTest value for the field.
None
borderColor
Specifies the border color value for this field.A border must be defined before you can change the color by scripting.
None
borderWidth
Specifies the border width for this field.
None
h
A measurement of the height for the layout.
None
transient
Specifies whether the processing application must save the value of the exclusion group as part of a form submission or save operation.
None
w
A measurement specifying the width for the layout.
None
x
Specifies the x coordinate of the container's anchor point relative to the upper-left corner of the parent container when placed with positioned layout.
None
y
Specifies the y coordinate of a container's anchor point relative to the upper-left corner of the parent container when placed with positioned layout.
None
caption
The caption object describes a descriptive label associated with a form design object.
None
validate
The validate object controls validation of user-supplied data on a form. The validate object can be activated multiple times during the life of a form.
None
dataNode
Gets the data node to which a form node is bound after merge.
None
presence
Specifies an object's visibility.
access
Controls user access to the contents of a container object, such as a subform.
For individual items in the exclgrp, it always returns open.
name
Specifies an identifier that may be used to specify this object or event in script expressions.
None
members
Specify the members of exclusion group.
None
selectedMember
Returns the selected member of an exclusion group.
None
execCalculate
Executes any scripts on the calculate event of the specified object, and any child objects.
None
calculate
The calculate object controls the calculation of a field's value.
None

arc arc

Property
Description
Exception
edge
The edge object describes an arc, line, or one side of a border or rectangle.
Attributes such as color, cap, and more are not supported.

border border

Property
Description
Exception
edge
The edge object describes an arc, line, or one side of a border or rectangle.
Attributes such as color, cap, and more are not supported.

$layout layout

Property
Description
Exception
h
Determines the height of a given form design object.
  • Height (h) property is not supported for page area and content area.
  • Parameter 'Offset from first content area the XFA-Form object occurs on' is not supported.
w
Determines the width of a given form design object.
  • Width (w) property is not supported for page area and content area.
  • Parameter 'Offset from first content area the XFA-Form object occurs on' is not supported.
x
Determines the x coordinate of a given form design object relative to its parent object.
  • x coordinate (x) property is not supported for page area and content area.
  • Parameter 'Offset from first content area the XFA-Form object occurs on' is not supported.
y
Determines the y coordinate of a given form design object relative to its parent object.
  • y coordinate (y) property is not supported for page area and content area.
  • Parameter 'Offset from first content area the XFA-Form object occurs on' is not supported.
pagecount
Determines the number of pages of the current form.
  • layout.pageCount() method returns different values for PDF and HTML forms.
  • On decreasing page count by hiding an object, abspagecount method returns incorrect value.
pagecontent
Retrieves types of form design objects from a specified page of a form.
None
absPageCount
Determines the page count of the current form.
  • layout.pageCount() method returns different values for PDF and HTML forms.
  • On decreasing page count by hiding an object, abspagecount method returns incorrect value.

items items

Property
Description
Exception
presence
Specifies an object’s visibility.
None

FormCalc formcalc

FormCalc is an XFA-specific language for creating e-form centric logic and calculations roots. FormCalculation provides a powerful set of build functions.

FormCalc Supported Functions formcalc-supported-functions

FormCalc Expression Support formcalc-expression-support

Category
Description
Sample
Simple Expression
Add, subtract, multiply, divide, and parentheses
(a+b)*3
Variable declaration
Define a variable
var a
var a=3
a=3
Logical expression
  • Logic (and/or)
  • Comparison (greater/less/ equal)
A or 1
1 <> 2
A NE B
A or 1
1 <> 2
A NE B
If expression
if (a>b) then 2 endif
while
while (i lt 5) do i = i + 1 endwhile
for
for i = 100 downto 1
do s = s + i endfor
for each
for each i in (1, 2, 3)
do s = s + i endfor
function declaration
Define a custom function in FormCalc
func foo(n) do var f = n endfunc

Acrobat API Support acrobat-api-support

  1. Arithmetic Functions

    1. Abs()
    2. Avg()
    3. Ceil()
    4. Count()
    5. Floor()
    6. Max()
    7. Min()
    8. Mod()
    9. Round()
    10. Sum()

  2. Scientific Functions

    1. Acos()
    2. Asin()
    3. Atan()
    4. Atan2()
    5. Cos()
    6. Sin()
    7. Tan()
    8. Exp()
    9. Log()
    10. Pow()
    11. Sqrt()
    12. Deg2Rad()
    13. Rad2Deg()
    14. Pi()

  3. Financial Functions

    1. Apr()
    2. Cterm()
    3. Fv()
    4. Ipmt()
    5. Npv()
    6. Pmt()
    7. Ppmt()
    8. Pv()
    9. Rate()
    10. Term()

  4. Logical Functions

    1. Choose()
    2. If()
    3. Oneof()
    4. Within()

  5. String Functions

    1. At()
    2. Concat()
    3. Left()
    4. Len()
    5. Lower()
    6. Ltrim()
    7. Replace()
    8. Right()
    9. Rtrim()
    10. Space()
    11. Stuff()
    12. Substr()
    13. Upper()
    14. WordNum()

  6. Date and Time

    1. Date()
    2. num2date()
    3. DateFmt()
API
Description
Aberration
console.println()
This acrobat API dumps the output toJavaScript console.
app.alert()
This acrobat API sends out an alert message throughJavaScript popup.
app.beep()
Causes the system to play a sound.
No action is performed.
app.execDialog()
Presents a modal dialog box to the user. Modal dialog boxes must be closed by the user before the host application can be directly used again.
No action is performed.
app.launchURL()
Launches a URL in a browser window.
app.setInterval()
Specifies a JavaScript script and a time period. The script is executed every time the period elapses. The return value of this method must be held in a JavaScript variable. Otherwise, the interval object is subject to garbage-collection, which would cause the clock to stop. To terminate the periodic execution, pass the returned interval object to clearInterval.
app.setTimeOut()
Specifies a JavaScript script and a time period. The script is executed one time only, after the period elapses.The return value of this method must be held in a JavaScript variable. Otherwise, the timeout object is subject to garbage-collection, which would cause the clock to stop. To cancel the timeout event, pass the returned timeout object to clearTimeOut.
app.clearInterval()
Cancels a previously registered interval initially set by the setInterval method.
In HTML5 forms, the API does not function correctly.
app.clearTimeOut()
Cancels a previously registered time-out interval. Such an interval is initially set by setTimeOut.
In HTML5 forms, the API does not function correctly.
app.eval()
Runs a given script.
app.activeDocs
An array containing the Doc object for each active document. If no documents are active, activeDocs returns nothing; that is, it has the same behavior as d = new Array(0) in core JavaScript.
Returns an empty array for HTMl5 forms.
app.calculate
If true (the default value), calculations can be performed. If false, calculations are not permitted.
Always true for HTMl5 Forms.
app.constants
A wrapper object for holding various constant values. Currently, this property returns an object with a single property, align.
HTML5 forms return an empty align object.
app.focusRect
Turns the focus rectangle on and off. The focus rectangle is the faint dotted line around buttons, check boxes, radio buttons, and signatures to indicate that the form field has the keyboard focus. A value of true turns on the focus rectangle.
Always true for HTML5 forms.
app.formsVersion
The version number of the viewer forms software. Check this property to determine whether objects, properties, or methods in newer versions of the software are available if you want to maintain backward compatibility in your scripts.
11.001 always.
app.language
The language of the running Acrobat viewer.
Always "ENU" for HTMl5 forms.

Supported XFA events supported-xfa-events

The following client sided XFA events are supported:

  • Initialize
  • Validate
  • Calculate
  • Click
  • Enter
  • Exit
  • Change
  • ValidationState
NOTE
HTML5 forms are rendered on the client-side (browser). Use client side validate and calculate scripts instead of server-sided scripts.
recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2