Loughborough Online Reading List System
FastGetStructuralUnit
NAME
FastGetStructuralUnit - LUMP CGI XML API to return the contents of a
Structural Unit (and its children).
DESCRIPTION
The GetStructuralUnit CGI script is designed to allow Structural Units
held in a LUMP database to be returned in an XML container format. The
script can return a tree of Structural Units to an arbitrary depth
rooted at a particular Structural Unit specified by its ID.
PARAMETERS
Standard
*username* - Name of user running this CGI script. Required unless web
server authentication is in use (when it is, the web server
authenticated user is used instead).
*password* - Password for the user. This is only required if the web
server is not handling the user authentication and if no security hash
parameter is being given.
*security_hash* - An opaque value used to authenticate the user without
requiring the password to be sent. This value is generated by a previous
execution of a LUMP API script and may well be time limited. It is only
required if no password or webserver authentication is done.
*act_as* - Users in the SysAdmins group can elect to act on the behalf
of other users once they are themselves authenticated. If this parameter
is present it should contain the username of the user that should be
switched to if this option is available and the real user has been
authenticated successfully. Optional.
*session_id* - An opaque string as far as the server is concerned that
is intended solely to allow async clients to differentiate different
results more easily. Optional.
Specific for this script
*suid* - ID of the root Structural Unit for the tree that should be
returned. This can be a comma separate list of IDs if more than one
Structural Unit is to be found.
RESULTS
The script returns an XML document in the standard LUMP response format
(as documented in LUMP-XML-Response). The <returns> section's contents
depends on the display format requested with the *format* parameter in
the request. If this is specified (and isn't "XML") the <returns>
element will contain a <rendered> element that contains the Structural
Unit(s) rendered using the appropriated display format module(s). This
means that in this case the value of the <rendered> element can often be
transmitted straight into an output stream, DOM element, etc.
The <returns> element also contains the XML structure following this DTD
fragment:
<!ELEMENT returns (su|rendered)>
<!ELEMENT rendered (#PCDATA)>
<!ELEMENT su (children|id|structural_unit_type_id|state|deleted|data+)>
<!ELEMENT children (su+)>
<!ELEMENT structural_unit_type_id (#PCDATA)>
<!ELEMENT id (#PCDATA)>
<!ELEMENT state (#PCDATA)>
<!ELEMENT deleted (#PCDATA)>
<!ELEMENT data (data_type|data_element)
<!ELEMENT data_element (id|value|modified_time)>
<!ELEMENT data_type (id|name|edit_representation|default_value|
validation_pattern|repeatable|size)>
<!ELEMENT value (#PCDATA)>
<!ELEMENT edit_representation (#PCDATA)>
<!ELEMENT validation_pattern (#PCDATA)>
<!ELEMENT repeatable (#PCDATA)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT size (#PCDATA)>
For example:
<response>
<returns>
<su>
<children>
<su>
<id>350</id>
<state>published</state>
<deleted>N</deleted>
</su>
</children>
<data>
<data_type>
<validation_pattern></validation_pattern>
<edit_representation>input text</edit_representation>
<name>Year</name>
<id>23</id>
<repeatable>N</repeatable>
<size>4</size>
</data_type>
<data_element>
<value>2006</value>
<id>1332</id>
</data_element>
</data>
<data>
<data_type>
<validation_pattern></validation_pattern>
<edit_representation>input text</edit_representation>
<name>Semester</name>
<id>24</id>
<repeatable>N</repeatable>
<size>100</size>
</data_type>
<data_element>
<value></value>
<id>1333</id>
</data_element>
</data>
<data>
<data_type>
<validation_pattern></validation_pattern>
<edit_representation>input text</edit_representation>
<name>Module Name</name>
<id>25</id>
<repeatable>N</repeatable>
<size>100</size>
</data_type>
<data_element>
<value>Advanced Human-Computer Integration</value>
<id>1334</id>
</data_element>
</data>
<data>
<data_type>
<validation_pattern></validation_pattern>
<edit_representation>input text</edit_representation>
<name>Student Numbers</name>
<id>27</id>
<repeatable>N</repeatable>
<size>10</size>
</data_type>
<data_element>
<value>0</value>
<id>1335</id>
</data_element>
</data>
<data>
<data_type>
<validation_pattern>dd[A-Z][A-Z][ABCPX]ddd</validation_pattern>
<edit_representation>input text</edit_representation>
<name>Module Code</name>
<id>28</id>
<repeatable>N</repeatable>
<size>10</size>
</data_type>
<data_element>
<value>06COC171</value>
<id>1336</id>
</data_element>
</data>
<data>
<data_type>
<validation_pattern></validation_pattern>
<edit_representation>input text</edit_representation>
<name>Module Tutor</name>
<id>26</id>
<repeatable>Y</repeatable>
<size>100</size>
</data_type>
<data_element>
<value>Professor R S Kalawsky</value>
<id>1339</id>
</data_element>
</data>
<id>350</id>
</su>
</returns>
<session>
<security_hash>1248086710:a615619fd3d278c8a15154afade9ccec</security_hash>
<lump_version>1</lump_version>
<acting_as></acting_as>
</session>
<error>
<error_message>Success</error_message>
<error_code>SUCCESS</error_code>
</error>
</response>
The <error> section contains SUCCESS in the <error_code> if the
operation finishes successfully, or a failure error code if it doesn't.
The <error_message> element contains a human readable message that can
be used to inform the user of problems if desired.
SEE ALSO
FindSuid
LUMP-XML-Response
COPYRIGHT
Copyright 2009 Loughborough University Library <library@lboro.ac.uk>.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.