I recently worked on an application that was used to demonstrate the process of capturing data from a mobile application created using PhoneGap, and pushing that data into a LiveCycle server’s workflow engine. Since my data was being captured and stored locally as JSON objects, I asked myself “why can’t I use a template to generate the XML for sending to LiveCycle?” … It turns out you can, and its not that hard at all.
The entire mobile experience was created using HTML, CSS, and JavaScript. Since the prototype application was intended to work in offline scenarios, it didn’t push to a server automatically. Rather you had to manually push data to LiveCycle once you’re on the network via a REST API service invocation. Since I couldn’t guarantee that the device was on the network, all data was collected on the client using a standard HTML form and data was saved locally as JSON strings using PhoneGap’s local storage imlementation.
Since the data was stored with “plain old” JSON, it is really easy to manipulate using JavaScript. You can transform it into HTML, raw text, XML, or whatever format you want. To present the data back to the user within the application experience I took advantage of the templating features from underscore.js. Templating in HTML/JS apps enables you to separate dynamically generated HTML structure from your application logic, and it keeps your JavaScript code clean without having to manage lots of string concatenation. I used these templating features to generate all views within the application, including tabular data views and even HTML forms that auto populated with data. Basically, anywhere there was an HTML-based view, I used a template to generate that HTML.
The REST API for LiveCycle expects you to pass the information for your form(s) in XML formats that match the information captured within the workflow process. The exact structure of the XML depends upon how the LiveCycle server/document workflow is configured, but in any case, it is still XML. You can use templates to generate this XML, or any text-based structure for use in any service call.
This technique can work in many scenarios, and with any endpoint – whether it is REST, SOAP, some other JSON string format (transformed), or something entirely different altogether. Templates enable you to cleanly generate text strings from JSON objects.
Here’s basically how I used templating:
- JSON to HTML – I used teampltes to generate my HTML views within the application.
- JSON to XML – I used templates to generate the XML structure that was passed as parameters to the LiveCycle server’s REST API.
Below is a really simple example showing how you can use templates to transform JSON objects for use within your applications. It uses jQuery for quick and easy DOM manipulation, Twitter Bootstrap for UI styling, and underscore.js for templates.
Click on the first button to display a string version of the JSON object using JSON.stringify() (without any templating), click the second to display a HTML table that was generated using a template, and click the last button to generate an XML string using a template.
This example is intended to be pretty simple – all of the JavaScript and the templates are included in one file, and it only demonstrates how to generate XML strings. I’m not posting it to a server in this example. Once you’ve generated the XML string, you could do anything with it, I posted it to the LiveCycle server using a simple jQuery $.ajax() call.
You can download the full source for this example here.
Raw JSON
Let’s first examine the raw JSON object. It is an array that contains several objects.
[js]var rawData = [
{id:1, firstName:"Homer", lastName:"Simpson", email:"homersimpson@fakeemail.com", phone:"555-123-1234"},
{id:2, firstName:"Bart", lastName:"Simpson", email:"bartsimpson@fakeemail.com", phone:"555-123-2345"},
{id:3, firstName:"Marge", lastName:"Simpson", email:"margesimpson@fakeemail.com", phone:"555-123-3456"},
{id:4, firstName:"Lisa", lastName:"Simpson", email:"lisasimpson@fakeemail.com", phone:"555-123-4567"},
{id:5, firstName:"Maggie", lastName:"Simpson", email:"maggiesimpson@fakeemail.com", phone:"555-123-5678"} ];
[/js]
Generating HTML
Next, let’s examine how the HTML structure gets generated. The generateHTML() function uses an underscore.js template to generate an HTML string, which gets loaded as the content HTML of the “output” div.
[js]function generateHTML() {
var data = { target:rawData };
var template = _.template( $("#tpl-html").text() );
$("#output").html( template(data) );
}[/js]
The HTML table is generated using the following template. Notice that underscore.js template uses a JSP-like syntax for injecting values. This template will loop over the array content and will generate a table row for each entry.
[html]<div class="well">
<table class="table">
<thead>
<tr>
<th>ID</th>
<th>Name</th>
<th>Email</th>
<th>Phone</th>
</tr>
</thead>
<tbody>
<% _.each( target, function(i) {%>
<tr>
<td><%= i.id %></td>
<td><%= i.lastName %>, <%= i.firstName %></td>
<td><%= i.email %></td>
<td><%= i.phone %></td>
</tr>
<% }); %>
</tbody>
</table>
</div>[/html]
Generating XML
You can generate XML strings for use in REST endpoints using this exact same approach. Look at the generateXML() function below. It uses a template to render the exact same data into an XML string:
[js]function generateXML() {
var data = { target:rawData };
var template = _.template( $("#tpl-xml").text() );
var xml = template(data);
}[/js]
The only real difference between these two examples is the template. The template used to generate the XML string is displayed below:
[html]<data>
<% _.each( target, function(i) {%>
<entry>
<id><%= i.id %></id>
<name>
<last><%= i.lastName %></last>
<first><%= i.firstName %></first>
</name>
<contact>
<email><%= i.email %></email>
<phone><%= i.phone %></phone>
</contact>
</entry>
<% }); %>
</data>[/html]
Again, you can download the full source for this example here.
Enjoy!