Administrators will now be able to set up and manage all the Form Rules within an App through a powerful feature called Form Scripts. In this low-coding environment you can configure a custom Form Script to easily create and control all your Form Rules and Actions from one place.
As with Form Rules, Form Scripts will give you full control of the Form Fields in each of your Apps. The core functionality has been retained, expanded upon and made simpler. Now you can compile all your chosen parameters within a single Form Script.
While code is required to create Form Scripts, it is minimal and easy to set up. In this article we will show you how to enable Form Scripts, how they work and the supported Form Action commands. Let's get started.
Note: Form Rules will continue to function normally as the Form Script feature is introduced. Administrators can decide when to convert to Form Scripts.
Edition Qualifier: This feature is available in all FreeAgent Editions.
User Permissions: Only an Administrator can customize Form Scripts.
In this tutorial, we will cover the following topics:
- Enable Form Scripts
- Setting Up Form Scripts
- Form Actions Table
- Example Form Script
Enable Form Scripts
Form Scripts are available at the App level and Lines within the App. Form Scripts will function as parent and child between the App and the Lines in the given App when both are enabled.
Establishing a Form Script for any App will make future Rule changes and additions more efficient and scalable. This is especially true with more Line dependent Apps such as Quotes. Utilizing Form Scripts at the parent App and child Line level can enhance your work processes in powerful new ways within FreeAgent.
App Setup
Under Admin Settings navigate to Apps Setup and choose your desired App. Select App Configuration, now you will see the 'Form Script' section. In the 'Use Form Script' field, choose 'Yes' to enable the custom code Script field as shown below.
Enter the custom code for your Form Script and click Save. Navigate back to App Configuration to modify your Form Script whenever needed.
Notice that when you enter a Form Field through the 'CTRL + space' command your available Fields will show up by their Field Name. Once selected however, they will auto convert to the System Name of this Field. This is to promote continuity and performance of your Form Scripts across FreeAgent.
Note: When 'No' is selected, existing Form Rules within the App will be used. When 'Yes' is selected, the existing Form Rules will be ignored and the custom code within the Form Script will be active - the Form Script will supersede Form Rules. However the Form Rules will not be deleted. You can choose when to implement Form Scripts per App.
Lines
Form Scripts can be enabled for individual Lines within an App. These Line level scripts can be used in conjunction with the parent App Form Scripts to define Form Rules for the Line itself.
When this feature is combined with the new Inline Edit mode, you can create robust grids where you will be able to directly add and edit Lines based on the rules in your Form Script.
To enable a Form Script for a Line, navigate to Apps Setup. Choose your desired App and select 'Lines.' Add a new Line or edit an existing one. Now you will see a Form Scripts section in the 'Use Form Script' field select 'Yes' to enable Form Scripts.
Now the code window below will be editable. Enter your custom code and click Save. Navigate back to Lines in Apps Setup to disable or change your Form Script.
Setting Up Form Scripts
All the functionality of Form Rules remain, such as the ability to show/hide line columns, make fields mandatory, make fields visible, reset fields, etc. You will still define your Rules via Form Actions, these will now be lines in your code script.
The existing Form Actions available when setting up a Form Rule are readily available in Form Scripts along with other functions that will help you add, define and change Rule parameters quickly from a single place. Let's take a look at these actions and how they are represented in the code script.
You'll notice in the following table that whereas Form Rules had a separate section for Conditions, Form Scripts allow you to set the conditional values directly in the code line along with the Action.
Form Actions Table
Once you've enabled the Form Scripts window by selecting 'Yes' in the Use Form Script field, you will be ready to assemble and edit the code you use to define your Rules. Here are the supported Actions and corresponding code.
| FORM ACTION | CODE |
| Add Validation to a Field | addFieldValidation: (fieldName, validationCallback) |
| Change a Field | fieldChanged: (fieldName) |
| Make Fields Read Only | makeFieldsReadOnly: (fieldNames, value) |
| Make Fields Required | makeFieldsRequired: (fieldNames, value) |
| Make Fields Visible | makeFieldsVisible: (fieldNames, value) |
| Make Line Fields Read Only | makeLineFieldsReadOnly: (lineApp, fieldNames, value) |
|
Make Line Fields Required |
makeLineFieldsRequired: (lineApp, fieldNames, value) |
|
Make Line Fields Visible |
makeLineFieldsVisible: (lineApp,fieldNames, value) |
| Reset Fields | resetFields: (changedField, fieldNames) |
| Set a Field Value | setFieldValue: (changedField, fieldName, value) |
| Hide or Show Columns in Lines | makeLineFieldsVisible: (lineApp, fieldNames, value) |
| Make Columns Read Only in Lines | makeLineFieldsReadOnly: (lineApp, fieldNames, value) |
| Make Columns Required in Lines | makeLineFieldsRequired: (lineApp, fieldNames, value) |
Example Form Script
Take this sales stage example which replaces a Form Rule scenario with 3 Form Script Actions in a simple bit of code
(function(form, context){
//If deal sales stage is 'Closed Won', make amount and closeDate readOnly, set status to closed
if (form.deal_fa_field16 === '69dcb80b-ebb8-43cb-ab61-b23596ac800f') {
context.formActions.makeFieldsReadOnly(['deal_fa_field0', 'deal_fa_field8'], true);
context.formActions.setFieldValue('deal_fa_field13', false);
}
}(form, context));