[[TOC]]
= 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
<?xml version='1.0' encoding='utf-8'?>
<s3xml>
  <resource name="hms_hospital"> <!-- the main resource -->

    <field
        name="name"
        type="string"
        readable="True"
        writable="True"
        has_options="False",
        comment="", <!-- comment is only contained if there is a comment string for the field -->
        label="名前"> <!-- comments and labels are localized -->

    <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
<?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 [wiki:S3/S3XML/Transformation On-The-Fly Transformation].

=== Backend Method ===

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

{{{#!python
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 [http://www.w3.org/TR/xforms11 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.

[[Image(xmlforms.png)]]

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

----
DeveloperGuidelines