Getting ready

1. Download a nightly build of Orbeon Forms.
2. Unzip the orbeon.war file and deploy it in Tomcat (say under webapps/orbeon).
3. Let’s say after this the application is deployed on http://localhost:8080/orbeon/.
4. Unzip WEB-INF/lib/orbeon-resources-public.jar in a temporary directory, and copy the ops directory to WEB-INF/resources (to create a directory WEB-INF/resources/ops).
5. You will be modifying files in that ops directory. (This is a way of overriding what ships with Orbeon Forms in the orbeon-resources-public.jar, so you can easily modify those files.)
6. [SINCE 2012-05-03] Set the Orbeon Forms run mode to dev in web.xml.
   
   Before 2012-05-03 builds, do the following:
   
   Create a file WEB-INF/resources/config/properties-local.xml, with this content:
   
   
   <properties xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:oxf="http://www.orbeon.com/oxf/processors"
            xmlns:xi="http://www.w3.org/2001/XInclude">
     <property as="xs:boolean" name="oxf.xforms.minimal-resources" value="false"/>
     <property as="xs:boolean" name="oxf.xforms.combine-resources" value="false"/>
</properties>
   
   
   (Setting oxf.xforms.minimal-resources to false, the “full” versions of the JavaScript files will be used, which makes debugging easier. When oxf.xforms.combine-resources is set to true, all the JavaScript files are combined into one file, which improves performance, but make debugging harder.)

Coding

• Most likely the only file you will need to edit is ops/javascript/xforms.js. You can find there most of the client-side JavaScript code of Orbeon Forms.
• You will want to find or create a test case so you can check that what you are implementing works. Most of the time you will use the Controls example, or one of the existing XForms sandbox examples, or you will create a new XForms sandbox example. To go to the XForms sandbox click on "XForms Sandbox" on the examples list on the right. Then go to the Test Samples tab, and select an example. Those examples are stored in resources/apps/xforms-sandbox/samples. As necessary you can extend existing examples, or create a new one (new files will be automatically picked up and listed in the the UI).
• You will then spend most of your time changing xforms.js and reloading the example you selected in the browser, checking that the wonderful changes you have done are working as expected.

Testing

• Once the feature you are implementing is working as expected, go through a at least a few of the examples to make sure that everything still works as expected. The XForms Controls, Government Forms, To-Do Lists, and Instant Translation are a good start.

Tools

• Firebug, the Firefox plugin, is a must-have. We do most of the development on Firefox, and then test on IE (rigorously), Safari and Opera (somewhat less rigorously).
• A good JavaScript editor. IntelliJ makes a great JavaScript editor but if you don't also need IntelliJ for other reasons (like editing Java or XML) you might prefer to use a more lightweight editor.
• See below for IE-specific tools.

JavaScript development in IE

Tools

• If the problem you want to debug also happens with IE8, or only happens in IE7 but can be reproduced in IE8 with the Document Mode set to IE7 Standards, then use the IE8 Developer Tools. The IE8 Developer Tools pales in comparison to Firebug, but it is better than anything you'll get on IE6 or IE7.
  
  
• If the bug you're working on is nasty enough that you can't reproduce it with IE8 in IE7 Standards mode, and can only reproduce it with IE6 or IE7, the following tools might help:
  
  
  • Firebug Lite implements some of the features of Firebug. To start Firebug Lite:
    
    
  • If your page uses XForms and is executed by Orbeon Forms, run:
    
    
    ORBEON.util.Test.startFirebugLite();
    
    
  • A reliable way to start Firebug Lite is to:
    
    
  • Load the page you want to debug.
  • Once it is loaded, paste the following link in the URL bar, and press enter.
    
    
    javascript:var%20firebug=document.createElement('script');firebug.setAttribute('src','http://getfirebug.com/releases/lite/1.2/firebug-lite-compressed.js');document.body.appendChild(firebug);(function(){if(window.firebug.version){firebug.init();}else{setTimeout(arguments.callee);}})();void(firebug);
    
    
  • Another way is to include that link (in previous bullet point) in the HTML of the page itself, and click it to start Firebug Lite, i.e.:
    
    
    <a href="...">Start Firebug Lite</a>
    
    
  • You can also include the following in the <head> section of your page to load Firebug Lite as soon as the page loads.
    
    
    <script type="text/javascript"
        src="http://getfirebug.com/releases/lite/1.2/firebug-lite-compressed.js"/>
    
    
  • (We found that using this link as a bookmarklet not to be working, at least with some versions of IE6.)
    
    
  • The Internet Explorer Developer Toolbar can be quite helpful. It is not as good as Firebug, but better than nothing. If you have to deal with an IE problem you can't reproduce on Firefox, then this will come handy.
    
    
  • The Microsoft Script Debugger has been around for a long time. I remember using it in 2000, and unfortunately it feels like it hasn't been improved since then. But again, if you have to deal with an exception that happens only on IE, the Microsoft Script Debugger can really help.

Finding where exceptions originated

When you have the Microsoft Script Debugger installed, if a JavaScript exception occurs, the debugger will ask you if you want to start debugging. However this won't happen if the exception occurs while an Ajax response is processed because in handleResponse we catch exceptions to display a user-friendly message. When debugging an issue of this nature, you might want to comment out the try and catch block which is around most of the code in handleResponse.