Live Forms v5.1 is no longer supported. Click here for information about upgrading to our latest GA Release.

Customizing Behavior

We strongly recommend that you are familiar with a JavaScript debugger / web development tool such as the Firebug extension for Firefox.

You can add custom behaviors to your form by adding JavaScript to your form. For example, you may want to change the look of your form's submit button when the user hovers the mouse over the button. It is possible to associate a custom JavaScript handler to any form control.  See Custom JavaScript Examples for sample code.

On this page:

You have the choice of three different approaches:

Method 1:  Add a Message control to your form. Add a <script> tag as the message. Here is an example of the script tag: put your JavaScript inside the script tag.

 <script>
        /* <![CDATA[ */
        code goes here
        /* ]]> */
</script>

Method 2:  Add your JavaScript to the file named custom.js in a custom theme. When custom.js is present in a theme, this file is automatically loaded for any form that uses the custom theme. All JavaScript handlers in custom.js will be available to the form. 

 Make sure that you have read and understood the section on Themes.

Method 3:  Add JavaScript to the WEB-INF/rules/includes.js file located in the <frevvo-home>\tomcat\webapps\frevvo.war. The contents of this file are included in the Rule Execution when the context initializes. You can add any JS that you want with the following caveats:

  • It is not supported by frevvo.
  • It is not guaranteed to be backward-compatible i.e. in the next version, you may have to change this. 

Follow these steps to add JavaScript to the includes.js file:

  1. Stop Live Forms if it is running. 
  2. Change the file extension from .war to .zip if necessary and unpack the frevvo.war file to a temporary location of your choice: e.g. c:\tmp\frevvo-war. 
  3. Navigate to c:\tmp\frevvo-war\frevvo\WEB-INF\rules.
  4. Edit the include.js file and add your custom JavaScript. Save the changes to the include.js file. 
  5. Rezip all the files in the c:\tmp\frevvo-war directory, even the ones you did not edit — if you change directories or zip them differently, Live Forms may not load correctly.

  6. Change the file extension from .zip to .war, if necessary. Copy the updated frevvo.war file to <frevvo-home>tomcat\webapps.
  7. Restart your Live Forms server.

Here is an example of a snippet of code when added to the include.js will allow you to do something like this in a rule: DateControl?.value =MyUtil?.today();

var MyUtil = {
today : function() {
var d = new Date();
var dd = d.getDate();
if (dd<10) dd='0'+dd;
var mm = d.getMonth()+1;
if (mm<10) mm='0'+mm;
var yyyy = d.getFullYear();
return String (mm+"-"+dd+"-"+yyyy);
}
}

What can you do in a handler

You can call any JavaScript code in a handler; you can access the DOM of the page (note that you only have access to the DOM of the iframe in which the form is rendered assuming you're using a standard embedding) or call external code. In addition, you have access to the following methods:

  1. CustomView.$frevvoControl(el) returns the HTML element corresponding to the  control that triggered the handler. This is typically a DIV HTML element and typically has CSS class 'f-control'
  2. CustomView.getState (el) returns the state of the control as a JavaScript object. The state contains things like the label, value, hint, help etc. Use a tool such as Firebug or a different JavaScript debugger to view it in detail.
  3. CustomView.getExtId (el) returns the name of the control as set in the Form Designer.
  4. 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.
  5. 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:

var CustomEventHandlers = {    
    setup: function (el) {      
        if (CustomView.hasClass(el, 's-submit'))        
            FEvent.observe(el, 'click', this.submitClicked.bindAsObserver(this,el));
        else if (CustomView.hasClass(el, 'my-class'))        
            FEvent.observe(el, 'change', this.myHandler.bindAsObserver(this,el));    
    },    
    submitClicked: function (evt, el) {      
        alert ('Submit button was clicked');    
    },    
    myHandler: function (evt, el) {      
        alert ('My Class change handler called');    
    },    
    onSaveSuccess: function (submissionId) {       
        alert ("Save complete. New submission id is: " + submissionId);    
    },    
    onSaveFailure: function () {       
        alert ("Save failed");    
    } 
}

Let's look in a little more detail

  1. You must have a class called CustomEventHandlers declared. Note that it is case-sensitive.
  2. It must have a method called setup() which takes a single argument (called el above). When the form is loaded,  will call this setup() method for each control in the form and will pass in the control as the argument.
  3. 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.
  4. 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.
  5. 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).
  6. When the event is question is fired by the control in question, your handler will be called.
  7. In addition to the event handlers, you can also provide methods that are called when the form is Saved using the Save/Load feature.
  8. The onSaveSuccess() method is called when a submission is saved and the resulting submission ID is passed in.
  9. The onSaveFailure() method is called when the save fails.

More Examples

You can add different event handling to your JavaScript code. This example handles click, mouseover and mouseout events to the Submit button:

 /*  
  * Custom Javascript here.  
  */   
   var CustomEventHandlers = {     
    setup: function (el) {       
        if (CustomView.hasClass(el, 's-submit'))       
        {  
            alert('setting up s-submit events');         
            FEvent.observe(el, 'click', this.submitClicked.bindAsObserver(this,el));         
            FEvent.observe(el, 'mouseover', this.submitMouseOver.bindAsObserver(this,el));         
            FEvent.observe(el, 'mouseout', this.submitMouseOut.bindAsObserver(this,el));       
        }     
    },     
    submitClicked: function (evt, el) {       
        alert ('Submit button was clicked');     
    },     
    submitMouseOver: function (event, element) {       
        alert ('Submit mouse over');     
    },     
    submitMouseOut: function (event, element) {       
        alert ('Submit mouse out');     
    } 
}

Extensions for flows

In addition to the above, flows also support a few other methods.

var CustomFlowEventHandlers = {     
    onNextClicked: function (name, id) {       
        alert ("Next button clicked for activity: " + name);     
    },     
    onNavClicked: function (name, id) {       
        alert ("Nav button clicked for activity: " + name);     
    },     
    onSaveSuccess: function (submissionId) {       
        alert ("Save complete. New submission id is: " + submissionId);     
    },     
    onSaveFailure: function () {       
        alert ("Save failed");     
    }   
}

 As the method names indicate

  1. 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 flow.
  2. 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 flow that is clicked.
  3. Finally, onSaveSuccess() and onSaveFailure() for flows 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.