Form action plugin
A form action plugin is a type of plugin that can add extra functionality to the form logic. Use a form action plugin instead of a scripted action when you want to be able to reuse the functionality within your application and/or share the functionality on Grexx Marketplace
Standard form actions include:
- Enabling or disabling a field
- Showing or hiding a field or group of fields
- Making fields mandatory or optional
- Setting or removing a value
Actions are performed when the conditions in an If then else are satisfied. The If then else conditions can be evaluated when the form is first loaded, when any changes are made to the form, or when a particular field is changed.
With a form action plugin you can implement more sophisticated functionality, such as:
- Removing spaces from a value.
- Formatting a value as telephone number, zip/post code, or other custom format.
- Performing a zip/post code check based on a zip/post code field.
- Validating data against an external source.
Structure
A form action plugin always has the same structure. You can configure the following options:
- Form fields that you want to use within your plugin.
- Form field groups that you want to use within your plugin.
- Any additional settings you want to use within your plugin.
- Action(s) that you can then link to the
On startof the form or theOn changeof certain form fields or groups.
To view the Grexx Platform JavaScript Library documentation, append docs/api/js to the URL of any of your application environments. For example, https://my-site-dev.grexx.today/docs/api/js
You can use the same API.v1.* functions in your form action plugin as in your widget plugin.
Standard structure
gx.plugin.createFormAction('myFirstFormActionPlugin') //== Here you create the plugin and give it the tag 'myFirstFormActionPlugin'. This cannot be changed anymore.
.setDisplayName('My First Plugin') //== The functionality will be displayed in the formlogic designer under this name, the 'DisplayName'.
.addField('myField1') //== Add a field named 'myField1'; you will have access to this in your action later.
.addField('myField2', 0) //== The second parameter (optional) indicates the minimum number of fields that need to be configured for this option.
.addField('myField3', 0, 0) //== The third parameter (optional) indicates the maximum number of fields that can be configured for this option. 0 means unlimited.
.addField('myField4', 0, 0, 'goFancy') //== The fourth parameter (optional) is the action you want to link to the change event of this field, in this case, the 'goFancy' action.
.addField('myField5', 1, 2, 'checkStuff') //== The field 'myField5' must be configured and can contain a maximum of 2 fields. The 'checkStuff' function is triggered on onchange.
.addGroup('myGroup1', 0, 1) //== You can also configure an entire group; this can, for example, be hidden or shown.
.setAction('goFancy', function (fields, groups, settings, form) {
//== Action 'goFancy' fires when the field configured as 'myField4' changes value.
})
.setAction('checkStuff', function (fields, groups, settings, form) {
//== Action 'checkStuff' fires when the field(s) configured as 'myField5' changes value.
})
.setAction('always', function (fields, groups, settings, form) {
//== This action always fires when triggered by form-logic.
}, {isDefault: true});
Actions
Within an action you have access to the fields, groups, and settings that you have added to the form action plugin. You can perform various actions on fields and groups. A field or group is always returned as a collection of 0 or more items. The actions you call are performed on all items within that collection.
//== This is a continuation of the code under `Standard construction`
gx.plugin.createFormAction('myFirstFormActionPlugin')
.setAction('goFancy', function (fields, groups, settings, form) {
const f = fields('myField4'); //== f is a collection of 0 or more formfields
gx.log.trace(['myField4', f.length]); //== console will print the amount of configured fields for this tag.
gx.log.trace(['myField4', f.hasValue()]); //== true when all fields in myField4 have a value.
f.getValue(); //==> return ['value1', 'value2']
f.disable(); //==> disables all fields in f
f.enable(); //==> enables all fields in f
f.show(); //==> show all fields in f
f.hide(); //==> hide all fields in f
f.setOptional(); //==> set all fields in f to optional
f.setRequired(); //==> set all fields in f to required
f.setEmpty(); //==> Set all fields in f to empty value
f.setValue('newValue'); //==> set all field-values in f to 'newValue'
f.removePicklist(); //==> removes picklist from all fields in f
})
Default action
Sometimes you want an action to fire without defining any fields, or for the same action to fire for all fields. By marking an action as default, that action is executed when the form logic thinks it is time for it. That is:
- When a change is made to any of the defined fields.
- When the form logic passes this plugin, for example when reaching an
On field changeblock or aThenorElseblock.- If your plugin is at the top level of the form logic, a default action always happens.
You can only have one default action per plugin. You indicate this by passing {isDefault: true} as the third parameter of setAction:
.setAction('goFancy', function (fields, groups, settings, form) { /* function body here */ }, {isDefault: true})
If you do not have a default action and have not defined an action for any form field, your plugin will not do anything.
Examples
The following example populates address fields based on a postcode and house number using postcodeapi.nu.
//== Postcode lookup
gx.plugin.createFormAction('postcodecheck')
.setDisplayName('Postcode Lookup (NL)')
.addField('postcode', 1, 1, 'lookup')
.addField('housenumber', 1, 1, 'lookup')
.addField('extension', 0, 1, 'lookup')
.addField('street')
.addField('city')
.addField('municipality')
.addField('state')
.setAction('lookup', function (fields, groups, settings, form) {
if ( fields('postcode').hasValue() && fields('housenumber').hasValue() ) {
const postcode = fields('postcode').getValue()[0],
housenumber = fields('housenumber').getValue()[0],
extension = fields('extension').getValue()[0],
activity = "1:146:1967";
API.v1.postActivity(activity, API.v1.info.getGlobalCaseId(), { "url": `https://api.postcodeapi.nu/${postcode}/${housenumber}` }).then(function ( response ) {
const result = response.result.result.returnResult.resource;
console.log('result', result);
fields('street').setValue(result.street);
fields('city').setValue(result.town);
fields('municipality').setValue(result.municipality);
fields('state').setValue(result.province);
});
} else {
//Not all required fields are present
gx.log.trace(['Missing some field values']);
}
});
The following example validates that the value entered in a field matches the BSN format.
gx.plugin.createFormAction('11proef')
.setDisplayName('BSN validation')
.addField('num', 1, 1, '11proef')
.setAction('11proef', function (fields, groups, settings, form) {
if (fields('num').hasValue()) {
let num = fields('num').getValue()[0],
check = function (num) {
num = num.replace(/\D/, "");
let total = 0;
for (i = 1; i < 10; i++) {
total += parseInt(num.charAt(i - 1), 10) * (10 - i);
}
return (num.length === 9 && total % 11 === 0);
};
if(check(num)) {
gx.log.trace('Number is valid');
} else {
gx.log.trace('Number is not valid');
}
} else {
//Not all required fields are present
gx.log.trace(['Missing some field values']);
}
});
You can import additional form action plugins as examples from Grexx Marketplace: filter products by the "Plugin" category to view all available plugins.
Logging in the JavaScript console
The output in the console is suppressed by default, so no output is visible from console.log or gx.log.trace.
Run the following command in the console to enable this output:
localStorage.debug = true