Formatic
vRC-1.0GitHub

Data API

The Data API allows you, as a developer, to hook in to the internals to access and manipulate the data within the rendered form. Exposed as a Data class object, when passed through to the Form component as a prop, exposes various helper functions which you can call to programmatically alter form behavior.

Note

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

Overview

Importing

A Data class object is exported by the SDK. Thus, to import in to your project:

import Formatic, { Data } from '@formatic/sdk';

Passing as a prop

To access, you’ll need to create an instance of the Data class and pass it through as a prop at the point in which the Formatic component is rendered:

constructor(props) {
  super(props);

  this.state = {
    data: new Data()
  };
}

render() {
  return (
    <Formatic data={this.state.data} {...this.props} />
  )
}

Note

The above example simply demonstrates the fact that an instance of the Data class needs to be instantiated and passed through as a prop.

To view a working example, see our Sample React App.

Reference

Properties

Functions

store

Returns an instance of the Redux store used internally within the component. For more information, see State Management.

client

Returns an instance of the Apollo Client, a GraphQL client used to sync data with our remote server. For more information, see State Management.

getCurrentPageID()

Data.getCurrentPageID()

Returns the ID of the page the user is currently active on. If the form is configured to render as a single page application (which renders out multiple forms pages vertically under each other), function will return the ID of the last page rendered on the user’s screen.

Returns a 24 character alphanumeric String.

getEmitter()

Data.getEmitter()

Returns an instance of the Pub/Sub Emitter.

getSubmissionID()

Data.getSubmissionID()

Returns a 40 character alphanumeric ID String that uniquely identifies the current user’s form session.

getEnvironment()

Data.getEnvironment()

Returns a String containing the environment the form was instantiated with. By default, the form environment is often set to Live.

getFieldValues()

Data.getFieldValues(idAsKey = true)

Returns an Object containing key value pairs of the user’s form field values.

Parameters

  • idAsKey Boolean optional If set to true, the key of the returned object is set to the field’s ID. When set to false, the key of the returned object is set to the field’s tag.

getFieldValue(id)

Data.getFieldValue(id)

Returns the value of the field if set, and null if not. The return type is dependent on the component in which the field refers to. For more information on the return type, see Components.

Parameters

  • id String Either the field ID or tag. Higher priority is given to the field ID. If there’s a conflict between the field ID and tag, the field with the corresponding ID will be returned.

getFieldErrors()

Data.getFieldErrors(idAsKey = true)

Returns a key value Object containing the error Strings that are currently visible on the user’s screen. If no errors are visible, will return an empty Object.

Parameters

  • idAsKey Boolean optional If set to true, the key of the returned object is set to the field’s ID. When set to false, the key of the returned object is set to the field’s tag.

getFieldError()

Data.getFieldError(id)

For a given field rendered on the user’s page, returns the error as a String if exists, and false if not.

Can either pass through the field ID or its tag for the id parameter, however higher priority is given to the field ID (and thus if there’s a conflict between the field ID/tag, it will prioritize field ID).

Note

If an ID of a field that is not currently rendered on the user’s screen is passed through, will return false.

getFieldTags()

Data.getFieldTags(idAsKey = true)

Returns an Object of field tags.

Parameters

  • idAsKey Boolean optional If set to true, the key of the returned object is set to the field’s ID. When set to false, the key of the returned object is set to the field’s tag.

Note

Tags are generally easier to work with and remember, however IDs are often useful to know for programmatic purposes, as they’re guaranteed to never change. Therefore getFieldTags() provides an easy way to look up a field’s ID given a tag, or vice versa.

getChannel()

Data.getChannel()

Returns the channel as a String that the form was instantiated on. Refers to the value passed through to the component as a prop.

For more information, see Components.

getFormAttributes()

Data.getFormAttributes()

Returns a key value Object referring to the form attributes (settings). By default, will return an object with the following properties set:

  • channel - the channel the form was instantiated with. Will return the same value as getChannel().
  • snapshot - contains details of the current, published version of the form. Includes ID, environment, created time, description and version.
  • variables - contains variables/tokens that are able to be used throughout the form. More more information, see tokens.

Will also contain any custom settings that have been configured through the cloud dashboard.

getFormAttribute()

Data.getFormAttribute(
  key, 
  defaultValue = null
)

Given a key, returns the corresponding form attribute setting. If the attribute does not exist, will return the defaultValue parameter, which defaults to null.

Parameters

  • key String The attribute to retrieve (e.g. channel).
  • defaultValue Boolean optional What to return if no attribute was found for the supplied key. Defaults to null.

Note

The return type can vary depending on the returned attribute.

getField()

Data.getField(id)

Returns the field Object if exists, null if not. The returned Object contains:

  • attributes - key value Object of Field settings.
  • id - alphanumeric String of the Field ID.
  • renderer - the component that is set to render the Field. For more information, see Components.

Parameters

  • id String Either the field ID or tag. Higher priority is given to the field ID. If there’s a conflict between the field ID and tag, the field with the corresponding ID will be returned.

Note

Does not return the value of the Field, but rather its Object definition.

It will also return an Object for all Fields that exist within the form definition, regardless of whether or not they’re currently rendered on the user’s page.

getSection()

Data.getSection(id)

Returns the Section Object if exists, null if not. The returned Object contains:

  • attributes - key value Object of Section settings.
  • fields - Array of all fields that belong to the section. However, does not necessarily correspond to fields that are currently visible within the section. If a field has visibility options that mean it is currently invisible or not rendered, it will still be returned within this Array.
  • id - alphanumeric String of the field ID.

Parameters

  • id String The ID of the section to return.

getPage()

Data.getPage(id)

Returns the Page Object if exists, null if not. The returned Object contains:

  • attributes - key value Object of Section settings.
  • id - alphanumeric String of the field ID.
  • sections - Array of all Sections that belong to the Page. However, does not necessarily correspond to Sections that are currently visible within the Page. If a Section has visibility options that mean it is currently invisible or not rendered, it will still be returned within this Array.

Parameters

  • id String The ID of the page to return.

getRenderedFields()

Data.getRenderedFields()

Returns an Array of all field IDs that are currently rendered and visible on the user’s page.

setFieldValue()

setFieldValue(
  id,
  value,
  timestamp = Date.now()
)

Updates a value for a given field within the current users active session. Will completely override the current value, therefore if you want to update a field’s value which is stored as an object, you will first need to retrieve the current value, update the object accordingly, and pass it through the value attribute. timestamp refers to the internal timestamp which is recorded against the value update. Defaults to the current time.

For more information on the structure of different component’s data values, see Components.

Parameters

  • id String The ID of the field to update.
  • value Any The value to set. Can be of any type.
  • timetamp Number optional A Number representing the milliseconds elapsed since the UNIX epoch. Used to set the modification time of the field value.