Phq-form-engine NPM

Premise HQ Form Engine

Renders UI of a form created by Form Engine application.

Installation

# npm
npm i phq-form-engine

Prerequisites

phq-utility/lib/ServerAPI usage

	```jsx
	import ServerAPI from 'phq-utility/lib/ServerAPI';

	ServerAPI.setVariables({
		AppKey, Key, Host, Premise,
		$ // or jQuery
	});

	// The library needs to be deployed and the `ServerAPI` object of it requires to be initialized
	```

react version >= 16.8.6
react-select >= 3.0.0

Examples

Demo

Props

`formName?: string`

Name of the form

`Did?: string`

The ID of the row (Did field value of the row from the designated module)

`canRestore?: boolean`

Whether the library should save data in-progress in localStorage for the user to restore when they leave without saving and come back

`autoRestore?: boolean`

Should the library automatically restore data if any previous unsaved work detected

`getComponent?: object`

The keys of the getComponent can be inputType or '-' + tag. inputType can be select, file, text, number, date, radio, checkbox, hidden, textarea, signature etc.

'-' + tag indicates that all other tags except for inputTypes should be prefixed by -. At the time of writing only -label is available - which controls the label components.

Each key of the object should be a function that returns modified component of developer's choice. Structure of the function is - (rawElem: object, props: object, value: string | undefined, repeaterInfo: object) => React.Node | boolean

rawElem The raw element that is responsible for rendering the component props Few of the props that FormEngine would've attached to the rendered component value value of the component or undefined when its not of a inputType repeaterInfo If the component is inside a repeater, returns an object containing Did, index & PostURL (targeted module). Else null

Returned value can either be a valid value that react can render or false specifically. Returning false will hand over the control back to FormEngine once again.

	<FormEngine
		getComponent={{
            'select': function () {
	            // 
                return false;
            },
            'file': function (rawElem, props, value, repeaterInfo) {
                return (
                    <div>
                        Testing
                        <div>
                            <input {...props} value={value} />
                        </div>
                    </div>
                );
            },
            '-label': function (rawElem, props, value, repeaterInfo) {
                return <div><span>Testing</span> <label {...props}>{rawElem.Label}</label></div>;
            },
        }}
		{...rest}
		/>

`onChange?: (rawElem: object, value: string | Array, info: object) => object`

rawElem The raw element that is responsible for rendering the component
value New value of the element, usually string, an Array if its a checkbox
info An object containing the following keys container Root HTML Element that is containing the form index Returns the sub-page index or 0 if the page is not set to be repeated Did Current Did of the page MID Parents Did if applicable * PostURL Targeted module

Return values:

Function expects to be returned a partial object containing [Id]: value pairs. ex. { [Id1]: newId1Value, [Id2]: newId2Value }
Return false to prevent state from updating
Return nothing (undefined) to let the library perform its default action

`onChange?: object`

Alternative to onChange function. This can be an object with id-function pairs. Each id will correspond to form's raw element having that particular Id . A change event triggered by that raw element will enter relevant id's function. To catch other change events except for the given ids, use __default__. Aforementioned function behaves the same way described in the above onChange function.

{
	Id1: function (rawElem, value, info) {
		// Enters when `Id1` changes
	},
	Id2: function (rawElem, value, info) {
		// Enters when `Id2` changes
	},
	__default__: function (rawElem, value, info) {
		// Enters when any other ids change except for `Id1` & `Id2`
	},
}

`onRepeaterChange?: (rawElem: object, value: string | Array, info: object) => object`

Similar to onChange function, except it registers the events created in the repeaters. info object returns similar keys, but has a slightly different indication

container HTML Element that is the owner of that input element (N.B. Input element of a repeater will certainly have a different container than a regualar input element)
index Returns the index position of that repeated item
Did Current Did of the repeater's item
MID Did of the form containing the repeater
PostURL Targeted module

`onRepeaterChange?: object`

Alternative to onRepeaterChange function. Expects a module-object/function pairs.

{
	Repeater1: function (rawElem, value, info) {
		// Enters when any element contained by the repeater assigned to module `Repeater1`, triggers a change event
	},
	Repeater2: {
		RepeaterId1: function (rawElem, value, info) {
			// Enters when `RepeaterId1` changes of the repeater assigned `Repeater2` module
		},
		__default__: function (rawElem, value, info) {
			// Enters when other elements change inside `Repeater2` module-repeater
		},
	},
	__default__: function (rawElem, value, info) {
		// Any repeater not having `Repeater1` or `Repeater2` module assigned, will enter this function
	},
}

`onLoadStart?: (info: object) => void`

Triggered when the form starts loading. info has the following attributes

Did of the form
formName the name of the form
data current id-value pairs (might not be initialized completely (or at all) during onLoadStart)
PostURL targeted module
container html element

`onRepeaterLoadStart?: (info: object) => void`

Triggered when the form starts loading. info has the following attributes

Did of the repeater
PostURL targeted module
repeaterIndex index position of that repeated item
data current id-value pairs of the repeater (might not be initialized completely (or at all) during onRepeaterLoadStart)
container html element the contains the current repeated item

`onLoad?: (info: object) => void`

Similar to onLoadStart, except info.data should have been configured at this stage

`onRepeaterLoad?: (info: object) => void`

Similar to onRepeaterLoadStart, except info.data should have been configured at this stage

`onSave?: (info: object) => void`

Similar to onLoad function, except it doesnt have container attribute & extends the following attribute(s) of the info object

errors An array containing list of errors, errors might suggest that although onSave invoked, data hasn't been saved

`onRepeaterSave?: (info: object) => void`

Similar to onRepeaterLoad function, except it omits container attribute & extends the errors attribute of the info object

`onGettingPageList?: (pages: Array) => void`

Provides all the retrieved pages from form structure

`onGettingSubPageList?: (subPages: Array) => void`

Provides all the sub-pages of page that is allowed to repeat.

`onGettingFormData?: (formJson: string) => void`

Provides the JSON structure of the form upon retrieval

`onBeforeSave?: (info: object, resolve: function) => boolean`

Just before save function is triggered. Return false to deny proceedings. info object has the following attributes

master id-value pair object of the master forms elements (not the repeater)
repeaters

{
	Repeater1: [
		{
			// repeated item of `Repeater1` module, row 1
			ID: Repeater1Did1,
			data // id-value pair object
		}, {
			// repeated item of `Repeater1` module, row 2
			ID: Repeater1Did2,
			data // id-value pair object
		}
	],
	Repeater2: [
		{
			// repeated item of `Repeater2` module, row 1
			ID: Repeater2Did1,
			data // id-value pair object
		}
	],
	...
}

formName Name of the form
PostURL Assigned module
errors Internal error list (for instance, if isRequired element doesnt contain any value - its appended to the list)

resolve the second parameter of onBeforeSave, it's a function which can be invoked if we decide to save at a later time.

`onBeforePageChange?: (info: object, resolve: function) => boolean`

Invoked before changing a page. info object has the following attributes

Did ID of the current form row
pages (Array) Collection of pages
subPageDids (Array) collection of sub-page Dids
alter number of pages to alter, -1 indicates it should go to previous page, 2 indicates that it should skip the next page and target the following one
curPageIndex active page index

`onBeforeRepeaterAddition?: (info: object, resolve: function) => boolean`

Invoked before a repeated item gets added. Return false to deny proceedings. info has the following attributes

Dids Collection of all the item'd Did in an Array
PostURL Targeted module

resolve is a function that can be executed to add repeater later, at a convenient time.

`onRepeaterAddition?: (info: object) => void`

Called after a repeater has been added. info has the following attributes

PostURL Targeted module

`onBeforeRepeaterDeletion?: (info: object, resolve: function) => boolean`

Invoked before deleting a repeated item. Return false to deny proceedings. info has the following attributes

data id-value pair of that repeated item
Did ID of that repeater
index index position of that repeated item
PostURL Targeted module
Dids All the repeated items of that repeater

resolve a function if repeated item is intended to be deleted at a later time

`onRepeaterDeletion?: (info: object) => void`

Executed after a repeater has been deleted. info contains the same attributes as onBeforeRepeaterDeletion's info does

`onBeforeSubPageDeletion?: (info: object, resolve: function) => void`

Invoked before deleting a sub page. Return false to deny proceedings. info has the following attributes

Did the ID of the row
MID the ID of the master form
index index position of that sub page
formName Name of the form
data Current id-value pair of the form
PostURL Targeted module
Dids Dids of all the sub-pages contained by the parent page

resolve a function if sub page is intended to be deleted at a later time

`onSubPageDeletion?: (info: object) => void`

Invoked after a sub page deletion. info contains all the same attributes of onBeforeSubPageDeletion's info object

`onBeforeSubPageAddition?: (info: object, resolve: function) => boolean`

Triggered before adding a sub page. Return false to deny proceedings. info contains the following attributes

formName Name of the form
Dids All the Dids of current page
PostURL Targeted module

resolve a function to be used at a later time

`onSubPageAddition?: (info: object) => void`

Invoked after sub page addition. info contains all the same attributes of onBeforeSubPageAddition's info object

`onError?: () => void`

Implementation has still a long way to go. Invoked during different errors - getting module data, saving data etc. Usually has two parameters. First parameter (object) has the following attributes

fn Name of the function
type Type of error
data Some relevant data
PostURL Relevant module if applicable

2nd parameter contains an xhr response if applicable. // TODO Things are still under construction, so certainly in need of standardization and stabilization.

`onBeforeCascade?: () => void`

Not functional at this moment

`onCascade?: () => void`

Not functional at this moment

`onRestoration?: () => void`

Invoked after data is restored from local storage

APIs

`setData?: (data: object, callBack: function) => void`

comp.setData({
	master: {
		SomeID: 'some-value',
		SomeID2: 'some-value-2'	
	},
	repeaters: { 
		Native_Repeater1: [ 
			{ 
				index: 1, 
				data: { 
					StepUp: '11' 
				} 
			}, {
				index: 0, 
				data: { 
					StepUp: '5654' 
				} 
			} 
		],
		Native_Repeater2: [ 
			{ 
				index: 1, 
				data: { 
					Allowance: 'N/A' 
				} 
			}, {
				Did: SOME_DID, 
				data: { 
					Allowance: 'Small',
					Details: 'Empty' 
				} 
			} 
		]
	} 
}, () => { 
	console.log('Done!'); 
})

`getData?: (getAll: boolean) => object`

comp.getData();
// returns
/*
	{
		MasterID1: 'MasterID1-value',
		MasterID2: 'MasterID2-value'
	}
*/ 

comp.getData(true);
// returns
/*
	{
		master: {
			MasterID1: 'MasterID1-value',
			MasterID2: 'MasterID2-value'
		},
		repeaters: {
			Repeater1: [
				{
					ID: REPEATER1_SOME_DID,
					data: {
						// id-value pair
					}
				}, {
					ID: REPEATER1_SOME_DID_2,
					data: {
						// id-value pair
					}
				}
			],
			Repeater2: [
				{
					ID: REPEATER2_SOME_DID,
					data: {
						// id-value pair
					}
				}, {
					ID: REPEATER2_SOME_DID_2,
					data: {
						// id-value pair
					}
				}
			]
		}	
	}
*/

`save?: (UNUSED, callBack: function) => void`

Starts saving the form

`getKeyData?: (key: string) => string`

Returns the value of the element having rawElement.Id== key

`getFormName?: () => string`

Returns active form's name

`updateDid?: () => void`

Should be avoided at this moment

`alterPage?: (alter: number, force: boolean) => void`

alter Number of pages to alter, -1 indicates it should go to previous page, 2 indicates that it should skip the next page and target the following one.
force Set true if onBeforePageChange callback invocation should be avoided