On this page:
You have the choice of two different approaches:
- If a designer uploads a custom.js file to a project, it is only available for forms/workflows in that project. Refer to Method 1a below for the details.
- If a Live Forms superuser/tenant admin uploads custom.js to the tenant, then the custom.js will be available to all forms/workflows in the tenant. Refer to Method 1b below for the details.
Custom.js scripts can be uploaded at two levels in Live Forms:
- If a custom.js file contains the wrong custom handler for the level you are uploading it to, you may see a delay in loading and the custom.js will not work. Verify that the CustomEventHandler is correct.
Follow these steps:
Browse your hard drive for your script file, Click Upload. Your file will be uploaded and it will display with the name Custom Script even though your script file may have another name.
If you need to modify the script, you must download it, make your modifications and then upload it again. When you download the script by selectingDownload from the Action Menu, it will be named custom.js.
Follow these steps:
Login to Live Forms as a superuser/tenant admin. Navigate to the Manage Tenant screen. Click the Manage Script link.
Browse your hard drive for your script file, then click Upload. Your file will be uploaded and it will display with the name Custom Script even though your script file may have another name.
If you need to modify the script you must download it, make your modifications and then upload it again. When you download the script by clicking on theDownload icon, it will be named tenantcustom.js.
- f you upload a custom.js file to the Tenant Level and the event handler is named CustomEventHandlers not TenantCustomEventHandlers you will not see an error message. The function may operate correctly but you may notice a delay in loading the form/workflow in Use mode.
You create another custom script to add the dashes to the Social Security Number as the user is typing. The class name is SSN1. You upload this custom script to an project.
A designer creating forms/workflows in the project will have access to both custom scripts. Both scripts will function properly.
Uploading custom.js files with the same class name on the project and tenant levels
- Add a message control to your form.
- Add a <script> tag in the message property.
Here is an example of the script tag: Drop your code inside of the script tag.
What can you do in a handler
- CustomView.$frevvoControl(el) returns the HTML element corresponding to the Live Forms control that triggered the handler. This is typically a DIV HTML element and typically has CSS class 'f-control'
- CustomView.getExtId (el) returns the name of the control as set in the Form Designer.
- CustomView.getIndex (el) returns the index of the control in its enclosing repeat control if the control is repeating. If the control is not repeating, it returns -1.
- CustomView.hasClass (el, className) returns true if the control has the indicated CSS class, false otherwise.
Custom Event Handler Example
Here is an example of a custom event handler:
Let's look in a little more detail
- You must have a class called CustomEventHandlers declared. Note that it is case-sensitive.
- It must have a method called setup() which takes a single argument (called el above). When the form is loaded, Live Forms will call this setup() method for each control in the form and will pass in the control as the argument.
- For each control we are interested in, the CustomEventHandlers class has a handler method. All handlers are functions that take two arguments: the event that triggered the handler and the control itself.
- The example above uses a custom CSS class on the control in question to figure out if it's the control we are interested in. You can set a custom css class for any control in the Form Designer.
- We're interested in two controls: the Submit button which already has a CSS class s-submit and a user-defined input control with custom CSS class my-class. For each control, we've associated a handler as described above. To associate a handler, call FEvent.observe (el, EVENT_NAME, handler) using the syntax above. The EVENT_NAME can be any standard event. fired by your browser e.g. click (also called onClick) or change (also called onChange).
- When the event is question is fired by the control in question, your handler will be called.
- In addition to the event handlers, you can also provide methods that are called when the form is Saved using the Save/Load feature.
- The onSaveSuccess() method is called when a submission is saved and the resulting submission ID is passed in.
- The onSaveFailure() method is called when the save fails.
Extensions for workflows
In addition to the above, workflows also support a few other methods.
As the method names indicate
- onNextClicked() is called when the Continue button is clicked: this button might be labeled Continue or Finish or might have a custom label assigned by you. The parameters are the name and id of the current activity (step) in the workflow.
- onNavClicked() is called when the user clicks on a link in the Navigation toolbar if it is displayed. The parameters are the name and id of the activity (step) in the workflow that is clicked.
- Finally, onSaveSuccess() and onSaveFailure() for workflows must be defined in the CustomFlowEventHandlers class.
It's not currently possible to directly fire a custom.js handler from a business rule. You can write a form.load rule that sets the value of a hidden control and set a change handler for that control in your custom.js Custom Handlers.