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
    • checkbox - creates a checkbox
    • video - captures a team video URL on Youtube
    • image - for a picture
    • attachment - capture a file such as PDF
  • <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>