1 What is Form Scripting?
2 Implicit Form Script Variables
3 Inline Form Script
4 External Form Script
5 Calling a Command from inside a Form Script
6 Form Events Reference
- 6.1 onbeforedatabind
- 6.2 onblur
- 6.3 onchange
- 6.4 onfocus
- 6.5 onkeydown
- 6.6 onkeyup
- 6.7 onload
- 6.8 onsubmit

What is Form Scripting?

In some cases, additional logic must be added to a form. For example

update the value of a form widget based on the changes in another widget
perform special calculation for some widget values
perform more complex validation of widget values (especially if widgets must be “cross” validated)
and more…

In all of these cases, the standard form toolings are often not sufficient. For these cases you can use Form Scripting: You can hook-in to certain events and execute custom JavaScript code in order to implement your additional logic.

Form Scripting requires JavaScript knowledge!
By using it, you could leave the field of “easy” low coding and could potentially create very complex algorithms which could be very hard to explain to other team members. Therefore, make sure in the first step, that Form Scripting is the only way to solve your task. If so, then make sure to write as little and clean code as possible to implement your task using Form Scripting.

See here for a full JavaScript reference: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference

Implicit Form Script Variables

These variables will be automatically passed to any form script:

context - An object that provides component(vue) functionalities/properties
data - The current form data model as JSON. This way you can access the current value of all widgets of the form by using the id of the widget. Also this way you can update the value of a widget.
schema - The Form Schema which is related to this form in JSON format.
config- The Form Config of this form as JSON document.
value - The current value of the widget which has fired this event.
fieldId- The id of the field(as defined in the Form Schema) which has fired this event and therefore caused the script to be executed.
pi - The PIPEFORCE object which allows you to communicate with the backend and execute pipelines and commands for example from inside JavaScript.

Inline Form Script

You can add a form script “inline” inside the Form Config using the script attribute. Inside this attribute you can add as many event to script mappings you like. The script must be written in a single line. This approach is meant for short and simple scripts no longer than one line.

For example:

{
  "id": "...",
  "schema": "...",
  "output": "...",
  "script": {
    "onload": "alert('Form has been loaded')",
    "onblur": "if (fieldId === 'firstName') { alert(data[fieldId]); console.log('name =>',data[fieldId]) }"
  },
  "layout": {
    ...
  }
}

External Form Script

In case you have to implement more complex logic which is more than a single line, then consider to put your form script into a property in the property store and link to it like this:

...
"script": {
    "path": "$uri:property:global/app/myapp/form/your-script"
},
...

The external script must look like this example:

(function () {

  // Listen to the onkey event
  function onkeyup(context, data, schema, config, fieldId) {
     console.log('on key up')
  }
  
  // Listen to the onchange event
  function onchange(context,data, schema, config, fieldId, value) {
     if(fieldId == 'gender') console.log('value selecting')
  }
  
  // Return the event methods
  return { onkeyup, onchange };
  
})()

For each event you have to define a function with the name of the event and then return it.

Inside the method you can use the fieldIdvariable in order to check whether this event was caused be the widget you are interested in.

Note
You cannot mix an external script with inline definitions; you have to choose one of them.

Calling a Command from inside a Form Script

You can also call a command from inside a form script like this example shows:

You can also execute a PIPEFORCE URI and return the result for further processing:

Example 2

You can also show the alert/notify message https://quasar.dev/quasar-plugins/notify#notify-api

Form Events Reference

The form events you can hook-in for are all liste here:

`onbeforedatabind`

This event method is called after page was loaded but before form data is set on widgets. This way you can transform and change data if required, before it gets finally bind to the the form fields.

For example in case you would like to do some extra date formats or highlight some fields depending on the initial data.

`onblur`

Emitted when the widget loses focus.
Also see:

`onchange`

Emitted when the widget value was changed.
Also see:

`onfocus`

Emitted when widget gains focus.
Also see:

`onkeydown`

This event occurs when the user presses a key on the keyboard

`onkeyup`

Emitted when the user releases a pressed key.
Also see:

`onload`

Emitted after the page was initially loaded.
Also see:

`onsubmit`

Emitted when form submit was initiated but before the data gets send.

Cancel submit

In some cases, the submit of a form must be cancelled. For example some additional validations have been failed. To do so, you have to return false in order to cancel the submit.

If the return value is true or undefined (no return value), the submit wont be cancelled.