Wednesday, September 19, 2012

Controller improvements

Image by M. H. Stephens
Until recently, we hadn't updated the Orbeon Forms controller (called the Page Flow Controller or PFC) in a long time. First, it had served us pretty well for many years. Second, the architecture of the controller made it hard to implement certain changes.

But in June we did some refactoring which has made it possible to implement a series of improvements:
  • The configured not-found handler is triggered in more relevant cases, including when accessing a non-existing Form Runner form or document. This works with the controller catching special exceptions, which could not be done before.
  • There is a new error handler. Previously, you had to catch errors at the web application level.
  • There is a new unauthorized handler, which allows you to show a particular page when a user doesn't have access to a given page or service.
  • Path matching is improved:
    • it is more efficient
    • you simply write matcher="regexp" instead of matcher="oxf:perl5-matcher"
    • the matcher can be configured at the top level (regexp or glob)
  • Some elements and attributes now have more meaningful names (the older names are deprecated):
    • the controller element replaces the config element
    • the path attribute replaces the path-info attribute
    • the mediatype attribute replaces the mime-type attribute
  • Resources are served directly, so serving CSS, JavaScript and images should be faster.
  • A new <service> element is introduced, which describes a service instead of a page.
In addition, we have started implementing protection of pages and services. As of M10, pages work like before, while services require a secret token to be present. For now, this means that a service can only be accessed by an Orbeon Forms application and not from the outside world. This means that services are more secure, including services used internally by Form Runner.

For a comprehensive real-life example, see the Form Runner page flow.

Tuesday, September 4, 2012

XForms Debugging Tips

The two pillars of XForms debugging are the XForms inspector and the Orbeon log:

  • The inspector, pictured below, allows you to see changes to your XForms instances right from your web browser, as you interact with the form.
  • Logging is done on the server, to a file generally referred to as orbeon.log. Once you have setup Orbeon Forms to log to that file, a tail -f orbeon.log in a console will tell you about all the events, submissions, and actions happening as you interact with the form.
XForms inspector screenshot
XForms inspector screenshot

But let’s get to the tips part of this post:

  • Visually checking on a condition — In some cases, you’re interested in checking that a condition is met. That condition most likely depends on values in your instance, and you could, with the XForms inspector, keep an eye on the inspector, checking that instances hold the appropriate value. Another way is to write the condition as an XPath expression, and use an AVT to set a style on a part of your form, for instance adding a green border to a section if the condition is met, and a red border if it isn’t, as in:

    style="border: 1px solid {if (condition) then 'green' else 'red'}"
    
  • Logging value changes in the browser console — In other cases, you want to know when a value changes and want to keep track of each value change. You can do this by adding to your form an output control for that value, and upon xforms-value-changed running in JavaScript a console.log() showing the new value, for instance:

    <xf:output value="concat('My value ', expression)"
            style="display: none">
        <xxf:script ev:event="xforms-value-changed">
            console.log(ORBEON.xforms.Document.getValue(this));
        </xxf:script>
    </xf:output>
    

    If you’re only interested in the value showing in the log, and don’t want it to be also displayed in the form, you can add a style="display: none" on the <xf:output>, as done in the above snippet. And you can generalize this technique to log in the browser console anything you’d like, upon any XForms event.