Namespace: Form

Form

Methods


Form.addPreviewDDSData(serviceName, dataOrHandler)

Add stub to handle DynamicData calls within preview
Parameters:
Name Type Description
serviceName string Service name to mock up for DynamicData.call() or Transact function call type
dataOrHandler Object | function Result object or handler function that allows conditional results based on parameters
Since:
  • Maestro 20.11.0
Examples

When you pass in a data object it is returned when you invoke DynamicData.call("serviceName").

Form.addPreviewDDSData("myService", { 'prop1': 'myValue' } );
DynamicData.call("myService").then(function(result) {
    // when this is called result will be { 'prop1': 'myValue' }
}

When you pass in a function, it gets the params passed in so you can do conditional logic to test different paths.

Form.addPreviewDDSData("myService", function(params) {
    if (params.myProp == "someValue") {
        return { operationResult: "success" }
    } else {
        return { operationResult: "failure" }
    }
 } );
DynamicData.call("myService", { myProp: "someValue" }).then(function(result) {
    // result.operationResult == "success"
}

Form.addRepeatInstance(item, repeatData [, transferFocus])

Adds an instance to a repeatable item. You can optionally cause focus to be transferred to the first focusable field of the new instance.
Parameters:
Name Type Argument Description
item string | Object The repeat item, can be a data path, item id or the item object.
repeatData Array The data context array of the repeat data. E.g. data.repeat
transferFocus boolean <optional>
If `true`, focus will be transferred to the next instance.
Returns:
Returns the repeat data instance object.

Form.availableRoutes()

Gets a form's available job routes.
Returns:
Returns an array of the available job routes in the form.
Type
Array

Form.backgroundSave()

Performs a background save of the form data to Transact Manager.
Returns:
Returns a promise of the result.
Type
Promise
Example
Form.backgroundSave();

Form.cacheData(itemOrId [, data])

Gets a cache of data from the specified item in the specified data context.
Parameters:
Name Type Argument Default Description
itemOrId string | Object
data Object <optional>
Form.data
Returns:
Returns the cache of data for the specified item.
Type
Object

Form.clearValidationErrors(itemOrId [, data])

Clears validation on the provided field (and its children) and broadcasts the validation display event.
Parameters:
Name Type Argument Default Description
itemOrId string | Object An id or item reference to the block/field to clear the validation on.
data object <optional>
Form.data The data reference to the block/field to clear the validation on.

Form.convertToFieldDataMap(fieldRefMap, data)

Takes in the fieldRefMap property array and converts to an object which can be used for dynamic data calls
Parameters:
Name Type Description
fieldRefMap A property reference to the fieldRefMap.
data Object The data source.
Returns:
Returns an object that can be used in a dynamic data call.
Type
Object

Form.copyData(fromItem, fromData, toItem, toData)

Copies the values of component fields from one item (and its data context) to another. Item component types must match and have been published with pubIds. Ignores any fields not in the component definition.
Parameters:
Name Type Description
fromItem string | Object An id or item reference to the source item.
fromData A reference to the source data.
toItem string | Object An id or item reference to the target item.
toData A reference to the target data.

Form.emailOperation(operationName [, opItemId], emailAddressId, senderNameId, emailBodyId)

Notifies Transact Manager that the form an email to be sent.
Parameters:
Name Type Argument Description
operationName string emailShareForm, emailSavedForm or emailReceipt.
opItemId string <optional>
If set the response will set a $responseStatus and $responseMessage on the data item specified.
emailAddressId string The email addresses to send to, these will get validated (Must be in an email field).
senderNameId string The senders name.
emailBodyId string The email body.
Returns:
Returns a promise of the result.
Type
Promise

Form.fireRule(ruleType, itemOrItemId [, data] [, responseData])

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
clickClick
focusFocus
blurBlur
changeChange
shVisibility
usEditability
okValidation
chokValidation After Change
eqCalculation
mdMandatory
mdMandatory
dcDynamic 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:
  • Maestro 21.11.0
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.

Form.resumeForm(validationRefId, trackingCodeId, challengeAnswerId)

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

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