XForms Converter
From Adobe Labs
Note: This technology shipped on July 19, 2007 as part of the Adobe LiveCycle Designer ES and is no longer hosted on Adobe Labs.
| Table of contents |
XForms Conversion Overview
The XForms Converter utility was developed to provide the ability to perform the conversion of XForms documents into Adobe’s XML Forms Architecture (XFA) documents. The resulting files are XDP documents that can be used in Adobe® LiveCycle® Designer application. The utility can be invoked via the console or a Java Swing client. Further details on how it can be invoked are provided in the Operation section of this document. This is an alpha version of the utility.
About XForms
XForms is an XML format that specifies a data processing model for XML data and user interface components for the capture of XML data. XForms was designed to be the next generation of HTML / XHTML forms and is a W3C Recommendation. XForms requires a host language for its presentation. This is usually HTML or XHTML but can be another language such as SVG, XML or XFDL. XFDL is IBM's proprietary form description language used in IBM Workplace Forms.
About the Adobe XML Forms Architecture
Adobe XML Forms Architecture (XFA) is a published specification which provides the grammar and a set of processing rules for creating interactive forms and documents. In addition to data processing and user interface controls, XFA describes presentation and layout. XFA documents have an .XDP extension and can be used with the some of Adobe's LiveCycle family of products. Adobe LiveCycle Designer's native format is XDP.
Download and Install
This technology shipped on July 19, 2007 as part of the Adobe LiveCycle Designer ES and is no longer hosted on Adobe Labs.
Operation
Console Invocation
The conversion tool can be run from the command line or by using the runconversion.bat file. To use the .bat file, edit the file to change the parameters after the class path instructions. The batch file approach may be useful if you have a large number of files to convert. Copy and paste the example in the batch file and edit for each form you need to convert.
Here are the parameters that you can set.
| Parameter | Values | Example |
|---|---|---|
| in | Input XForms file name (required) | demo.xhtml |
| out | File Path to use for the Output XDP (required) | myOutput.xdp |
| error | Name of error log (required) | error.log |
| summary | Name of summary log (required) | summary.log |
| log | 0 for Do Not Log or 1 for Windows Temp log | 1 |
| embedschema | On to embed schema in XDP or Off to not embed | On |
NOTE: The error log contains error messages if any. The summary log contains information messages. Both of these log file names are required parameters. If the log option is set to one, an additional and more detailed log is written to c:\temp and has a prefix of ConvertCF with a series of numbers to uniquely identify it (e.g ConvertCF12345.text)
Here's an example of how it will look in your .bat file or on the command line in the console:
java -classpath .;lib\log4j.jar;lib\xmlParserAPIs.jar;lib\dom4j.jar;lib\xsom.jar;lib\relaxngDatatype.jar;lib\adobe-xfa-2.6.0.jar;lib\xforms_xfa_code.jar com.adobe.convertxf.xforms.XFormsProcessor in="Demo.xhtml" out="myOutput.xdp" error="errors.log" summary="summary.log" log=1 embedschema=off
Note: You will need to add [basedir]\jre\bin to your system PATH variable where [basedir] is the path to the folder that you extracted the zip file to.
Swing Client User Interface
Java Swing Client Invocation A simple Java Swing application is also available to run the XForms conversion. To operate, simply execute the ConvertXFUI.exe program by double-clicking it. The following screen shot shows the window that pops up when the Swing client is run.
Type in the path and name or browse to the input and output file. Once the input XForms file and output XDP file are selected, the Convert button is pressed and an Options dialog will appear to accept the options for the conversion.
The options that can be set are the following:
- Embed Schema - if a schema is set for the XForms document, this checkbox can be selected to indicate that it should be embedded within the output XDP file.
- Working Directory - this directory indicates where the application should look for relative file path locations that might be included in the XForms document (ie: instance data xml files or XML Schema files). If the working directory is left blank, the converter will look in the directory where the XForms input file was found, otherwise the XForms document must include absolute file paths.
- Log Option – Specifies where conversion output messages should be logged. The options are
- Do Not Log : no log is written to.
- \TEMP\ConvertXF.log: writes to a temp file under the Windows Documents and Settings\<user>\Local Settings\Temp
- <working_dir>ConvertXF.log: writes to a file named ConvertXF.log under the directory specified as the working directory.
Click the Ok button to start the conversion.
Viewing the Results
The output from either the console or Swing client is an *.XDP. The *.XDP file can be opened in LiveCycle Designer 8.0. If you don't have LiveCycle Designer 8.0, you can download a trial version as part of the Acrobat 8 Professional trial.
The converter only converts the XForms markup in the source file. Any presentation definition in the host language (e.g. HTML) is not converted so the form may not look like it does when viewed in the browser or a form client like IBM Workplace forms.
Conversion Details
The XForms components will be mapped to Designer components in the following general manner and layed out left to right, top to bottom.
| XForms Component | XFA Component |
|---|---|
| input | textedit, numericEdit or dateTimeEdit |
| textarea | Textedit (multiline) |
| select1 | choicelist (multiple selection) |
| select | Dropdown or listbox depending on appearance |
| secret | password |
| submit | httpSubmitButton |
| trigger | button |
| repeat | Subform with bind ref and occurs settings |
| group | Subform with bind ref |
| repeat | Subform with bind ref and occurs settings |
| switch/case | Subforms with binds and occurs tags, and custom script for managing instances |
| output | Textedit without caption so we can point to a ref |
Note: there is no equivalent to the upload and range components in XFA, thus they will not be translated.
The calculate attributes from the XForms binds are translated and added into a <calculate> tag on the field as needed. The data type constraints are also processed and <validate> or <picture> tags are put in as needed. The bind required, relevant and readonly attributes are also interpreted and the related XFA attributes are added. Events and their XForms actions to take that occur within a component are processed with custom script and mapped to XFA as best as possible. See Limitations section for further details.
Limitations
The following limitations are noted for this version of the utility:
XForms Model
Only one form bound can be bound to one data model so only one model can be specified per XForms document (including one namespace max).
- XForms Instance
- One instance (src reference or inline)
- XForms Schema
- One schema reference to correlate with the instance data – see next section for schema limitations.
Data Schema
Limited schema support will be available in this version. Specifically only simple types including the binding and validation of those types are supported.
XPath
The set of XPath functions that correspond to FormCalc functions will be supported (Sum, Min, Max etc, as well as true() and false()). The others will be logged at this time. It is advised to use absolute paths particularly within calculations or nodeset references and to limit the use of XPath shortcuts (‘.’ and ‘..’ etc) for best conversion results.
XForms Actions/Event Processing
Actions that are defined within the components are currently the only actions that are supported. A script is used to represent logic similar to the XForms action where possible.
The XForms setindex action is used with a repeat to visually outline a certain item in the repeat list. It will not be converted. The insert/delete actions used with repeats are supported. An insert is converted to insert to the end of the repeat via the instanceManager, and a delete will use instanceManager to remove the last instance or repeat item.
Tips
Certain modifications can be made to achieve better results in the import process.
- Change file paths to be absolute references. If file paths are relative, a working directory must be set in the Options dialog, and the files must be located within that working directory.
- The conversion does not handle the case of a multiple select pointing to one data node, the form can be modified to have each item point to a separate data node.
