Form Scripting
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/propertiesdata
- 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 fieldId
variable 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: https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event
onchange
Emitted when the widget value was changed.
Also see: https://quasar.dev/vue-components/input#qinput-api
onfocus
Emitted when widget gains focus.
Also see: https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event
onkeydown
This event occurs when the user presses a key on the keyboard
https://www.w3schools.com/jsref/event_onkeydown.asp
onkeyup
Emitted when the user releases a pressed key.
Also see: https://developer.mozilla.org/en-US/docs/Web/API/Element/keyup_event
onload
Emitted after the page was initially loaded.
Also see: https://www.w3schools.com/jsref/event_onload.asp
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.