Pub/Sub Emitter

The Emitter object enables you to subscribe to various events that are published internally within the form lifecycle. Typically it’s used to be notified when various events occur:

// Be notified of all value changes
emitter.on(Events.ValueChanged, (data) => {
  console.log(`Value changed from ${data.oldValue} to ${data.newValue}`);
});

Note

During Release Candidate phase, the following specification is liable to change without notice. Upon an initial 1.0.0 release, SemVer versioning guidelines will be maintained.

Setup

An instance of the emitter is made available through the Data.getEmitter() function. Event constants are also exported from the library through an Events object. Thus, to subscribe to events:

import React, { Component } from 'react';
import Formatic, { Data, Events } from '@formatic/sdk';

class App extends Component {
  constructor() {
    super();
    this.state = {
      data: new Data(),
    };
  }

  componentDidMount() {
    const emitter = this.state.data.getEmitter();
    emitter.on(Events.ValueChanged, (data) => {
      console.log(`Value changed from ${data.oldValue} to ${data.newValue}`);
    });
  }

  render() {
    const { data } = this.state;

    return (
      <div>
        <Formatic data={data} {...props}/>
      </div>
    );
  }
}

Note

As the data prop is only initialized as the component is being mounted, subscriptions need to be configured in the above example in the componentDidMount() method. If you attempted to configure within the constructor, for example, you would receive an error stating data.getEmitter() is undefined.

Reference

• on()
• off()
• emit()

on()

emitter.on(
  type,
  handler
)

Register an event handler for the given type.

Parameters

• type String Type of event to listen for, or "*" for all events
• handler Function Function to call in response to given event

off()

emitter.off(
  type,
  handler
)

Remove an event handler for the given type.

Parameters

• type String Type of event to deregister handler from, or "*"
• handler Function Handler function to remove

emit()

emitter.emit(
  type,
  evt
)

Invoke all handlers for the given type. If present, "*" handlers are invoked after type-matched handlers.

Parameters

• type String The event type to invoke
• evt Any? Any value (object is recommended and powerful), passed to each handler

Events

• AnalyticsCallback
• BeforePageRender
• FieldError
• NextPage
• PageRender
• PrevPage
• SessionCompleted
• SessionStarted
• ValueChanged

AnalyticsCallback

emitter.on(Events.AnalyticsCallback, data => handler)

Published whenever an analytics event is recorded. An analytics event refers to a data packet that is sent up to the Formatic cloud servers for analytical purposes. Whilst it does not contain personally identifiable information, it does contain data relating to user behavior.

Data

• time Number Time the event was published in milliseconds, as returned by new Date().getTime().
• event String Name of the published analytics event.
• params Object Object of data related to the event.

Event Types

The AnalyticsCallback event is unique, in that it itself describes a set of events. The following event types (passed through the event attribute above) are as follows:

Note

As we use the below events and data for analytical purposes within our cloud app, we are liable to add and remove data between releases, and do not consider doing so a violation of our SemVer guidelines. Therefore we do not recommend the AnalyticsCallback event for implementing custom behavior within your application, but would recommend the other events, which are SemVer compliant.

onBlur

Published when focus on a Form field is lost. Returns a params object with:

• fieldId String ID of the field whose focus was lost.

onFocus

Published when focus on a Form field is attained. Returns a params object with:

• fieldId String ID of the field whose focus was attained.

onFieldError

Published when focus on a Form field is lost. Returns a params object with:

• fieldId String ID of the field whose focus was lost.

onValueChange

Published when a field value is changed. Returns a params object with:

• fieldId String ID of the field whose value was changed.
• valueLength Number The length of the value, if that value is a simple string/number. Components whose data is not stored as a simple value can implement their own valueLength value.

Note

The above onValueChange analytics event demonstrates how no personally identifiable information is sent up to our server. Rather than sending up the value, which could contain sensitive information, we simply send up the valueLength attribute.

onWindowBlur

Published when focus on the window is lost. Returns a params object with:

• pageId String ID of the active page at the point in time the event was published.

onWindowFocus

Published when focus on the window is gained. Returns a params object with:

• pageId String ID of the active page at the point in time the event was published.

onWindowClose

Published when the window is unloaded. Returns a params object with:

• pageId String ID of the active page at the point in time the event was published.

onFormComplete

Published when the user’s active form session is marked as complete. Returns a params object with:

• pageId String ID of the active page at the point in time the event was published.

BeforePageRender

emitter.on(Events.BeforePageRender, data => handler)

Published immediately before a page is to be rendered on the DOM.

Data

• id String The page that is about to be rendered.

Note

Does not fire when you navigate back on a single-page form if the page is already visible in the DOM.

FieldError

emitter.on(Events.FieldError, data => handler)

Published when a field triggers an error. If inline validation is set to true, this will get triggered as the user is filling out the form. Otherwise it will trigger when the user attempts to navigate to the next page.

Data

• fieldID String The ID of the field that triggered the error.
• message String The error message.

NextPage

emitter.on(Events.NextPage, data => handler)

Published immediately before the user navigates to the next page, generally when the user clicks the Next Page button.

Data

• oldPage String The ID of the page the user is navigating from.
• newPage String The ID of the page the user is navigating to.

PageRender

emitter.on(Events.PageRender, data => handler)

Published immediately after a page has been rendered on the DOM.

Data

• id String The page that was rendered.

Note

Does not fire when you navigate back on a single-page form if the page is already visible in the DOM.

PrevPage

emitter.on(Events.PrevPage, data => handler)

Published immediately before the user navigates to the previous page, generally when the user clicks the Back Page button.

Data

• oldPage String The ID of the page the user is navigating from.
• newPage String The ID of the page the user is navigating to.

SessionCompleted

emitter.on(Events.SessionCompleted, data => handler)

Published when the active form session has been completed.

Note

This has not been implemented as part of the first release candidate, but will be implemented in the subsequent release.

SessionStarted

emitter.on(Events.SessionStarted, data => handler)

Published when the user’s form session is started, generally on page load. Gets triggered after the initial API request to Formatic. If no submission ID currently exists for the user, the server generates a session and returns it. If a submission ID has previously been created, the server confirms details are correct and returns it.

Data

• isNew Boolean Whether or not the submission is newly created, or the user is initializing a previously started session. This will be true only once per submission ID (when it is newly created), otherwise will be set to false. Useful for bootstrapping a submission.
• submissionID String The ID of the submission as returned by the server.

ValueChanged

emitter.on(Events.ValueChanged, data => handler)

Published when a field value changes. This is a local trigger. It does not wait for confirmation from the server to confirm the value change went through (thus should be used carefully).

Data

• fieldID String ID of the field who’s value changed.
• oldValue Any? The field value prior the change. Will be set to the component default value if being changed for the first time. For more information, see Components.
• newValue Any? The field value before the change.