...

The model and the view documents will be loaded by the form generator which is implemented in the portal. It will render and show a form to the user based on the input documents:

...

Let’s have a look to all of these parts step by step below.

The Form

...

Data

The Form Model Data is a JSON document which provides the data to be displayed in the form.

It is belongs to the central “model” part of the MVC form framework: .

The whole form framework is about loading this model data (A), displaying it in a form (B), validating it, merging copying the data values from the form back to the model fields into the output data (C) and storing the final model to some target sinkoutput data to the property store by default. The structure of the input data and output model JSON document data is always defined by the same Form Schema (D):

...

The Input Form Model

There can be an optional input form model (A) which is the data to be shown initially to a form. For example in case data will be loaded from a database in order to edit it in the form, then this data from the database will become the input model to the form. The model must comply with the Form Schema (D).

The input form model can be provided to the form framework in two different ways:

• Via the input configuration attribute in the Form Config (see below) which is a custom uri pointing to the data to be loaded and converted to the input form model format. This can be a custom uri which

  • points to a property in the property store (for example "input": "$uri:property:global/app/myapp/data/mydata")

  • a pipeline which will prepare the input form model (for example "input": "$uri:pipeline:global/app/myapp/pipeline/mypipeline" or a

  • command which will return such a model (for example "input": "$uri:command:my.command").

• Via request parameters whereas each request parameter name must have the same name as the form field. For example a request parameter like this ?firstName="Max" will set the value Max on a field with id firstName. Also complex (nested) elements can be set this way whereas the value must be url encoded. In case there exists already a form input model, then a request parameter can overwrite values from this model afterwards. In case no field with this id exists, nothing happens.

In case a form has no input model (which means input config is set to null or doesn't exist and no request parameter was set), then it will be an empty form which can be initially filled with data from the user.

Here is an example of such an input model to a form containing different types of data:

{
  "firstName": "Max",
  "lastName": "Huber",
  "age": 48,
  "cv": {
    "name": "cv-max-huber.pdf",
    "contentLength": 243,
    "contentType": "application/pdf",
    "contentEncoding": "base64",
    "content": "YWRzYXNhc2ZzZCBmc2R.....BkZmRzZmRzIHNzc2Rmcw=="  
  }
}

The Output Form Model

After the user has clicked the submit button of the form (B), the fields of the form will be written back into a JSON document which is then the output form model (C) which also must comply with the Form Schema (D).

This output form model finally will be send to the target sink which is configured by the output parameter in the Form Config. This is typically a location in the property store. For example "output": "$uri:property:global/app/myapp/data/mymodel".

The JSON format of the output is the same as the format of the input model and complies with the Form Schema.

The Form Schema

The Form Schema document describes the fields of a Form Model using the JSON Schema specification. For example the type of the field, validation rules, the title and how to display such a field in the form (for example as text field or number picker?).

For more details go to: /wiki/spaces/DEV/pages/2482176001

The Form Config

The Form Config is the central configuration file of a form. It defines things like:

• How the fields of a form must be positioned in the view (= the layout).

• Where to load and write the form model from / to.

• Where to load the schema of the form from.

• What to do, after a form has been submitted.

• Title, description, type and other settings of the form.

...

The Input Data (initial form data)

There can be an optional input data (A) which is the data to be shown initially to a form when it gets loaded. This input data is provided as a JSON document. For example, in case data must be loaded from a database in order to edit it in the form, then this data from the database will be converted to JSON and will become the input data to the form. The input data structure must comply with the Form Schema (D).

Here is an example of such an input data JSON:

{
  "firstName": "Max",
  "lastName": "Huber",
  "age": 48,
  "cv": {
    "name": "cv-max-huber.pdf",
    "contentLength": 243,
    "contentType": "application/pdf",
    "contentEncoding": "base64",
    "content": "YWRzYXNhc2ZzZCBmc2R.....BkZmRzZmRzIHNzc2Rmcw=="  
  }
}

The input data can be loaded to the form framework in different ways:

• Via the input attribute in the Form Config (see below) which is a custom uri pointing to the data to be loaded. This custom uri can point to a

  • … property to be loaded from the property store. For example:
    "input": "$uri:property:global/app/myapp/data/mydata"

  • … pipeline which will be executed and returns the input data. For example:
    "input": "$uri:pipeline:global/app/myapp/pipeline/mypipeline"

  • … command which will be executed and returns the input data. For example:
    "input": "$uri:command:my.command"

• Via HTTP request parameters whereas each request parameter name must have the same name as the form field. For example a request parameter like this ?firstName="Max" will set the value Max on a field with id firstName. Also complex (nested) elements can be set this way in JSON format whereas this value must be url encoded. In case there exists already a form input data, then a request parameter can overwrite values from this data afterwards. In case no field with this iname from request exists, nothing happens.

In case a form has no input data (which means input config is set to null or doesn't exist and no request parameter was set), then it will be an empty form which can be initially filled with data from the user.

The Output Data

After the user has clicked the submit button of the form (B), the fields of the form will be written back into a JSON document which is then the output data (C) which also must comply with the Form Schema (D).

This output data finally will be send to the target sink which is configured by the output parameter in the Form Config. This is typically a location in the property store. For example:
"output": "$uri:property:global/app/myapp/data/mymodel"

The JSON format of the output is the same as the format of the input model and must comply with the Form Schema.

The Form Schema

The Form Schema document describes the fields structure of a Form Model using the JSON Schema specification. For example the type of the field, validation rules, the title and so on.

It belongs to the “model” part of the MVC form framework.

For more details go to: /wiki/spaces/DEV/pages/2482176001

Here is an example of such a Form Schema JSON:

TODO

The Form Config

The Form Config is the central configuration file of a form.

It belongs to the “view” part of the MVC form framework.

It defines things like:

• How the fields of a form must be positioned in the view (= the layout).

• Where to load and write the form model from / to.

• Where to load the schema of the form from.

• What to do, after a form has been submitted.

• Title, description, type and other settings of the form.

For more details go to: /wiki/spaces/DEV/pages/2482798727

here is an example of such a Form Config:

TODO

The Pipeline

After the form has been submitted by the user, the output data will be stored in the property store and then a property.created event will be fired by the property store.

A pipeline can listen to this event and then further process the form submit.

The pipeline belongs to the “controller” part of the MVC form framework.

Here is an example of such a pipeline listening to the event:

pipeline:
  - event.listen:
      key: property.created
      filter: ${body.target.path.contains('global/app/myapp/object/person/v1/instance')}
  
  - mail.send:
    to: name@email.tld
    subject: "Apllication form was submitted"
    messsage: |
      The application form was submitted:
      ${body.target}

The pipeline listens to all property.created events and in case a property was created which matches the given filter, it will be executed and can then further process the form output data which are provided in the body.

For more details, see:

• Command and Pipeline

• Events

• Pipeline Triggers

In order to define a form in PIPEFORCE, you need a JSON schema and the form configuration.

...