Maestro API Reference Namespace: 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
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:

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