XML Forms

The RESTful API has a built-in method to retrieve the data structure of a resource as S3XML:

Retrieving the Resource Structure

REST Method

If GET/create.xml is requested without specifying a source, like:

GET http://localhost:8000/eden/hms/hospital/create.xml

then the interface will return the resource structure (empty, i.e. without any data) as S3XML:

<?xml version='1.0' encoding='utf-8'?>
<s3xml>
  <resource name="hms_hospital"> <!-- the main resource -->

    <field
        name="paho_uuid"
        type="string"
        readable="True"
        writable="True"
        has_options="False">

    <resource name="hms_bed_capacity"> <!-- a component, nested inside the main resource -->

      <field name="hospital_id" type="reference hms_hospital" readable="True" writable="True" has_options="True"/>
    </resource>
  </resource>
</s3xml>

(shortened here for better visibility)

Option Lists

To include option lists inside the fields which have options, add the options parameter:

GET http://localhost:8000/eden/hms/hospital/create.xml?options=true

Options are embedded as <select> inside the respective <field> element:

<?xml version='1.0' encoding='utf-8'?>
<s3xml>
  <resource name="hms_hospital">
    <field name="facility_type" type="integer" readable="True" writable="True" has_options="True">
      <select name="facility_type" id="hms_hospital_facility_type">
        <option value=""></option>
        <option value="99">Unknown type of facility</option>
        <option value="1">Hospital</option>
        <option value="2">Field Hospital</option>
        <option value="3">Specialized Hospital</option>
        <option value="21">Dispensary</option>
        <option value="98">Other</option>
        <option value="11">Health center</option>
        <option value="12">Health center with beds</option>
        <option value="13">Health center without beds</option>
      </select>
    </field>
  </resource>
</s3xml>

Reference Options

Note that this does not include option lists for reference fields - since these can be huge, you have to activate them explicitly if needed by adding the references parameter:

GET http://localhost:8000/eden/hms/hospital/create.xml?options=true&references=true

(no example here because it looks pretty the same as the <select> element in the prior example)

Transformation

This REST method supports On-The-Fly Transformation.

Backend Method

This REST function is facilitated by the S3Resource.struct() method, which can also be called from the controller:

xml = resource.struct(options=False,           # same parameter as in the URL
                      references=False,        # same parameter as in the URL
                      stylesheet=None,         # full path to the stylesheet to transform the output tree
                      as_json=False,           # convert the result into JSON
                      as_tree=False)           # return the result as ElementTree (without string-ification),
                                               #   => this overrides as_json, of course

Generating XForms

This function can be used to produce ​XForms to feed external clients.

To achieve this, one would implement stylesheets for transformation of the S3XML structure tree to XForms, and from XForms into S3XML.

Retrieving and Submitting Forms

The forms can then be retrieved using the internal transformation engine, just requesting:

GET http://localhost:8000/eden/hms/hospital/create.xforms

The completed form can then be submitted to the same URL:

POST http://localhost:8000/eden/hms/hospital/create.xforms

Specific Implementation Options

It might be necessary to have a way to configure the XForm transformation. This can be done by parameterizing the configuration options, putting them into a separate XML configuration file, and fetch this file into the stylesheets using the document() function of XPath.

It is also possible to use the output of S3Resource.struct() to produce input for the ReportLab PDF Generator to convert the XForms into printable PDF forms. These forms can later be scanned and processed by OCR and then fed back into the XML importer.

Of course it is also possible to produce other XML formats (or even text formats) using transformations, e.g. xHTML.