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

  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

loadSubPage?: (Did: string) => void

• Did Load certain sub page providing the Did
• force Set true if onBeforeSubPageAddition callback invocation should be avoided

deleteSubPage?: (UNUSED: any, force: boolean) => void

• UNUSED No usage at the moment, reserved for future purpose
• force Set true if onBeforeSubPageDeletion callback invocation should be avoided

Limitations / Gotchas

• // TODO

License

ISC