XML constructs
The XML files are built from a limited number of constructs:
- <livedoc>: is the top level construct
Each root file starts with a <livedoc> construct. - <part>: a section of a <livedoc> (details here)
A <part> typically introduces a sub-section of of a <livedoc>. Parts can have text describing the section. Parts can also be nested if you need sub-sections of a section. For example, Team Choice Elements are a part, but are further sub-divided into TCE1 and TCE2. - <element>:an item to collect some online form input (details here)
A common element type is a para. When displaying an Online Form, a para would be used to capture something like a story description. There are a variety of element types such as: - para - paragraph
- phrase - a shorter text description
- choice - creates a dropdown
- multichoice - creates a set of checkboxes to make more than once choice
- checkbox - creates a checkbox
- video - captures a team video URL on Youtube
- image - for a picture
- attachment - capture a file such as PDF
- there are a set of more specialized element types discussed in the more detailed description of element type
- <include>: place constructs (often a <part>) in another file that is added at the point of the include
This support sharing of sections among the documents and ensures the section in each document is the same.
A good way to get a feel for the XML language is to look at an example and what it produces. The general structure is:
- a form has a <livedoc>
- a <livedoc> consists of a series of <part>s
- a <part> consist of a
- a series of nested <part>s
- a series of nested <element>s
Livedocs also support substitution of certain values into a document. These substitutions appear in the text of the XML files in curly braces (eg {firstname}). The values are described in the database table di_live_doc_arg that indicates where the Resource Area can find the value to substitute. The table contains the following columns:
- id: unique id
- program_year: if non-zero, it applies to a specific year; zero applies to all years
- doc_type: applies only to tdfs, exps, or prep
- arg_type: provides details on how the RA finds the value to substitute
- user: arg_name is a field in the user record
- team: arg_name is a value associated with the team
- function: arg_name is a function to run in livedocs to get the value
- team-link: arg is a link to another team-specific page - substitute the team_id to create the link
- link: arg is a link to another page (often external to the RA)
- help: arg is a topic in the help website
- arg_name: the value that appears between the braces (how the RA finds the value)
- arg: is an arg_type dependent value needed to get the value
Currently these substitutions are limited to the descriptive text associated with a <part>. To activate substitutions in this text,in a part description, the substitute attribute is set to 1 or give the part a type of substitute. For example:
<part name="ip_kids" desc_clid="ip_kids-desc" type="substitute" title="Team Members" output="heading">
You have entered the following team members into the <b>Resource Area.</b> If this list is inaccurate, click
{teamedit-link} to edit your team members. Check the box beside each team member's name that
participated in the creation of your team's solution:
<element type="dcl_kid_checkbox" clid="dcl-checkbox" name="dcl-kid-checkbox" submit="checked"></element>
</part>