XHTML Form Extractor

The adapter extracts form fields from XML-compatible (X)HTML documents to make the mapping of process data to form fields easier to understand.

The adapter expects an (X)HTML document as input (in any case a well-formed XML document!) and outputs an XML document with the structure of the extracted (X)HTML form. In addition, the adapter can use the FillInFields operation to fill the adapter-specific XML structure, which contains set form fields and, if applicable, modified properties for option fields, into an (X)HTML form template and output the finished (X)HTML form document.

This adapter is targeted at developers of Human Workflow processes who want to fill existing (X)HTML form templates with data at runtime. For this purpose, the input data structure (e.g. the results of a database query) is linked to the fields of the (X)HTML form in an XSL mapping via the Mapping Editor.

To make (X)HTML document structures clearer for mapping, the XHTML Form Extractor Adapter extracts all form elements so that only this simplified form structure and the data need to be linked in the Mapping Editor. For conversion to the XML form structure, the context menu function Extract XHTML Form for (X)HTML repository documents, is available in the X4 Designer.

To convert the XML form structure back into a complete (X)HTML form after mapping, place the XHTML Form Extractor Adapter as the next process step, select the FillInFields operation and specify the URL to the (X)HTML form template in the adapter parameter templateUrl. When the process is executed, the modified form elements are merged with the (X)HTML form template and output at runtime, e.g. for display in web applications. Via attributes in the XML form structure, option fields can be (de)selected and (de)activated, and CSS direct formatting and CSS class assignments can be defined.

Properties

Operation

Determines which operation the adapter executes

Possible values:

ExtractFields: Extract form fields from an input (X)HTML document (well-formed XML!).
FillInFields: Insert form fields from the adapter-specific XML structure into an XML-compliant (X)HTML document defined in parameter templateUrl; additional fields from the (X)HTML template document are taken over unchanged.

Parameter

Adapter

Main class of the adapter (do not change!)

Possible values: en.softproject.integration.adapter. htmlformextractor.FormAdapter: Main class (default)

templateUrl

URL to the template document of the (X)HTML form (required for operation FillInFields).

Possible values: Any valid URL (e.g. xstore://Project/Folder/Form.xhtml)

Status values

`1`	The operation was executed successfully.
`-1`	The operation failed due to a technical error.

Example

In this example, an HTML5 form (well-formed XML) serves as input:

HTML/XML

<!DOCTYPE HTML>
<html>
  <head>
    <title>My Form</title>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <style type="text/css">
      body { background-color:#F0F0F0; font-family:sans-serif }
    </style>
  </head>
  <body>
    <h1>Form</h1>
    <form action="ACTION" method="post" id="myID">
      <p>
      <input type="text" name="myName" value=""/>
        <select name="myDropdown" size="1">
          <option>1</option>
          <option>2</option>
          <option>3</option>
        </select>
      <input type="radio" name="myOptions" value="either" /> Either
        <input type="radio" name="myOptions" value="or" /> Or
      <input type="submit" value="submit" name="mySend"/>
     </p>
    </form>   
  </body>
</html>

In Operation ExtractFields, the adapter converts the HTML5 form into the following XML structure:

HTML/XML

<HtmlFields>
  <title>My Form</title>
  <form_myID id="myID">
   <text_myName name="myName" type="text"/>
   <submit_mySend name="mySend" type="submit">submit</submit_mySend>
   <singleselect_myDropdown name="myDropdown">
     <option disabled="false" selected="false">1</option>
     <option disabled="false" selected="false">2</option>
     <option disabled="false" selected="false">3</option>
   </singleselect_myDropdown>
  </form_myID>
</HtmlFields>

The following XML structure has now been created via an XSL mapping, in which field values and the page title have been changed. Various properties for option fields have been set and an additional option field has been added.

HTML/XML

<HtmlFields>
  <title>X4 Experience</title>
  <form_myID id="myID">
   <text_myName type="text" name="myName">X4 Experience</text_myName>
   <submit_mySend type="submit" name="mySend">submit</submit_mySend>
   <singleselect_myDropdown name="myDropdown">
     <option>Version 4.0</option>
     <option selected="false" disabled="true">Version 4.1</option>
     <option selected="false" disabled="false" cssStyle="color:blue">Version 4.2
     </option>
     <option selected="true" disabled="false">Version 4.3</option>
   </singleselect_myDropdown>
  </form_myID>
</HtmlFields>

With Operation FillInFields, the adapter converts the above modified XML structure back into a complete, XML-compliant HTML5 form:

HTML/XML

<!DOCTYPE HTML>
<html>
  <head>
   <title>X4 Experience</title>
   <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
   <style type="text/css">
     body { background-color:#F0F0F0; font-family:sans-serif }
   </style>
  </head>
  <body>
   <h1>Form</h1>
   <form action="ACTION" method="post" id="myID">
     <p>
      <input type="text" name="myName" value="X4 Experience" 
       style="color:blue"/>
      <select name="myDropdown" size="1">
        <option>Version 4.0</option>
        <option disabled="disabled">Version 4.1</option>
        <option style="color:blue">Version 4.2</option>
        <option selected="selected">Version 4.3</option>
      </select>
      <input type="radio" name="myOptions" value="either"/> Either
      <input type="radio" name="myOptions" value="or"/> Or
      <input type="submit" value="submit" name="mySend"/>
    </p>
   </form>   
  </body>
</html>

Operation: ExtractFields

With Operation ExtractFields, form fields can be extracted from an input (X)HTML document (well-formed XML!).

Input

For Operation ExtractFields, the adapter expects an (X)HTML document that has a well-formed XML structure (correct nesting, self-closing empty elements such as <br/> etc.) and whose form elements are unique via attribute id or name.

Output

With Operation ExtractFields, the adapter outputs an XML document with form data that you can use in the mapping as a template for the target structure.

Operation: FillInFields

Operation FillInFields can be used to insert form fields from the adapter-specific XML structure into an XML-compliant (X)HTML document defined in parameter templateUrl; additional fields from the (X)HTML template document are taken over unchanged.

Input

With operation FillInFields, the adapter expects an XML document that has a structure according to the following pattern and creates an XML element for all form fields (except checkboxes and radio buttons) that contains the field type and field name in the name.

In the XML structure, <option/> fields can be provided with CSS direct formatting (cssStyle="..."), CSS class assignments (cssClass="...") and labels (label="...") via specific attributes, and can be (de)selected (selected="true/false"), (de)activated (disabled="true/false") and set to read-only (readonly="true/false"). Values of <input/> and <option/> can be set via an attribute value="...".

HTML/XML

<HtmlFields>
 <title><!--Seitentitel des (X)HTML-Dokuments--></title>
 <!-- Beliebig viele Formulare (eindeutig über ID identifiziert) -->
 <form_id id="Formular-ID">
  <!-- Beliebig viele Formularfelder (identifiziert über ID oder Name) -->
  <Feldtyp_Feldname/-ID name="Feldname" type="Feldtyp"><!--Feldwert--></Feldtyp_Feldname/-ID>
 </form_id>
</HtmlFields>

Output

In the FillInFields operation, the adapter outputs an XML-compatible (X)HTML document that contains the field values (and, in the case of radio buttons, possibly modified properties) that were defined in the input document and whose structure corresponds to the template defined in the templateUrl parameter. Checkboxes and radio buttons from the template are transferred unchanged to the result document.