• Categories

  • Oh, the Things You’ll Do With XFA Source XML…

    By Fred Pantalone

    Part 1 - XFA Stitching

     

    Most LiveCycle/AEM form developers know that the source code for an XFA form template is XML. Many experienced form developers regularly inspect the XML source and modify it directly either via the XML Source tab in LiveCycle Designer or by opening the XDP in their favorite editor. Some things can be done a lot quicker this way: batch changes, text tweaks, etc. Also, sometimes debugging tasks can be helped greatly by going directly to the source. Of course, since the source is XML, we can do much more to it: transform it with XSLT, load it into a DOM and manipulate it – delete nodes, move nodes, and add nodes, etc., - anything that we normally do with XML data.

     

    In this series of articles, I’ll discuss a few of the more out of the ordinary things that I’ve done with XFA source code. In this first article I’ll discuss stitching XFA source content: adding content from one or more XFA form templates into another.

     

    Figure 1 - XFA Form Template Source: it's XML so treat it that way!

     

    Why Stitch?

     

    There are many reasons to stitch together XFA content and I’ve had two: create custom form packages and embed fragments.

     

    In the first scenario, create custom form packages, the requirement was to create a customized interactive form (a catalog of products and services) that includes content from many other forms based on options selected in another “configuration” form. The configuration form is completed by the catalog coordinator and submitted to a LiveCycle orchestration. The orchestration processes the data and executes a custom stitching component that builds the package. Essentially, the stitching component iterates through the submitted data and inserts into a “master” XFA form template the XFA content of the forms selected to be a part of the package. The result is a custom form package that only includes the forms that were needed for that specific version of the catalog. I’ve described building a catalog package but this also works well for application packages, legal document packages, etc.

     

    The main assets for this solution are: the stitching component (which is a non-trivial piece of work and will not be discussed in detail here), the “master” XFA form template, and the source form templates.

    The master XFA form template is the base document that the other form content is inserted into. Some considerations for this template are:

    ·       Basic content: this includes items that any version of the package contains such as cover page, Ts & Cs, back pages, etc;

    ·       Data binding: The data connection of the template’s  data schema is created in this template. This is typically an XML schema (XSD);

    ·       Master page(s): There are two approaches to master pages. The preferred approach is to have all master pages required by the stitched forms present in this document. This simplifies the stitching code significantly. The other approach is to stitch the master pages along with the main form content giving your stitching code twice the work to do. Regardless of the approach, master pages should all have unique names;

    ·       Others: things such as common script objects(s) and web service connections should be implemented and located in the master template;

    ·       Advanced options: I also implemented creating a dynamically generated table of contents and index for the package. Note that this can take a lot of time to design and implement.

     

    The source form templates are more or less regular form templates. Some considerations are:

    ·       Name the top-level and page-level subforms of each template uniquely;

    ·       Place any form-specific script objects under the page-level subform – not in the variables section;

    ·       Further to the previous point, ensure that the form is self-contained so that everything needed by the template is under the page-level subform – that is what will be copied from the source template into the master template.

     

    An effective way to approach a stitching project is to design the master template and a few source templates and manually stitch them together (i.e. copy and paste). 

    Once you get the resulting package working properly and you’ve figured out all of the quirks of moving form content from one template to another you can move on to writing the stitching code. The basic stitching code itself is a matter of loading the form templates into XML DOM objects and copying nodes.

     

    It’s worth mentioning that we have in the past been engaged to explore stitching AEM’s Adaptive Forms and, while we had success with a proof of concept, we found that it wasn’t quite practical just yet to proceed with a project. However, stitching adaptive forms remains an exciting and promising concept.

     

    Embedding Fragments

     

    The second scenario for stitching content is to embed fragments which means replacing fragment references with the actual content of the fragments. The purpose for doing this is to create a snapshot of a form template and all of its fragments – you might have an administrative or legal requirement to do this.

     

    Embedding fragments is easier to implement than the multi-document stitching described above. Simply read the fragment reference(s), which contains the file and the location within the source code of the fragment, open the fragment document, and replace the fragment reference subform with the actual fragment subform. Figure 2, below, shows the source code of a fragment reference. Notice the two pieces of information stored in the usehref attribute: the location and name of the fragment file, and the SOM expression to the fragment element itself. 

     

    Figure 2 - The fragment reference contains all you need to know.

     

    Your main document may contain several fragment references to be embedded and you can use this XPath expression to return a nodelist of all the references in a template:

     

    //*[local-name()='subform'][@*[local-name()='usehref']]

     

    I hope you found this discussion on stitching interesting. I also hope that you can one day find it useful! This isn’t something you’ll do every day but it might get you thinking about the different things you can do with XFA source code. In the next article I’ll discuss transforming XML data into an XFA form!

     

    Need a hand?
    Contact Us