What is 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 view / layout).

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

• Where to load the /wiki/spaces/DEV/pages/2482176001 from.

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

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

Here is an example how such a form config could look like:

{
  "title": "Add person",
  "description": "Add a new person",
  "schema": "$uri:property:global/app/tld.domain.myapp/object/person/v1/schema",
  "input":"$uri:property:global/app/tld.domain.myapp/object/person/v1/instance/67b07f3c-e006-4bec-a790-ef25b9fe97df",
  "output": "global/app/tld.domain.myapp/object/person/v1/instance/${vars.property.uuid}",
  "layout": {
    "orientation": "vertical",
    "items": [
      {
      "orientation": "horizontal",
      "items": [
        {
        "field": "firstName"
        },
        {
        "field": "lastName"
        }]
      },
      {
        "field": "age"
      },
      {
        "field": "gender"
      },
      {
        "field": "birthDate"
      }
    ]
  }
}

The form config must be stored in the property store inside the form subfolder of your app. For example:

global/app/tld.domain.myapp/form/person

All form configs inside the form folder will be automatically picked-up and shown in the forms overview of an app. For example, here you can see the form Add person automatically listed:

Configuration Attributes

The form config contains different attributes in order to specify the form. All of these attributes are described in detail below.

title

The title defines the title of the form to be displayed in the web ui and in other locations.

This can be a static text or an i18n uri like $uri:i18n:myTitle for example.

description

The description is optional and describes the intention of the form.

This can be a static text or an i18n uri like $uri:i18n:myDescription for example.

icon

Each form can have an individual icon. This value must be a code name from the Google Material Icons as listed here: https://fonts.google.com/icons

This value is optional. If not given, the icon with code name ballot is shown as default:

color

The color of the form icon. If not given, the secondary color is used, which depends on the style settings. By default this is a blue color like this:

The color value can be a hex color value like this:
"color": "#FFA500"

Or it can be a constant selected from the Colors palette.

For example you could use the color palette constant “green” like this:
"color": "green"

Another example:

"color": "red-8"

schema

The schema attribute defines a PIPEFORCE URI which is called in order to retrieve the Form schema for this form.

For example, the attribute could look like this:

"schema": "$uri:property:global/app/tld.domain.myapp/object/person/v1/schema"

Which could return a JSON schema like this:

{
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "title": "First Name",
      "description": "The first name of the person."
    },
    "lastName": {
      "type": "string",
      "title": "Last Name",
      "description": "The last name of the person."
    },
    "age": {
      "type": "number",      
      "title": "Age",
      "description": "The age of the person."
    },
    "gender": {
      "type": "string",
      "title": "Gender",
      "description": "The gender of the person.",
      "enum": [
        "male",
        "female",
        "neutral"
      ]
    },
    "birthDate": {
      "type": "string",
      "format": "date",
      "title": "Date of birth",
      "description": "The date of birth of the person."
    }
  }
}

output

The output defines the path in the property store where the form data must be stored as JSON property after the form has been submitted. Example:

input": "global/app/tld.domain.myapp/object/person/v1/instance/${vars.property.uuid}"

The PE variable will be interpreted at server side and will be replaced by the uuid of the property.

The form handling pipeline can listen to a property.created event on this path then in order to get informed when a new property was created on this path:

pipeline:
  - event.listen:
      eventKey: property.created
      filter: ${body.target.path.contains('/tld.domain.myapp/object/person/v1/instance/')}

The same way it works with property.updated event.

Also see:

• https://logabit.atlassian.net/wiki/spaces/PA/pages/2545451358/Forms#The-Pipeline-(Controller)

input

The input attribute defines a PIPEFORCE URI which is called to retrieve the initial input data for the form in order to set predefined values on the form widgets. For example, the input parameter could look like this in order to load a JSON property from the property store:

"input": "$uri:property:global/app/tld.domain.myapp/object/person/v1/instance/fe97df"

Which could return a form data (= model) as JSON to be edited similar to this:

{
  "firstName": "Alice",
  "lastName": "Smith",
  "age": 20,
  "gender": "female",
  "birthDate": "2003/05/01"
}

forwardOnSuccess

DEPRECATED Use onSuccess instead.

This attribute defines an URL, or a path relative to the portal in order to forward to after the form has been submitted successfully. In case the submit caused an error, the form will stay at current location in order to display the error. In case this attribute is not given, the form will show the default submit success message.

onSuccess

SINCE 9.0

This defines what should happen in case the form was successfully submitted. This is optional. If not defined, the default success message and icon will be shown:

forward

Forwards to a URL or a path relative to the portal. In case the submit caused an error, the form will stay at current location in order to display the error:

{
  "onSuccess": {
    "action": "forward",
    "url": "http://target/url"
  }
}

• action - must be set to forward.

• url - The URL or the path relative to the portal where to forward after success.

message

Shows a text message and an icon in case the form was successfully submitted.

{
  "onSuccess": {
    "action": "message",
    "text": "$uri:i18n:successMessage",
    "icon": "done",
    "color": "green"
  }
}

• action - Must be set to message.

• text - Can contain a static text or an i18n key. If not given, the default text will be shown.
  See: TODO

• icon - Must be a code name from the Google Material Icon. If not given, the default icon will be shown. See: https://fonts.google.com/icons .

• color - Defines the color of the icon. If not given, the default icon color will be shown.
  See Colors .

layout

By default, in a form, all widgets (= fields) of the Form Schema are displayed vertically, each ints own row.

Vertical orientation​

You can change this default by configuring orientation of the layout in the Form Config.

To do so, firstly you need to add the element layout to the form configuration as shown in this example:

{
  "title": "Person",
  "description": "The person form",  
  ...
  
  "layout": {
    "orientation": "vertical",
    "items": [
      {"field": "firstName"},
      {"field": "lastName"},
      {"field": "age"},
      {"field": "gender"}
    ]
  }
}

This example layout configuration would create exactly the default layout again:

Horizontal orientation​

You can then change the orientation, width and height of a layout item like this:

{
  "title": "Person",
  "description": "The person form",  
  ...
  
  "layout": {
    "orientation": "horizontal",
    "height": "100",
    "width": "900",
    "items": [
      {"field": "firstName"},
      {"field": "lastName"},
      {"field": "age", "width": "150"},
      {"field": "gender"}
    ]
  }
}

The attributes width and height can be also specified on individual widget fields.

This would result in this form layout afterwards, where all fields are displayed in a single row (horizontally):

Width of 900 in horizontal layout item prevents fields to cover all of the available space.

Layout items and fields in horizontal orientation, by default, try to span as much width as possible, but with respect to neighbouring fields - behave responsively.

Both min-width and max-width can be also used in place of width to reach responsiveness within defined limits.

Nesting layouts and orientations​

Layouts and its orientations can be nested in order to create quite complex form structures. Here’s an example:

{
  "title": "Person Form",
  "description": "A simple person form.",  
  ...
  
  "layout": {
    "orientation": "horizontal",
    "items": [
      {
        "orientation": "vertical",
        "items": [
          {"field": "firstName"},
          {"field": "age"}
        ]
      },
      {
        "orientation": "vertical",
        "items": [
          {"field": "lastName"},
          {"field": "gender"}
        ]
      }
    ]
  } 
}

This example would produce a form like this with nested orientation:

type

TODO

Internationalization (i18n)

TODO

Special Form Types

Document Understand Form

TODO

Variable substitution

Request parameters

It is possible to use request parameters in the form config attributes as placeholders like this:

"input": "$uri:command:workflow.history.tasks?taskId=${request.param.myTaskId}"

In order to set the taskId dynamically, one could call the form like this:

form?myTaskId=someTaskId

After the placeholder has been replaced, the input parameter will look like this:

$uri:command:workflow.history.tasks?taskId=someTaskId

These attributes in the form config support request parameter variable substitution:

• input

• output

• schema

Property attributes (PEL)

It is also possible to specify a PEL inside some of the config attributes. This way the PEL will be executed at server side and the result will be used to form the final config value. For example:

"output": "global/app/myapp/object/person/v1/instance/#{var.property.uuid}"

In this example the PEL #{var.property.uuid} will be resolved to the UUID of the property which is about to be created when sending this output.

Form Scripting

TODO: Add final description here. See here and add parts of it to this documentation which are finalized: https://logabit.atlassian.net/wiki/spaces/DEV/pages/846233616/PRD11+-+Forms#P1:-Form-script

Internal Script

Use script as a config in form configuration.

{
  "id": "person",
  "title": "person",
  "public": false,
  "description": "",
  "schema": "$uri:property:global/app/neel/object/person/v1/schema",
  "output": "$uri:property:global/app/neel/object/person/v1/instance/#{property.uuid}",
  "script":{
    "onload":"alert('PipeForce-neel')",
    "onblur":"if (src === 'firstName') { alert(data[src]); console.log('name =>',data[src]) }"
  },
  "layout":{
    "items":[
      {
        "field":"firstName"
      },
      {
        "field":"lastName" 
      }
      ]
  }
}

External Script

Step-1: You have to define path inside script as below given example.

You will get the information about form-data, form-schema, form-layout and source from where the event is triggered below are the param names

data, schema, layout, src

• data - you will get form model in JSON format

• schema - you will get the form schema document in JSON format

• layout - you will get then layout config in JSON format

• src - it will give the form field name - for better understanding find attached video

• value - it will give the current value of the element - use for onchange event only

Find the attached video for how to use script in form

{
  "id": "person",
  "title": "person",
  "public": false,
  "description": "",
  "schema": "$uri:property:global/app/pi-4685/object/person/v1/schema",
  "output": "$uri:property:global/app/pi-4685/object/person/v1/instance/#{property.uuid}",
  "script":{
    "path":"$uri:property:global/app/pi-4685/form/script"
  },
  "layout":{
    "items":[
        {
          "orientation":"horizontal",
          "items":[
            { "field":"firstName" },
            { "field":"lastName" },
            { 
              "field":"gender", 
              "class":"col col-md-5"
            }
          ]
        }
      ]
    }
}

Step-2: You have to define script as below example. It will support only these events and add only those events required. For this follow example 2.

(function () {
  function onload(data, schema, layout, src) {
     alert('PipeForce PI-4685')
  }
  function onunload(data, schema, layout, src) {
     alert('PipeForce PI-4685 unload')
  }
  function onkey(data, schema, layout, src) {
     console.log('key down')
  }
  function onkeyup(data, schema, layout, src) {
     console.log(data[src])
  }
  function onkeypress(data, schema, layout, src) {
     console.log('key press')
  }
   function onchange(data, schema, layout, src,value) {
     if(src == 'gender') console.log('value selecting')
  }
  function onsubmit(data, schema, layout, src) {
     console.log('Click event')
  }

  function onfocus(data, schema, layout, src) {
     alert('on focus')
  }
  
  // Mouse events
  function onmouseoup(data, schema, layout, src) {
     console.log('mouse up')
  }
  
  function onmousemove(data, schema, layout, src) {
     console.log('mouse move')
  }
  
  function onmouseover(data, schema, layout, src) {
     alert('mouse over')
  }
  
  function onmouseout(data, schema, layout, src) {
     console.log('mouse out')
  }
  
  function onscroll(data, schema, layout, src) {
     console.log('scrolling')
  }
  function onresize(data, schema, layout, src) {
     console.log('resized')
  }
 return {
    onload,onunload,onchange,onfocus,onkey,onkeyup,onkeypress,onscroll, onresize,
    onsubmit, onmouseup, onmousemove, onmouseover, onmouseout
  };
})()

Example 2

(function () {
  function onload(data, schema, layout, src) {
   // Add your code here.
  }
  function onchange(data, schema, layout, src,value) {
   // Add your code here.
  }
  return { onload, onchange }
 })()  

Example 3: How to call the Pipeline using script
iam.group.members?name=ALs – its example

(function () {
  
  function onchange(data, schema, layout, src,value) {
   pi.pipeline('iam.group.members?name=ALs').then((res)=>{
    debugger
   })
   
  }
  return { onchange }
 })()  

https://quasar.dev/vue-components/select#qselect-api

https://quasar.dev/vue-components/input#qinput-api

https://quasar.dev/vue-components/time#qtime-api

https://quasar.dev/vue-components/date#qdate-api