Thursday, May 19, 2016

JavaScript components made easier

Orbeon Forms's toolbox, which presents the choice of form controls available when you build a form, is fully customizable. Each form control points to a file containing information about the control and, in the case of custom controls (also known as components), the behavior of the control itself.

Some components do not require any custom JavaScript code: you implement all the logic with XForms. These components often combine other existing controls (such as a date components made of separate input fields or dropdown menus) and "glue" them together, visually as well as functionally (for example the value of multiple fields are put together to build an ISO date string).

On the other hand some components encapsulate functionality mainly implemented in JavaScript. And in such cases, XForms and JavaScript must communicate. For example, when a component becomes visible, some JavaScript initialization must run. Similarly, a user interaction might dispatch a JavaScript event which must result in a change of the control's value in the form.

Orbeon Forms does this with the help of a JavaScript class called the component's companion class. Each JavaScript-based component defines such a class, which handles the component's lifecycle and holds custom data and functions. One instance of this class is automatically created by Orbeon Forms for each instance of relevant (visible) control. We call these instances companion instances.

And the good news is that since Orbeon Forms 2016.1, a new javascript-lifecycle mode lets Orbeon Forms handle important aspects of the component's lifecycle. This makes it much easier to implement JavaScript-based components.

All the details are available in the documentation of JavaScript Companion Classes. We hope you'll like this new feature of Orbeon Forms 2016.1!

Thursday, May 5, 2016

Speaking JSON

JSON is the most popular format for browser/server communication. It is used more and more for all types of web services and as time goes it becomes more and more likely that you will encounter web services based on JSON rather than XML.

So Orbeon Forms had to support JSON, which is why we worked hard to ship Orbeon Forms 2016.1 with JSON support out of the box!

We considered two levels of JSON support:

  • First, within the forms engine.
  • Second, from Form Builder and Form Runner.

With Orbeon Forms 2016.1, JSON support is fully integrated at the XForms level, and submissions (service calls) can send and receive JSON.

Because natively XForms is XML-based, JSON goes through a transformation when it is received, following the proposed XForms 2.0 specification. This is designed so that you can access the resulting XML with path expressions in a way very similar to how you do it in JavaScript. Say you have this JSON:

{
   "father":{
      "given":"Mark",
      "family":"Smith"
   },
   "mother":{
      "given":"Mary",
      "family":"Smith"
   }
}

In JavaScript you use the expression mother.given to find “Mary”. From XForms, you use instead mother/given. It is pretty natural in many cases. For more details, see also submissions JSON support.

Similarly, XML goes through the reverse transformation when you need to send JSON to a service. The idea is that you can roundtrip JSON from a service.

With Orbeon Forms 2016.1, Form Builder and Form Runner only have limited JSON support, but receiving JSON from a service already works: if the service response contains application/json, it is automatically processed, and you can access the received data in actions via path expressions. For more deatils, see HTTP services JSON support.

In the future, we plan to make sending JSON to services from Form Builder / Form Runner possible and user-friendly, and we also want to allow sending form data in JSON format to services. Stay tuned!