Table of Contents
The RESTful API has a built-in method to retrieve the data structure of a resource as S3XML:
Retrieving the Resource Structure
If GET/create.xml is requested without specifying a source, like:
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="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)
To include option lists inside the fields which have options, add the
Options are embedded as
<select> inside the respective
<?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>
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
(no example here because it looks pretty the same as the <select> element in the prior example)
This REST method supports On-The-Fly Transformation.
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
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:
The completed form can then be submitted to the same URL:
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.