Module: state-store

The state store can keep track of any JSON-style data object for other modules to access and use.

The state store is used as centralized data storage for all modules, especially when concerning data that is shared among 2 or more modules. When individual modules need to update specific data, modifications through the state store ensure that other modules that need to be aware of the latest available data can do so without specific input from the module changing it.

The state store can store any number of states, as defined by a data string. See module:event-store#event:ModifyState. It is able to associate any data object with that particular state, although it is optimized to store key-value Objects.

Example

var StateStore = require('state-store.js');

// a generic Viewer constructor
function Viewer(opts) {
    // other modules will expect this to be present
    this.stateStore = StateStore(this);
}

(require("state-store"))(viewer)

Creates and initializes the state store.

Parameters:

Name	Type	Description
`viewer`	Core	The core viewer to which the module will attach.

Fires:

module:event-store#event:StateModified

Listens to Events:

module:event-store#event:ModifyState

Members

(inner) FieldList

The known set of fields and metadata on the form.

Example

var fieldList = viewer.stateStore.getState('FieldList');

Properties:

Name Type Attributes Default Description

templateDocumentId

string

The unique id used to determine which document belongs to the form. The form cannot be loaded if this value is not defined.

formName

string

The display name of the form.

formDefinitionId

string

The unique id to use to save the form to the server.

formRoles

Object

A hash object used to store and access the metadata for each role in the form. The key for this hash object is the formRoleId of the form role.

Properties

Name	Type	Description
`formRoleId`	string	The id of the form role.
`displayName`	string	A friendly name for the form role.
`fieldColor`	string	The color to use for any field to which the form role is assigned, as a pound sign followed by a 6 character hexadecimal color code.
`sortIndex`	number	A number representing the sorting order of the form role.

groups

Object

A hash object used to store and access the metadata for each group in the form. The key for this hash object is the groupId of the group.

Properties

Name Type Attributes Description

groupId

string

The id of the group.

displayName

string

A friendly name for the group.

type

string

The data type of the group. Possible values are:

checkbox

data

Object

Data associated with the group.

Properties

Name	Type	Description
`multiple`	boolean	Indicates whether or not the group allows multiple selections.

readOnly

boolean

Indicates whether this group is read only when signing the form.

required

boolean

Indicates whether this group is required when signing the form.

formRoleId

string

The form role id associated with the group.

fieldList

Object

A hash object used to store and access the metadata for each field in the form. The key for this hash object is the markId of the viewer mark.

Properties

Name Type Attributes Description

markId

number

The viewer mark associated with the form field.

fieldId

string

A unique id for that field.

displayName

string

A friendly name for the field.

template

string

The data type of the field. Possible values are:

SignatureTemplate
InitialsTemplate
TextTemplate
DateTemplate
CheckboxTemplate

required

boolean

Indicates whether this field is required when completing the form.

readOnly

boolean

Indicates whether this field is read-only when completing the form.

horizontalAlignment

string

Indicates the horizontal Alignment of text within the field Possible values are:

left
center
right

sortIndex

number

A number representing the sorting order of the field, when displaying an ordered list.

pageNumber

number

The page number where the field is located.

pageData

Object

Represents metadata about the page at the time when the field rectangle was created or updated.

Properties

Name	Type	Description
`width`	number	The width of the page.
`height`	number	The height of the page.

rectangle

Object

The location of the field on the document.

Properties

Name	Type	Description
`x`	number	The x-coordinate of the top-left of the field in respect to the document.
`y`	number	The y-coordinate of the top-left of the field in respect to the document.
`width`	number	The width of the field.
`height`	number	The height of the field.

fontName

string

The font name to use for TextTemplate and DateTemplate fields.

fontColor

string

The font color to use for TextTemplate and DateTemplate fields, as a pound sign followed by a 6 character hexadecimal color code.

multiline

boolean

Indicates whether or not the field is multiline. This property is only used for TextTemplate fields.

characterLimit

number

The amount of characters that can be entered in a TextTemplate field. It is a whole number greater than or equal to 0 that indicates the maximum number of characters allowed in a text field when completing the form, with 0 indicating that there is no limit.

formRoleId

string

The id of the form role associated with the field.

groupId

string

The id of the group that contains the field.

defaultValue

string | Object

The default value of the field to be added when the form is loaded. If it is a TextTemplate, this value should be a string. If it is a DateTemplate, it should be an ISO formatted date string (e.g. 2016-11-16T18:23:08.030Z). The format will be dictated by the globalSettings.signatureDateFormat property. If it is a CheckboxTemplate, it may only be "" or "checked". If it is a signature, it should be an object with the following properties:

Properties

Name	Type	Attributes	Description
`type`	string	<optional>	The type of signature that will be placed in the field. Can be "text" for a text signature or "path" for a freehand signature.
`value`	string	<optional>	For a text signature, this is the actual text that will be in the signature. For a path signature, this is a subset of the SVG path standard, only including the M, L, and C commands (e.g. M0,0L1,1L1,0).
`fontName`	string	<optional>	The font to be used to render the signature. This is required for text signatures but does not apply to path signatures.

value

string | Object

The value of the field. This property is only used in the ESigner and is undefined if the field has not been filled out. If it is a TextTemplate, this value should be a string. If it is a DateTemplate, it should be an ISO formatted date string (e.g. 2016-11-16T18:23:08.030Z). The format will be dictated by the globalSettings.signatureDateFormat property. If it is a CheckboxTemplate, it may only be "" or "checked". If it is a signature, it should be an object with the following properties:

Properties

Name	Type	Attributes	Description
`type`	string	<optional>	The type of signature that will be placed in the field. Can be "text" for a text signature or "path" for a freehand signature.
`value`	string	<optional>	For a text signature, this is the actual text that will be in the signature. For a path signature, this is a subset of the SVG path standard, only including the M, L, and C commands (e.g. M0,0L1,1L1,0).
`fontName`	string	<optional>	The font to be used to render the signature. This is required for text signatures but does not apply to path signatures.

globalSettings

Object

Settings that apply globally to the template.

Properties

Name	Type	Description
`signatureDateFormat`	external:"jQuery.fn"~DateFormat	The format to use for dates when completing template fields.

(inner) FormDefinition

Defines the schema of the template form that is saved to the server, including all of the metadata required to load and recreate the form.

Properties:

Name	Type	Attributes	Default	Description
`templateDocumentId`	string			The unique id used to determine which document belongs to the form. The form cannot be loaded if this value is not defined.
`formName`	string	<optional>	""	The display name of the form.
`formDefinitionId`	string	<optional>		The unique id to use to save the form to the server.
`formRoles`	Array	<optional>		The data here is similar to the `formRoles` property of module:state-store~FieldList, but represented as an array to be saved to the server. This array will be used to rebuild the `formRoles` object when a `FormDefinition` is loaded into the viewer.
`groups`	Array	<optional>		The data here is similar to the `groups` property of module:state-store~FieldList, but represented as an array to be saved to the server. This array will be used to rebuild the `groups` object when a `FormDefinition` is loaded into the viewer.
`formData`	Array			The data here is similar to the `fieldList` property of module:state-store~FieldList, but represented as an array to be saved to the server. This array will be used to rebuild the `FieldList` object when a `FormDefinition` is loaded into the viewer. As such, some properties of `FieldList.fieldList` are excluded when generating the `FormDefinition.formData`. These exclusions are `markId` and `sortIndex`.
`globalSettings`	Object			An instance of the module:state-store~GlobalSettings object used for this form.

(inner) PageData

Defines the set of currently known pages -- ones that have loaded at least once in the viewer -- and their sizes. It is a hash object, using the page number as the object key, and the following properties as the object value.

Properties:

Name	Type	Description
`width`	number	The width of the page.
`height`	number	The height of the page.

Methods

destroy()

Destroys the instance of the State Store.

getState(key) → {*|undefined}

Gets the current state.

Parameters:

Name	Type	Description
`key`	string	The name of the state value being retrieved.

Returns:

The state value associated with the specified key or undefined if the state value does not exist.

Type: * | undefined