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:

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:

</part>