Form development

Form development - Patch specific forms

A form can contain specific information that varies depending on the filing case. The aim is to separate all default information from the specific information of a form. This is done by adding the default segments of a form to the specific segment via JavaScript triggered JSON Patches. The JSON Patches are a diff from an skeleton form with the default segments.

The following steps describe how this is achieved in detail.

1. Nashorn Action

The Nashorn Action is inserted after the createFormInstance Action:

- name: ecm4uBizDocs_BusinessPartnerDataCapture_MergeForms
  impl: de.ecm4u.faw.api.impl.NashornAction
  predecessors: [ecm4uBizDocs_BusinessPartnerDataCapture_CreateFormInstance]
  args:
    NashornAction.scriptName: ecm4uBizDocs_mergeForms.js
    Custom.formInstanceId: $formInstanceId0

The script uses the jsonpatch textresources ecm4uBizDocs_PatchInformation and ecm4uBizDocs_PatchOptional as default segments. The create form instance action creates the specific form.

2. Patching-forms

The form textresources ecm4uBizDocs_DefaultInformation and ecm4uBizDocs_DefaultOptionals contain the default segments as regualr forms. The specific form is NOT converted into a patch. This patch mechanism relies on the separation of default and specific information in the form element of the form. Thus a form is separated into these three fieldsets:

{
    "form": {
        {
            "expandable": false,
            "id": "fieldset_default_information",
            "type": "fieldset",
            "items": []
        }, {
            "expandable": false,
            "id": "fieldset_specific_information",
            "type": "fieldset",
            "items": []
        }, {
            "expandable": false,
            "id": "fieldset_optional_information",
            "type": "fieldset",
            "items": []
        }
    }
}

The specific form only contains the fieldset_specific_information, the default information form only contains the fieldset_default_information and the default optionals form only contains the fieldset_optional_information. It is not possible to insert specific segments in the default forms and vice versa.

3. Converting forms into patches

The forms ecm4uBizDocs_DefaultInformation and ecm4uBizDocs_DefaultOptionals are used to create the default patches. A diff between an empty skeleton form and the default form is created. This is done with the Module Build Tool (requires node) by using the following command lines:

node buildmodule.js jsondiff -jf=form/ecm4uBizDocs_FormSkeleton.json -jt=form/ecm4uBizDocs_DefaultOptionals.json -jd=textresources/jsonpatch/ecm4uBizDocs_DefaultOptionals.json

node buildmodule.js jsondiff -jf=form/ecm4uBizDocs_FormSkeleton.json -jt=form/ecm4uBizDocs_DefaultInformation.json -jd=textresources/jsonpatch/ecm4uBizDocs_DefaultInformation.json -i=2

Only the optionals patch must be modified slightly: In order to insert the optionals fieldset as the last fieldset in the form, the index in path must be set from 0

"path": "/form/0"

to - (which equals the last index)

"path": "/form/-"

The skeleton form only contains the basic structure of a form. It must be used as base for the diff, otherwise each diff would overwrite the whole form. The skeleton form looks like this:

{
    "schema": {
        "properties": {}
    },
    "layout": [],
    "form": [],
    "uiSchema": {},
    "actions": {}
}

4. Example form

This way of configuring forms results in smaller and easier to maintain forms. When using the patch mechanism, the form for capturing data for a business partner document only contains the following information:

{
    "schema": {
        "properties": {
            "businessPartnerId": {
                "minItems": 0,
                "type": "string",
                "required": true,
                "enum": []
            }
        }
    },
    "layout": [],
    "form": [{
        "id": "fieldset_specific_information",
        "expandable": false,
        "type": "fieldset",
        "items": [
            "businessPartnerId"
        ]
    }],
    "uiSchema": {
        "businessPartnerId": {
            "widget": "mdhEntity",
            "idProperty": "id",
            "displayProperty": "{id} ({displayName})",
            "multiple": false,
            "searchProperty": "displayName",
            "source": "BusinessPartner",
            "searchWholeProperty": true,
            "loadAllData": false,
            "addable": true,
            "addableFieldName": "displayName",
            "sortBy": "displayName",
            "sortDirection": "ASC"
        }
    },
    "actions": {}
}