Manually fires a form rule. The list of general rule types for fields/blocks are below, widgets can define their own type ruleType values.
Rule Type |
Rule Name |
click | Click |
focus | Focus |
blur | Blur |
change | Change |
sh | Visibility |
us | Editability |
ok | Validation |
chok | Validation After Change |
eq | Calculation |
md | Mandatory |
md | Mandatory |
dc | Dynamic Class |
Parameters:
Name |
Type |
Argument |
Default |
Description |
ruleType |
string
|
|
|
The rule type to fire. |
itemOrItemId |
string
|
Object
|
|
|
The item or item id that has the rule. |
data |
Object
|
<optional>
|
Form.data
|
The data of the item (can leave as data in most cases). |
responseData |
Object
|
<optional>
|
|
Used to push in data from a data call to an on success or on failure handler. |
Form.focusOnFirstHeading( [element] [, failHandler])
Transfers focus to the first heading on the page. Uses the `tabindex` attribute to determine what heading is first.
If a heading isn't found, this method will call the `failHandler` method (if it exists).
Parameters:
Name |
Type |
Argument |
Description |
element |
string
|
<optional>
|
The element to search for headings. If `undefined`, the method will search globally. |
failHandler |
function
|
<optional>
|
The handler to call if no headings are found. |
Example
Form.focusOnFirstHeading();
Form.getBlockData(item [, data])
Gets a data object of a block's child values.
Useful for dynamic data call parameters.
Only handles simple values of a block's immediate children.
It will not recurse down to create a nested data structure.
Parameters:
Name |
Type |
Argument |
Default |
Description |
item |
string
|
Object
|
|
|
The ID or item reference of the block. |
data |
Object
|
<optional>
|
Form.data
|
Optional data context, if not provided will use the base form data context. |
Returns:
Returns an object of a block's child values.
-
Type
-
Object
Form.getCurrentPageId()
Gets the ID of the current page.
Returns:
Returns the ID of the current page (or a blank string if a page is not initialized).
-
Type
-
string
Examples
When the ID of the page is "page1".
Form.getCurrentPageId();
// => "page1"
When a page is not initialized.
Form.getCurrentPageId();
// => ""
Form.getCurrentPageNumber()
Gets the current visible page number in the navigation menu.
Returns:
Returns the current visible page number or `null` if there are no pages.
-
Type
-
integer
|
null
Examples
On the first page.
Form.getCurrentPageNumber();
// => 1
When there are no pages.
Form.getCurrentPageNumber();
// => null
Form.getDataXml(prettify, excludeSfmData [, dataObj])
Retrieves the form data as an XML string.
Parameters:
Name |
Type |
Argument |
Description |
prettify |
boolean
|
|
If `true`, the XML will be returned in a prettified format. |
excludeSfmData |
boolean
|
|
If `true`, the SFMData will be excluded from the result. |
dataObj |
Object
|
<optional>
|
Used if a specific data object needs to be returned. If blank, the whole form data will be sent. |
Returns:
Returns the form data as an XML string.
-
Type
-
string
Form.getDisplayValue(elementOrId, data)
Gets the display value of an item or element.
Parameters:
Name |
Type |
Description |
elementOrId |
|
Must be an element or an id |
data |
Object
|
Must be provided when passing in an id string |
Returns:
Returns the display value of the item or element.
-
Type
-
string
Form.getEntityData(path [, onlySubmittedData])
Get an entity data object for the given entity path.
Parameters:
Name |
Type |
Argument |
Description |
path |
string
|
|
|
onlySubmittedData |
boolean
|
<optional>
|
|
Returns:
Returns an entity data object.
-
Type
-
Object
Form.getFieldRefPropValue(itemOrPath, prop)
Gets the value of a field targeted by the field ref property of another field.
Parameters:
Name |
Type |
Description |
itemOrPath |
string
|
Object
|
The field with the field ref property |
prop |
string
|
The property name |
Returns:
Returns the current value of the field targeted by the field ref property.
-
Type
-
*
Form.getImagesByName(imageName)
Get all images in the form with the specified name, images with a specified name can have several attributes updated at runtime and the changes will be reflected in the form.
To get help with updating the image items
Parameters:
Name |
Type |
Description |
imageName |
string
|
Image name as defined on an image widget in the form. |
- Since:
-
Returns:
Returns an array of items with the item property 'imageName' that are non-blank.
-
Type
-
Array
Example
When you pass in a data object it is returned when you invoke DynamicData.call("serviceName").
var logos = Form.getImagesByName("orgLogo");
logos.forEach(function (item) {
console.log(item.properties.imgUrl)
} *
Form.getItemFromPath(path)
Return an item object from its data path.
An item object contains an item's label and properties.
Parameters:
Name |
Type |
Description |
path |
string
|
The path to the data of an item e.g. "data.myField". |
Returns:
Returns the item's object.
-
Type
-
Object
Example
Form.getItemFromPath("data.firstName");
// => {
// clearHidden: "no",
// htmlLabel: "First Name",
// id: "firstName",
// jsFiles: [],
// label: "First Name",
// mandatory: false,
// offset: {xs: 0, sm: 0, md: 0, lg: 0},
// path: "FirstName",
// properties: {inputType: "text", maxLength: "", preventCopyPaste: false, placeholder: "", helpText: ""},
// publishOptions: {},
// repeatingData: false,
// span: {md: 6, lg: 6, xs: 12, sm: 12},
// type: "text-input"
// }
Form.getItemProperty(pathOrItem, propName)
Get the value of an item's property.
Parameters:
Name |
Type |
Description |
pathOrItem |
string
|
Object
|
An item or the path of an item. |
propName |
string
|
The name of the property. |
Returns:
Returns the value of the item's property.
Examples
Form.getItemProperty(Form.items.firstName, "inputType");
// => "text"
Form.getItemProperty("data.firstName", "inputType");
// => "text"
Form.getNavPageCount()
Gets the number of the visible pages in the navigation menu.
Returns:
Returns the number of pages visible in the navigaion menu.
-
Type
-
integer
Example
Form.getNavPageCount();
// => 1
Form.getNavPages()
Get an array of pages visible in the navigation menu.
Returns:
Returns an array of the pages visible in the navigation menu.
-
Type
-
Array
Example
Form.getNavPages();
// => [
// { htmlLabel: "Page One", id: "page_one", label: "Page One", … },
// { htmlLabel: "Page Two", id: "page_two", label: "Page Two", … }
// ]
Form.getPathData(path [, source])
Gets the data from an item.
Parameters:
Name |
Type |
Argument |
Default |
Description |
path |
string
|
|
|
The data path of an item, such as "data.myField". |
source |
Object
|
<optional>
|
Form.data
|
The data context to which the path is relative - defaults to Form.data if not supplied |
Returns:
Returns the data found at the specified path.
-
Type
-
Object
Examples
Getting the value from a text field.
Form.getPathData("data.firstName");
// => "David"
When a path doesn't exist.
Form.getPathData("data.someRandomPath");
// => null
Form.getRepeatData(itemOrId, data [, filterMethod])
Gets the data for a given item within a repeat.
Parameters:
Name |
Type |
Argument |
Description |
itemOrId |
string
|
Object
|
|
The data path to the item or the item object within a repeat. |
data |
|
|
The data context from which this method is called from. |
filterMethod |
function
|
<optional>
|
An optional handler to filter the results. |
Returns:
Returns an array of the repeated item's data.
-
Type
-
Array
Form.getSelectionLabel(dataPath, data)
Gets the label of a selection list.
Parameters:
Name |
Type |
Description |
dataPath |
string
|
The data path of the item that has the selection list. |
data |
|
The data source. |
Returns:
Returns the label of the selection list.
-
Type
-
string
Form.getSystemData( [name])
Gets a System Profile value.
Parameters:
Name |
Type |
Argument |
Description |
name |
string
|
<optional>
|
The name of a Sytem Profile property. |
Returns:
Returns the value of a System Profile property, or if the name of a property hasn't been supplied, the entire System Profile object is returned.
-
Type
-
Object
Examples
Form.getSystemData();
// => {
// ComposerDataVersion: "2000-03-31T14:00:00.000Z"
// DisplayMode: "Entry"
// FormCode: "avokabasetemplate"
// FormDataServiceURL: "/maguire/servlet/FormDynamicDataServlet"
// …
// }
Form.getSystemData("FormCode");
// => avokabasetemplate
Form.getSystemData("FakeProperty")
// => null
Form.getXmlPath(item)
Gets the XML path of an item, including path components provided by parent containers.
Parameters:
Name |
Type |
Description |
item |
Object
|
The item to get the XML path for. |
Returns:
Returns the XML path of the item or `null` if the item doesn't exist.
-
Type
-
string
|
null
Examples
Form.getXmlPath(Form.items.firstName)
// => "FirstName"
When the item doesn't exist.
Form.getXmlPath(Form.items.fakeItem)
// => null
Form.goToNextError()
Scrolls to the next error in the form.
Example
Form.goToNextError();
Form.goToPage(pageIdOrNo [, skipValidation] [, skipScrollFocus])
Navigates to the specified page.
Parameters:
Name |
Type |
Argument |
Description |
pageIdOrNo |
string
|
integer
|
|
A page number or ID. |
skipValidation |
boolean
|
<optional>
|
If `true`, page validation will be skipped. |
skipScrollFocus |
boolean
|
<optional>
|
If `true`, the default scrolling and focus management will be skipped. |
Returns:
Returns a promise that resolves if the page changes successfully.
-
Type
-
Promise
Form.hasRule(ruleType, itemOrItemId)
Checks if the specified rule type has been assigned to the specified item.
Parameters:
Name |
Type |
Description |
ruleType |
string
|
The type of rule to check for. |
itemOrItemId |
string
|
Object
|
|
Returns:
Returns `true` if the specified rule type exists for the specified item.
-
Type
-
boolean
Example
Checking if the Form component has a "load" rule.
// Referring to the item itself
Form.hasRule("load", Form.items.AvokaSmartForm);
// Referring to the ID of the item
Form.hasRule("load", "AvokaSmartForm");
Form.hasRuleInAncestry(ruleType, itemOrId)
Checks if the specified rule type has been assigned to the specified item or any of the specified item's ancestors.
Parameters:
Name |
Type |
Description |
ruleType |
string
|
The type of rule to check for. |
itemOrId |
string
|
Object
|
|
Returns:
Returns `true` if the specified rule type exists for the specified item or for any of the specified item's ancestors.
-
Type
-
boolean
Form.isAuthenticatedUser()
Checks if the form was opened from an authenticated user session.
Returns:
Returns `true` if the user is authenticated.
-
Type
-
boolean
Examples
When the user is authenticated.
Form.isAuthenticatedUser();
// => true
When the user is not authenticated.
Form.isAuthenticatedUser();
// => false
Form.isFieldWorker()
Checks if the form is running within the context of Avoka Transact Field App.
Returns:
Returns `true` if the form is hosted in Avoka Transact Field App.
-
Type
-
boolean
Form.isStep(steps)
Checks if the current collaboration job step name equals a supplied string or is an item in a supplied array.
Parameters:
Name |
Type |
Description |
steps |
string
|
Array
|
A step name (as a string) or an array of step names. |
Returns:
Returns `true` if the current collaboration job step name equals a supplied string or is an item in a supplied array.
-
Type
-
boolean
Form.isVisible(itemOrId, data)
Determine if the given item is visible for the given data context based on the form's visibility rules.
Parameters:
Name |
Type |
Description |
itemOrId |
string
|
Object
|
|
data |
|
|
Returns:
Returns `true` if the item -- or any ancestor of the item -- is visible. Does NOT take account of other non-visibility-rule mechanisms such as whether the item is on another page,
or other similar native-component internal display logic.
-
Type
-
boolean
Examples
When items are visible.
Form.isVisible(Form.items.firstName)
// => true
Form.isVisible("data.firstName")
// => true
When items are not visible.
Form.isVisible(Form.items.firstName)
// => false
Form.isVisible("data.firstName")
// => false
Form.loadAllPages()
Loads all pages of a dynamic page loading form.
Returns:
-
Type
-
Promise.<void>
Form.loadCachedData(cache [, data])
Loads the provided cache (made using cacheData) into the provided data context
or the top level form data if none provided.
Parameters:
Name |
Type |
Argument |
Default |
Description |
cache |
|
|
|
|
data |
Object
|
<optional>
|
Form.data
|
|
Form.loadPage(id)
Dynamically loads a page.
Parameters:
Name |
Type |
Description |
id |
string
|
|
Form.redirect(redirectTarget [, redirectParent])
Redirects the form to a URL.
Parameters:
Name |
Type |
Argument |
Description |
redirectTarget |
string
|
|
The URL to redirect to. |
redirectParent |
boolean
|
<optional>
|
If `true`, the window's parent will be redirected. |
Examples
Form.redirect("https://google.com")
Form.redirect("https://google.com", true)
Form.removeRepeatInstance(item, data [, index] [, transferFocus])
Removes an instance from a repeatable item.
Parameters:
Name |
Type |
Argument |
Description |
item |
string
|
Object
|
|
The repeat item, can be a data path, item id or the item object |
data |
Array
|
|
The data context array of the repeat data or the data of the instance. E.g. data.repeat or data (to delete an instance from within a repeat) |
index |
integer
|
<optional>
|
The index to delete. If not supplied the last instance will be removed. If within a repeat and not supplied, the current index will be removed. |
transferFocus |
boolean
|
<optional>
|
If `true`, focus will be transfered to the previous repeat instance. |
Notifies Transact Manager that the form is attempting to acess another saved submission. Will redirect if successful.
Parameters:
Name |
Type |
Description |
validationRefId |
string
|
ID of the item to validate, usually the container of the tracking code and save challenge fields. |
trackingCodeId |
string
|
The Tracking Code of the submission |
challengeAnswerId |
string
|
The challenge answer required, set to blank if not set. |
Form.setInstanceCount(item, repeatData, desiredCount)
Modifies the current instance count to match the desired count. Instances are added or removed make the number of instances match the count.
Parameters:
Name |
Type |
Description |
item |
string
|
Object
|
The repeat item, can be a data path, item id or the item object |
repeatData |
|
The data context array of the repeat data. E.g. data.repeat |
desiredCount |
integer
|
The requested number of instances |
Form.setPathData(path, data [, source])
Sets the data of an item.
Parameters:
Name |
Type |
Argument |
Default |
Description |
path |
string
|
|
|
The path to the data item. |
data |
*
|
|
|
The data value to assign to the item. |
source |
Object
|
<optional>
|
Form.data
|
The data context to which the path is relative - defaults to Form.data if not supplied |
Examples
Set the value of a text field to "David".
Form.setPathData("data.firstName", "David");
Set the value of a checkbox to `true`.
Form.setPathData("data.termsAndConditions", true);
Set the value of a numeric field to `6000`.
Form.setPathData("data.creditLimit", 6000)
Form.setSystemData(name, value)
Sets a System Profile value. An existing value can be overriden or a new value can be created.
Parameters:
Name |
Type |
Description |
name |
string
|
The name of the System Profile data, can be separated by dots. |
value |
string
|
The value to set the system value to. |
Examples
Overriding an existing value.
Form.setSystemData("FormCode", "MyCustomFormCode");
Creating a new value.
Form.setSystemData("CustomSystemData", "SomeCustomValue");
Form.showAccessibleAlert(message, expanded [, delay])
Alerts a message to a screen reader.
Parameters:
Name |
Type |
Argument |
Default |
Description |
message |
string
|
|
|
|
expanded |
boolean
|
|
|
If `true`, an `aria-expanded` attribute will be added to the alert. |
delay |
integer
|
<optional>
|
300
|
A delay (in milliseconds). |
Form.showDialog(id)
Shows the specified dialog.
Parameters:
Name |
Type |
Description |
id |
string
|
The ID of a dialog. |
Example
Form.showDialog("dialog_id_goes_here");
Form.showModal(id [, showAscAlert])
Shows the specified modal page.
Parameters:
Name |
Type |
Argument |
Description |
id |
string
|
|
The ID of a modal page. A blank string will close an open modal page. |
showAscAlert |
boolean
|
<optional>
|
For accessibility purposes, this will alert the page that has loaded when closing a modal page |
Example
Form.showModal("modal_id_goes_here");
Form.showProgress(message)
Shows an indeterminate progress indicator.
Parameters:
Name |
Type |
Description |
message |
string
|
The message to display in the progress indicator. |
Example
Form.showProgress("Something is happening...");
Form.submit( [type], legacyMethod, skipPostSubmit [, validateItem], sendEmail, backgroundSave, skipScrollOnError)
Submits, saves, or abandons a form.
Parameters:
Name |
Type |
Argument |
Default |
Description |
type |
string
|
<optional>
|
"Submitted"
|
Abandoned / Saved / Submitted. |
legacyMethod |
boolean
|
|
|
Use old-school HTML form post instead of AJAX - redirects to submission complete page, so there is no return value. |
skipPostSubmit |
boolean
|
|
|
Setting to true will stop the form from going to a success modal page or redirecting |
validateItem |
|
<optional>
|
|
Provide an item to validate, will validate the whole form on Submitted type if not provided |
sendEmail |
boolean
|
|
|
the optional send email (form saved, receipt). |
backgroundSave |
boolean
|
|
|
sets backgroundSave parameter to true for non user initiated saves. |
skipScrollOnError |
boolean
|
|
|
Setting to true will stop the form from scrolling to the error block on validation errors. |
Returns:
A promise of the result.
-
Type
-
Promise
Example
// After validating the Item this will submit the form using a AJAX call with a success modal page.
Form.submit("Submitted", false, false, Item, true, true, false);
Form.term(path, defaultTo)
Provide the value of the given path (e.g. 'myTextField.label' or 'myDatePicker.properties.placeholder')
in the currently selected language. If no language entry exists, return the default value.
Generated scripts are converted to use this for translatable strings.
Parameters:
Name |
Type |
Description |
path |
string
|
|
defaultTo |
string
|
If no term exists for the given path, return this string instead. |
Returns:
-
Type
-
string
Form.updateBranding(brandOptions)
Update branding on the form based on the options in the JSON brandOptions. This also broadcasts the AngularJS event "brandUpdate"
Parameters:
Name |
Type |
Description |
brandOptions |
RuntimeBrandUpdate
|
JSON object or string with details to update the form branding |
- Since:
-
Form.updateCssByName(cssId, cssUrl, cssContent)
Update named CSS with either a new URL or CSS content, switching between a URL and a CSS string will remove the previous link or style tag as appropriate and replace it with the one based on the update required.
Parameters:
Name |
Type |
Description |
cssId |
string
|
ID of CSS to update as defined in the ID property on a Runtime CSS Resource widget in the form. |
cssUrl |
string
|
New URL for the CSS to use, eg using a relative URL like "./css/myCustomCss.css" will get the image from the FAR file. Setting the URL takes priority over setting CSS Content. |
cssContent |
string
|
New CSS content to inject into a style tag for the CSS name. |
- Since:
-
Returns:
Indicates whether any changes were made with the specified details.
-
Type
-
boolean
Examples
Passing in a CSS file name will can update the link tag source.
Form.updateCssByName("myCustomCss", "./css/anotherCssFile.css");
Passing in a CSS content string will update the form with the contents being added to a style tag.
Form.updateCssByName("myCustomCss", null, "h1 { color: yellow !important; }");
Form.updateData(newFormData)
Takes new form XML data (usually in a response from the new TM HTTP API) and updates the form's internal data structure.
Parameters:
Name |
Type |
Description |
newFormData |
string
|
|
Returns:
-
Type
-
Promise
Form.updateImageByName(imageName, newValues)
Update images in the form by its name specified on the image, Images with a specified name can be updated at runtime by modifiying their properties
Parameters:
Name |
Type |
Description |
imageName |
string
|
Image name as defined on an image widget in the form. |
newValues |
RuntimeImageUpdate
|
New values to set on images with the specified name |
- Since:
-
Returns:
Indicates whether any images were found and updated with the specified details.
-
Type
-
boolean
Example
Passing in an image name you can update the image source.
Form.updateImageByName("orgLogo", {
imgUrl: "./images/logo2.png"
});
Form.validate(itemOrId [, data] [, trigger])
Runs validation on given field (and its children) and broadcasts validation display event.
If the item does not exist or is invalid, the whole form will be validated.
Parameters:
Name |
Type |
Argument |
Default |
Description |
itemOrId |
string
|
Object
|
|
|
An id or item reference to the block/field to run the validation on. |
data |
object
|
<optional>
|
Form.data
|
The data reference to the block/field to run the validation on. |
trigger |
string
|
<optional>
|
|
Used by Transact Insights to send a validation event. |
Returns:
Returns a promise that contains the validation result object. The "valid" key on this object will be `true` or `false`. The "errors" key will contain a list of errors.
-
Type
-
Promise
Form.validateFieldRefMap(inputFieldRefs, data, alertMessage)
Validates all the fields in a field reference map property.
Parameters:
Name |
Type |
Description |
inputFieldRefs |
|
A reference to the fieldRefMap property. |
data |
Object
|
A reference to the form data. |
alertMessage |
string
|
A message to show the user if validation fails. |
Returns:
Returns a promise of the result.
-
Type
-
Promise