Skip to main content

Version: 23.10

Narrator Controller component

The Narrator Controller component is responsible for enforcing the Narrative and controlling the form behavior on the client-side. It simplifies the task of using a Journey Narrative.

JavaScript functions

The controller adds a JavaScript library named Narrator to the Template/Form. The Narrator library contains the following functions.





Valid directions are forward and back.
Forward navigation attempts to move the Narrative to the next page, while backward navigation returns to the previous page (if back navigation is enabled on the current page).

Narrative metadata

The Narrative maintains metadata in the application XML to indicate its current state.


The Template and Form must only read from this data. Never write to it.

The Narrative metadata is stored within the SFMData element, and is accessible via XPath or directly as an item in a Maestro rule. For example:

  • XPath: //AvokaSmartForm/SFMData/NarrativeMeta
  • Form Location:


The name of the current Narrative Page.
The action that the Form is requesting the Narrative make. For example, 'forward' to move forward.
This is set via the Narrator Controller. Never set this manually.
The message that the Narrative wants the Form to display in its loading dialog.
A map of page names and booleans indicating whether each page is to be visible ("true") or hidden ("false").
Whether submissions are permitted from the current page.
Whether saving is permitted from the current page.
Whether back navigation is permitted from the current page
Whether a fatal error has occurred. If true, the form cannot progress. This is watched by the Narrator Controller's FatalError Rule.


<?xml version="1.0" encoding="UTF-8"?>
<!-- other elements omitted -->
<!-- other elements omitted -->

Handling Errors

Certain errors that occur on the server (Narrative) are considered unrecoverable. For example:

  • Any unhandled exception is thrown when calling an Action.
  • An Action name and version have been configured in the Narrative, but the corresponding Transact Function can't be found.

These kinds of errors are considered fatal errors because they prevent an application from being completed and the error cannot be resolved by code or the applicant. By default, fatal errors trigger the On Fatal Error rule on the Narrator Controller which, by default, will immediately submit the application.

The default code in the rule is:


We recommend that your Template be set up to handle these cases by presenting an error Modal Page, so that the default submission confirmation page is not displayed. You can do this in your Template by adding a new Modal Page and modifying the On Fatal Error rule as follows:

Form.showModal("your modal error page"); // Add this line