Changes between Initial Version and Version 1 of S3/XMLForms


Ignore:
Timestamp:
03/15/11 22:02:52 (14 years ago)
Author:
Dominic König
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • S3/XMLForms

    v1 v1  
     1= XML Forms =
     2
     3The RESTful API has a built-in method to retrieve the data structure of a resource as S3XML:
     4
     5== Retrieving the Resource Structure ==
     6
     7=== REST Method ===
     8
     9If '''GET/create.xml''' is requested '''without specifying a source''', like:
     10
     11{{{
     12GET http://localhost:8000/eden/hms/hospital/create.xml
     13}}}
     14
     15then the interface will return the resource structure (empty, i.e. without any data) as S3XML:
     16
     17{{{
     18<?xml version='1.0' encoding='utf-8'?>
     19<s3xml>
     20  <resource name="hms_hospital"> <!-- the main resource -->
     21
     22    <field
     23        name="paho_uuid"
     24        type="string"
     25        readable="True"
     26        writable="True"
     27        has_options="False">
     28
     29    <resource name="hms_bed_capacity"> <!-- a component, nested inside the main resource -->
     30
     31      <field name="hospital_id" type="reference hms_hospital" readable="True" writable="True" has_options="True"/>
     32    </resource>
     33  </resource>
     34</s3xml>
     35}}}
     36
     37(shortened here for better visibility)
     38
     39=== Option Lists ===
     40
     41To include option lists inside the fields which have options, add the {{{options}}} parameter:
     42
     43{{{
     44GET http://localhost:8000/eden/hms/hospital/create.xml?options=true
     45}}}
     46
     47Options are embedded as {{{<select>}}} inside the respective {{{<field>}}} element:
     48
     49{{{
     50<?xml version='1.0' encoding='utf-8'?>
     51<s3xml>
     52  <resource name="hms_hospital">
     53    <field name="facility_type" type="integer" readable="True" writable="True" has_options="True">
     54      <select name="facility_type" id="hms_hospital_facility_type">
     55        <option value=""></option>
     56        <option value="99">Unknown type of facility</option>
     57        <option value="1">Hospital</option>
     58        <option value="2">Field Hospital</option>
     59        <option value="3">Specialized Hospital</option>
     60        <option value="21">Dispensary</option>
     61        <option value="98">Other</option>
     62        <option value="11">Health center</option>
     63        <option value="12">Health center with beds</option>
     64        <option value="13">Health center without beds</option>
     65      </select>
     66    </field>
     67  </resource>
     68</s3xml>
     69}}}
     70
     71=== Reference Options ===
     72
     73Note 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:
     74
     75{{{
     76GET http://localhost:8000/eden/hms/hospital/create.xml?options=true&references=true
     77}}}
     78
     79(no example here because it looks pretty the same as the <select> element in the prior example)
     80
     81=== Transformation ===
     82
     83This REST method supports [wiki:S3XRC/S3XML/Transformation On-The-Fly Transformation].
     84
     85=== Backend Method ===
     86
     87This REST function is facilitated by the {{{S3Resource.struct()}}} method, which can also be called from the controller:
     88
     89{{{
     90xml = resource.struct(options=False,           # same parameter as in the URL
     91                      references=False,        # same parameter as in the URL
     92                      stylesheet=None,         # full path to the stylesheet to transform the output tree
     93                      as_json=False,           # convert the result into JSON
     94                      as_tree=False)           # return the result as ElementTree (without string-ification),
     95                                               #   => this overrides as_json, of course
     96}}}
     97
     98== Generating XForms ==
     99
     100This function can be used to produce [http://www.w3.org/TR/xforms11 XForms] to feed external clients.
     101
     102To achieve this, one would implement stylesheets for transformation of the S3XML structure tree to XForms, and from XForms into S3XML.
     103
     104=== Retrieving and Submitting Forms ===
     105
     106The forms can then be retrieved using the internal transformation engine, just requesting:
     107
     108{{{
     109GET http://localhost:8000/eden/hms/hospital/create.xforms
     110}}}
     111
     112The completed form can then be submitted to the same URL:
     113
     114{{{
     115POST http://localhost:8000/eden/hms/hospital/create.xforms
     116}}}
     117
     118=== Specific Implementation Options ===
     119
     120It 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.
     121
     122It 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.
     123
     124[[Image(xmlforms.png)]]