Feed items

In a prior blog entry, I told you about the powerful data-driven dynamism available in Lotus Forms due to the features of XForms.  I used the example of a Questionnaire or Survey that used an <xforms:repeat> in an XFDL <table> to expand to any length of survey and respond to a mixture of question/answer types.

One the one hand, this is a neat, easy to understand example that helps you understand how a Lotus Form could dynamically respond to web service query results that arrive during the form interaction experience.  However, many many applications, including the Survey/Questionnaire, have the property that the "data" (e.g. the questions and answers) exist before the form is even delivered to the end-user.

A bit of terminology.  We say we have a "mid-pop" operation when we have a form that must be responsive to web service query results.  This is because you're in the middle of the form fill experience when an operation occurs that populates the form with more data from a server data source.  We say it is a "pre-pop" operation when the data can be placed into the form before it is delivered to an end-user.  Even if it is not the first user in a business process, if the data can be put in the form before a particular user's interaction experience begins, it is a pre-pop.

Of course, pre-pop can be handled as just an easy special case of mid-pop, as I did in the prior blog entry.  On the other hand, Lotus Forms is fully and completely an XML technology, so the tools of the XML technology stack can be brought to bear on this kind of problem with great results in terms of efficiency and simplicity.

When a user requests a particular questionnaire, the responding servlet or portlet can run a simple XQuery to get the survey XML, which still looks something like this:

<survey>
  <item>
     <question type="yesno">Do you like apples?</question>
     <answer></answer>
  </item>
  <item>
     <question type="likertscale">It is OK for apples to have a powdery texture.</question>
     <answer></answer>
  </item>
  <item>
     <question type="closedselection">What is your physical gender?</question>
     <answer></answer>
     <choices>
        <choice label="Female" code="F"/>
        <choice label="Male" code="M"/>
     </choices>
  </item>
  ...
</survey>

Then, rather than placing this XML data into the <xforms:instance> of a Lotus Form containing an <xforms:repeat>, the servlet or portlet code can run a simple XSLT to generate the Lotus Form with an <xforms:instance> containing the survey data plus the exact XFDL+XForms user interface controls needed to present each survey question and collect an answer from the user.

Compare the approach in the prior blog entry to the following XSLT fragments.  Here's a  first fragment that sketches out the top-level stylesheet for generating the Lotus Form:

<?xml version="1.0"?>

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
 xmlns="http://www.ibm.com/xmlns/prod/XFDL/7.7">

<xsl:template match="/">
  <xsl:apply-templates/>
</xsl:template>

<xsl:template match="survey">

<XFDL xmlns="http://www.ibm.com/xmlns/prod/XFDL/7.7"
      xmlns:custom="http://www.ibm.com/xmlns/prod/XFDL/Custom"
      xmlns:ev="http://www.w3.org/2001/xml-events"
      xmlns:xfdl="http://www.ibm.com/xmlns/prod/XFDL/7.7"
      xmlns:xforms="http://www.w3.org/2002/xforms"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <globalpage sid="global">
      <global sid="global">
         <xformsmodels>
            <xforms:model id="model">
               <xforms:instance id="data" xmlns="">
                  <!-- Here you have to dump the whole input document as a serialization -->
               </xforms:instance>
            </xforms:model>
         </xformsmodels>
      </global>
   </globalpage>
   <page sid="PAGE1">
      <global sid="global">
         <label>Survey</label>
      </global>
 
      <xsl:apply-templates/>  <!-- defaults to children, which are 'item' elements -->
  </page>
</XFDL>

</xsl:template>

...

</xsl:stylesheet>

The match on the <survey> element produces the outermost XFDL element and a <page> into which the XFDL+XForms form controls are generated by other XSLT templates, such as those shown below. You can either do some XSLT magic to place the whole <survey> inside the <xforms:instance> or you can just pre-pop the Lotus Form with it after the XSLT has generated it. 

Here's a sample pseudo-template that matches a survey <item> whose question type indicates it is a yes/no question, and it produces a check box input control:

<xsl:template match="item[question/@type = 'yesno']">
   <check sid="Need to generate a unique ID here">
      <xforms:input ref="item[need to numerically identify the item here]">
        <xforms:label ref="question"/>
      </xforms:input>
   </check>
</xsl:template>

Here are more sample pseudo-templates for a one-line free text input, a radiogroup for a 1 to 5 scale, and a closed selection drop-down control:

<xsl:template match="item[question/@type = 'onelinetext']">
   <field sid="Need to generate a unique ID here">
      <xforms:input ref="item[need to numerically identify the item here]">
        <xforms:label ref="question"/>
      </xforms:input>
   </field>
</xsl:template>

<xsl:template match="item[question/@type = 'likert']">
   <radiogroup sid="Need to generate a unique ID here">
      <xforms:select1 ref="item[need to numerically identify the item here]" appearance="full">
        <xforms:label ref="question"/>
        <xforms:item>
           <xforms:label>Strongly disagree</xforms:label>
           <xforms:value>1</xforms:value>
        </xforms:item>
        <xforms:item>
           <xforms:label>Disagree</xforms:label>
           <xforms:value>2</xforms:value>
        </xforms:item>
        <xforms:item>
           <xforms:label>Neither agree nor disagree</xforms:label>
           <xforms:value>3</xforms:value>
        </xforms:item>
        <xforms:item>
           <xforms:label>Agree</xforms:label>
           <xforms:value>4</xforms:value>
        </xforms:item>
        <xforms:item>
           <xforms:label>Strongly agree</xforms:label>
           <xforms:value>5</xforms:value>
        </xforms:item>
      </xforms:select1>
   </radiogroup>
</xsl:template>

<xsl:template match="item[question/@type = 'closedselection']">
   <popup sid="Need to generate a unique ID here">
      <xforms:select1 ref="item[need to numerically identify the item here]" appearance="minimal">
        <xforms:label ref="question"/>
        <xforms:itemset nodeset="choices/choice">
           <xforms:label ref="@label"/>
           <xforms:value ref="@code"/>
        </xforms:itemset>
      </xforms:input>
   </check>
</xsl:template>

So, hopefully these are enough examples for you to get the idea of how you might write templates that produce combobox date pickers, combobox open selection controls, check box groups and so forth.   I recommend using this technique for this kind of problem because it is more efficient than the <xform:repeat> approach, which generates all possible user interface controls for each question and then only shows you the UI control for the type of question/answer.  With this approach, you only get an XSLT template match for the exact user interface control you need, so you've done a better job of leveraging more of the tools available in the XML technology stack.

There are lots of advanced IBM libraries to help you efficiently perform XML-based processing functions, including the IBM Websphere Application Server XML Feature Pack and the XML tooling in IBM Websphere Portlet Factory (the Bowstreet assets).  However, if you're just looking to get started and test drive an idea like this, you could probably start with the XSLT transform capability built right into Java.  Something like this:

/*
Simple XSLT Transform Invocation
Copyright (c) 2010, IBM Corporation
All rights reserved.

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this
  list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice, this
  list of conditions and the following disclaimer in the documentation and/or
  other materials provided with the distribution.

* Neither the name of the IBM Corporation nor the names
  of its contributors may be used to endorse or promote products derived from this
  software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/

import java.io.*;
import javax.xml.transform.*;
import javax.xml.transform.stream.*;

public class applyXSLT {
 static private String findArg( String[] args, String argName )  {
  int ix = -1;
  
  for ( int i = 0; i < args.length; i++ )  {
   if ( args[i].equalsIgnoreCase( argName ) ) { ix = i; break; }
  }
  if ( ix != -1 )  {
   // we found a valid arg -- look for the value
   
   ix++;
   if ( ix < (args.length) )
    return ( args[ix] );
   else return null;
  }
  else return null;
 }
 
 public static void main(String[] args)  {
  FileInputStream infile = null;
  FileInputStream xsltFile = null;
  FileOutputStream outfile = null;
  TransformerFactory theFactory = null;
  Transformer theTransformer = null;
  String infileName, transformFileName, outfileName;
  String paramName = null, paramValue = null;
  
  if (args.length == 0 )  {
   System.out.println("Usage: java applyXSLT -IN input -XSL transform [-OUT output] [-PARAM name value]*");
   System.exit(-1);
  }

  try {
   System.out.println("Starting Transformation");
   
   // Read the XSL stylesheet

   transformFileName = findArg( args, "-XSL" );
   if ( transformFileName == null )   {
    System.out.println("Can't find stylesheet name...exiting");
    System.exit(-1);
   }
   xsltFile = new FileInputStream(transformFileName);
   theFactory = TransformerFactory.newInstance();
   theTransformer = theFactory.newTransformer(new StreamSource(xsltFile));
   
   // Set the input and output files
   infileName = findArg( args, "-IN" );
   if ( infileName == null )  {
    System.out.println( "Can't find input filename...exiting");
    System.exit( -1 );
   }
   infile = new FileInputStream(infileName);
   
   // look for an explicit output filename, or build one from the input name
   outfileName = findArg( args, "-OUT" );
   if ( outfileName == null )
    outfileName = "output."+infileName;
   outfile = new FileOutputStream(outfileName);
   
   // Set the path for resolving relative URIs in the input document
   // to be the current directory
   StreamSource instream = new StreamSource(infile);
   instream.setSystemId(".");
   // An absolute path would look like this
   //instream.setSystemId("file:///C:/eclipse/workspace/xsltTest/");
   // The parent directory seems to require a leading current directory
   //instream.setSystemId("./../");
   
   // pass any other PARAMs into the transformer

   for ( int i = 0; i < args.length; i++ ) {
    if ( args[i].equalsIgnoreCase( "-PARAM" ) ) {
     // we found a valid param switch -- look for the name
     if ( (i+1) < args.length ) paramName = args[i+1];
     else {
      System.out.println( "Missing param name...exiting");
      System.exit(-1);
     }
     if ( (i+2) < args.length ) paramValue = args[i+2];
     else {
      System.out.println( "Missing param value...exiting");
      System.exit(-1);
     }
     // got a valid param -- set it on the transformer
     theTransformer.setParameter( paramName, paramValue );
    }
   }                                     
   // Apply the XSL stylesheet to the input to produce the output
   theTransformer.transform(instream, new StreamResult(outfile));
   
   System.out.println("Transformation completed. See " + outfileName);
  }  catch (Exception e)  {
   e.printStackTrace();
   System.exit(-1);
  }  
 }
}