A form uses an extended version of JSON Schema to define a form.
Additional patch-mechanisms used when developing forms for modules
See the timestamp section on the page about modules.
{
"forms": {
"93e7aab7-7fee-4b87-b038-e893dbf6dc44": {
"name": "Simple Form",
"definition": "classpath:/de/ecm4u/faw/module/simple/forms/simple-form-1.0.0.json",
"module": "simple-1.0.0"
}
}
}The JSON representation of a task has four properites:
name: The name of the form.definition: The of the form. This can be an inlined JSON object or a classpath URL to a JSON file.module: The module version in which the form fast first included.A form consists of five parts: schema, form, uiSchema and actions.
{
"schema": {},
"form": [],
"layout": [],
"uiSchema": {},
"actions": {}
}The schema defines the data model of the form fields.
{
"schema": {
"properties": {
"description" : {
"type" : "string",
"required" : true,
"default" : "Enter your description here ..."
}
}
}
}The form defines the visibility and order of form fields.
{
"form": [
"description"
]
}It is possible to put form elements into rows. The optional layout array contains an object for every row.
{
"layout": [
{
"properties": ["review_state", "approve_state"],
"columns": [6, 6]
}
]
}properties: The names of the form properties that shall be put into a row together.columns: The relative widths of the properties (must add up to 12).The uiSchema allows more specific configuration of the form fields. Dependending on the intended
behaviour of the form field, a specific combination of options can be used.
See the documentation for the supported widgets.
hidden: Hides an element from the form.number: Makes the form element display a number.date: Displays the form element as a date and adds a datepicker.datetime: Displays the form element as a datetime and adds a datetimepicker.flowLabel: Displays the form element as a read only label.smFlow: Display a select field with values of a Status Machine Flow Status.mdhEntity: Displays a select field that interacts with a MDH entity.csSubject: Displays a select field with values of a configuration service Subjectglyphicon: Render a button using a Bootstrap Glyhicon.Actions can be used to add behaviour to form elements. You can add an action to a form element that belongs to a form property. Or you can add buttons that do not correspond to form properties.
If the action ist save, the widget, when its value is changed, triggers a save and reload of the complete form. If the Flow or Task Instance the form belongs to has the property save-form-script, the referenced Nashorn script is executed on the FaW server after save and before reload.
This example defines a number widget with this behaviour.
{
"schema": {
"properties": {
"myNumberProperty": {
"type": "string"
}
}
},
"form": [
"myNumberProperty"
],
"uiSchema": {
"myNumberProperty": {
"widget": "number",
"digits": 2
}
},
"action": {
"myNumberProperty": "save"
},
"formData": {
"myNumberProperty": 1234.56
}
}If the action ist onChange, the widget, when its value is changed, triggers a named Action Script to be executed on the FaW server. The complete form is rebuild after the action execution has finished.
This example defines a mdhEntity widget that, when its value is changed, triggers the named Action Script partner-changed on the FaW Server.
{
"schema": {
"properties": {
"bd_partnerNo": {
"minItems": 0,
"type": "string",
"required": true,
"enum": []
},
}
},
"form": [
"bd_partnerNo"
],
"uiSchema": {
"bd_partnerNo": {
"widget": "mdhEntity",
"idProperty": "id",
"displayProperty": "{id} ({displayName})",
"searchProperty": "displayName",
"multiple": false,
"source": "BusinessPartner",
}
},
"actions": {
"bd_partnerNo": "partner-changed"
},
"formData": {
"bd_partnerNo": "BP-1234"
}
}You can also bind an action to a form element that does not belong to a form property. You will have to define the form element in the form section and reference it in the action section.
This example will render a button that, when clicked, executes the exand-inbound Script Action on the FaW server.
{
"schema": {
"properties": {
}
},
"form": [
{
"id": "expand-inbound-btn",
"type": "button"
}
],
"actions": {
"expand-inbound-btn": {
"onClick": "expand-inbound"
}
}
}The formData part is optional for the creation of a form as it mainly contains the chosen values. Nevertheless it can be important for script/action usage, e.g. to pre-set fields.
When a form instance is displayed, labels are added to each field, as section headings, as input field placeholders, and as button texts.
The values for these labels are defined in JSON textresource files having type=i18n. I18N textresources are loaded first for the flow instance, second for the task instance the form instance belongs to. The labels loaded for the task instance override thos loaded for the flow instance. This makes it possible to define lables that apply to all tasks in a flow to a common textresource.
An example for a I18N JSON file:
{
"de": {
"sin_state": "Rechnungsstatus",
"fieldset_optional_information": "Optionale Informationen",
"comments_placeholder": "Kommentar eingeben ...",
"add-link": "Nebenzuordnung hinzufügen"
},
"en": {
"sin_state": "Invoice State",
"fieldset_optional_information": "Optional Information",
"comments_placeholder": "Enter comment ...",
"add-link": "Choosen an optional Assignment"
}
}The file must contain a JSON object. The keys in this object are locales, the values objects with the lable values for this locale. The above example defines label values for two locales, de and en.
The keys in a lables JOSN object are:
sin_statefieldset_optional_informationcomments_placeholderadd-linkInside a form JSON, they correpond to the locations illustrated in the following abbreviated example.
{
"schema": {
"properties": {
"sin_state": {
"readOnly": true,
"type": "string",
"required": false
}
}
},
"form": [
{
"id": "fieldset_optional_information",
"expandable": false,
"type": "fieldset",
"items": [
"sin_state",
{
"placeholder": "comments_placeholder",
"type": "textarea",
"key": "comments"
},
{
"id": "add-link",
"type": "button"
}
]
}
]
}A Form Instance can be configured to automatically save values from formData on save or submit. There are two ways to configure this feature.
CreateFormInstanceActionThe CreateFromInstanceAction supports four parameters to define the formData values to be saved.
The formData values to save can be put into the Configuration Services. The subjects are
taskInstancePropertiesOnSavetaskInstancePropertiesOnSubmitflowInstancePropertiesOnSaveflowInstancePropertiesOnSubmitThe key is the name of the Form Instance. The value must be a comma separated string containing the names of the formData properties.