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.

Narrator.navigate(direction)

Synopsis

Narrator.navigate(direction)

Parameters

Parameter	Description
direction	String 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.

note

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: Form.data.SFMData.NarrativeMeta

Properties

Name	Description
CurrentPage	String The name of the current Narrative Page.
Action	String 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.
PageWaitMessage	String The message that the Narrative wants the Form to display in its loading dialog.
PageVisibility	Object A map of page names and booleans indicating whether each page is to be visible ("true") or hidden ("false").
DisableSubmit	Boolean Whether submissions are permitted from the current page.
DisableSave	Boolean Whether saving is permitted from the current page.
DisableBack	Boolean Whether back navigation is permitted from the current page
FatalError	Boolean Whether a fatal error has occurred. If true, the form cannot progress. This is watched by the Narrator Controller's FatalError Rule.

Example

<?xml version="1.0" encoding="UTF-8"?>
<Root>
  <AvokaSmartForm>
    <!-- other elements omitted -->
    <SFMData>
      <!-- other elements omitted -->
      <NarrativeMeta>
        <CurrentPage>YourDetails</CurrentPage>
        <Action>forward</Action>
        <PageWaitMessage/>
        <PageVisibility>{"LetsGetStarted":"true","YourDetails":"true","KYC":"false","Legal":"true"}</PageVisibility>
        <DisableSubmit>false</DisableSubmit>
        <DisableSave>false</DisableSave>
        <DisableBack>false</DisableBack>
        <FatalError/>
      </NarrativeMeta>
    </SFMData>
  </AvokaSmartForm>
</Root>

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:

Transact.userSubmit();

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:

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