Docs:Metadata

Course material in the wiki needs to conform to a Course Structure specification, but that structure does not contain enough information on its own to successfully generate a CBT package using the export and processor tools. In order to generate a CBT package, the tools need information about how themes and modules are related to each other, and information about the layout and contents of the course. This information is held inside the metadata that must be provided for the course and for the themes.

At the top level of the course data, a metadata section is used to specify the course front page image (or animation) and the text to show before the 'start course' button, along with other information about the course. Each theme must have an associated metadata section that describes the theme's modules and the links between them in a format the course processor can understand.

The contents of the metadata should conform to XML standards with the added restriction that all element and attribute names must be specified in lowercase or the processor will not parse them correctly.

All the elements that have name and title attributes interpret them in the same way: name contains the physical directory name used for the resource, while title is the human-readable descriptive title associated with the resource. name attributes may only contain alphanumeric characters and underscores, and you are very strongly advised to only use lowercase characters in names. title attributes may contain any characters other than literal quote marks (if you need to use a quote in a title, encode it as a HTML entity, ie: "). The order in which you specify attributes within elements is irrelevant.

Course-level metadata

As stated in the Course Structure specification, the CourseData page must include a level two title == Metadata == followed by the course metadata inside a source element. This is an example of a CourseData page including the metadata block:

[[FOO:Course|View course page]]

== Themes ==
[[FOO:Fnord]]<br/>
[[FOO:Python Sketches]]<br/>
[[FOO:Vaults of Zin]]<br/>

== Resources ==
[[FOO:Media]]<br/>

== Metadata ==
<source lang="xml" style="emacs">
<course version="1.0">
    <courseinfo title="Not a real course" splash="front_page.png" type="image" width="300" height="300"><![CDATA[
        <p class="center">This is not a real course</p>
        <p class="center">If you encounter any problems, please <a style="font-weight: bold;"
        href="feedback.html">contact us</a> at the earliest opportunity.</p>
    ]]></courseinfo>
</course>
</source>

The course element

The root of the course metadata is the course element. This element's attributes contain versioning information about the course. The element is used as a container for a number of other course-level metadata elements described below.

Attributes

version The course version number. This must be specified, but the format of the contents of the attribute is not prescribed or enforced.

Example

This is an example of a minimal course element based around the copy used in the C course:

<course version="1.0 (2009-09-28 09:52)">
    <courseinfo title="C Programming" splash="C_course_front_page.png" type="image" width="300" height="300"><![CDATA[
        <p class="center">Welcome to the PEVE C Programming Course. To begin using the course,
        click the button below. If you have already started working through the course you should
        also see a button to allow you to continue from the last page you viewed.</p>
        <p class="center">If you encounter any problems, please <a style="font-weight: bold;"
        href="feedback.html">contact us</a> at the earliest opportunity.</p>
    ]]></courseinfo>
</course>

This is an example of a complete course element, including a number of required and optional elements inside the course element.

<course version="1.0 (2009-09-28 09:52)">
    <courseinfo title="C Programming" splash="C_course_front_page.png" type="image" width="300" height="300"><![CDATA[
        <p class="center">Welcome to the PEVE C Programming Course. To begin using the course,
        click the button below. If you have already started working through the course you should
        also see a button to allow you to continue from the last page you viewed.</p>
        <p class="center">If you encounter any problems, please <a style="font-weight: bold;"
        href="feedback.html">contact us</a> at the earliest opportunity.</p>
    ]]></courseinfo>
    <latexintro>
        \documentclass[12pt]{article}
        \usepackage{html}
        \usepackage[dvips]{color}
        \pagecolor{white}
    </latexintro>
    <extrahead><![CDATA[
        <link rel="stylesheet" type="text/css" href="{COURSE_BASE}media/main-rollup.css" />
    ]]></extrahead>
    <forcemedia>
        <file>Animusic_03_splash.png</file>
    </forcemedia>
    <maps>
        <map><![CDATA[
            ... image map and image ...
        ]]></map>
    </maps>
</course>

The courseinfo element

This element is a required child of the course element. At least one courseinfo must be specified, and it may be specified multiple times if needed by filtering requirements. The element's attributes contain information about the course title and splash page, and it should contain the message to show on the front page of the generated course. The content of the courseinfo element may contain any html, but you are advised to keep to basic tags if at all possible. If your message contains any HTML, you must wrap the contents of the courseinfo with <![CDATA[ ... ]]> to ensure the contents are interpreted correctly.

Note regarding courseinfo and filtering: When the processor is attempting to determine which courseinfo element to use when generating the course title and splash page, it will use the first specified courseinfo element that passes filtering. This means that, if you have a courseinfo element with no filtering rules set, and it appears before any courseinfo elements with filtering rules, it will always be used, even if one of the filtered courseinfo elements would have passed the filtering rules. Basically, you should either:

1. specify filtering rules for all courseinfo elements if any of the courseinfo elements in your course metadata have filtering rules set, or
2. always place a courseinfo element without filtering rules after courseinfo elements with filtering rules in your course metadata (effectively providing a fallback for situations where none of the filtered courseinfo elements pass filtering).

Attributes

title The human-readable course title.

splash The name of the splash image/animation to show on the front page. Must be an image or animation present in the course's media directory.

type either 'image' if splash names an image to use in the page, or 'anim' if splash names a flash animation. applets are not supported in this page.

width The width of the splash image/animation in pixels.

height The height of the splash image/animation in pixels.

include optional, allows you to specify a comma separated list of filters under which this map will be included. See the Docs:Filtering page for more information

exclude optional, allows you to specify a comma separated list of filters under which this map will be excluded. See the Docs:Filtering page for more information

Example

This is an example message element taken from the C course. Note the use of <![CDATA[ ... ]]> here.

    <courseinfo title="C Programming" splash="C_course_front_page.png" type="image" width="300" height="300"><![CDATA[
        <p class="center">Welcome to the PEVE C Programming Course. To begin using the course,
        click the button below. If you have already started working through the course you should
        also see a button to allow you to continue from the last page you viewed.</p>
        <p class="center">If you encounter any problems, please <a style="font-weight: bold;"
        href="feedback.html">contact us</a> at the earliest opportunity.</p>
    ]]></courseinfo>

The latexintro element

This element is an optional child of the course element, and contains latex commands to prepend to the contents of [latex] directives. It may contain any valid LaTeX header commands, and may import LaTeX modules if you require them.

Attributes

None. This element is a container only.

Example

The following example is the default latex preamble prepended to any [latex] blocks.

<latexintro>
    \documentclass[12pt]{article}
    \usepackage{html}
    \usepackage[dvips]{color}
    \pagecolor{white}
</latexintro>

The extrahead element

This element is an optional child of the course element, and contains xhtml elements to place in the head element of each generated file in the CBT package. This should be used to load custom stylesheets, javascript, or to insert additional <link> items. Any occurrences of {COURSE_BASE} in the element's contents will be replaced by a relative path back to the course directory in the generated CBT package (including a trailing slash!) This means that you can place any files you require in the course media, and then use {COURSE_BASE}media/your_file_name to have the system generate the correct path to the file for you, at all levels in the package. You must wrap the contents of the extrahead with <![CDATA[ ... ]]> to ensure the contents are interpreted correctly.

Attributes

This element is a container only. It should be used as:

Example

This example will result in a stylesheet being loaded from the media directory on all pages in the CBT package.

<extrahead><![CDATA[
    <link rel="stylesheet" type="text/css" href="{COURSE_BASE}media/main-rollup.css" />
]]></extrahead>

The forcemedia element

This element is an optional child of the course element, and contains a list of files that should be retained in the media directory even if the course does not appear to explicitly reference the files. This is needed to ensure that resources loaded by animations or other embedded content are available in the generated course.

Attributes

This element is a container only. It should be used as:

Example

This example forces the 'Animusic_03_splash.png' file to be retained in the CBT package, even if it does not appear to be used anywhere.

<forcemedia>
    <file>Animusic_03_splash.png</file>
</forcemedia>

The file element

This element is a child of the optional forcemedia element, and contains the name of a file that should be retained in the media directory even if the course does not appear to explicitly reference the file.

Attributes

This element is a container only. It should be used as:

Example

Please see the forcemedia element for an expanded example.

<file>Animusic_03_splash.png</file>

The maps element

This element is an optional child of the course element. If specified, you must include one or more map elements in the maps element body.

Attributes

This element is a container only.

Example

Please see the course map element description for usage examples.

The map element

This element is an required child of the maps element. If specified, and the element passes filtering checks, the contents of the element will be used in the body of the course-wide map (the page from which the user may select the theme to browse, usually via a graphical system such as buttons). If you do not specify a map element, or none of the map elements remain after filtering, the processor will generate an appropriate map for you based on the indexorder of the themes. You must wrap the contents of the map with <![CDATA[ ... ]]> to ensure the contents are interpreted correctly.

Attributes

include optional, allows you to specify a comma separated list of filters under which this map will be included. See the Docs:Filtering page for more information

exclude optional, allows you to specify a comma separated list of filters under which this map will be excluded. See the Docs:Filtering page for more information

Example

This example shows map element whose contents will only be used on the course map page when the filter keyword 'apecs' has been passed to the processor (otherwise, an automatically generated map will be used)

<maps>
    <map include="apecs"><![CDATA[
        ... image map and image ...
    ]]></map>
</maps>

Theme-level metadata

As stated in the Course Structure specification, theme pages must include a level two title == Metadata == followed by the theme metadata inside a source element. This is an example of a theme page including the metadata block:

[[FOO:CourseData|View coursedata page]]

== Modules ==
[[FOO:Gugs]]<br/>
[[FOO:Ghasts]]<br/>
[[FOO:Access from Sarkomand]]<br/>

== Metadata ==
<source lang="xml" style="emacs">
<theme name="zin" title="Vaults of Zin" indexorder="3">
    <module name="gugs" title="Gugs" level="green" indexorder="1">
        <leadsto>
            <target>access</target>
        </leadsto>
    </module>
    <module name="ghasts" title="Ghasts" level="green" indexorder="2">
        <leadsto>
            <target>access</target>
        </leadsto>
    </module>
    <module name="access" title="Access from Sarkomand" level="yellow" indexorder="3" />
</theme>
</source>

The theme element

The root of the theme metadata is the theme element. This element defines the theme name and title and acts as a container for module, include, and filter elements. Each theme metadata file must contain exactly one theme element.

Attributes

name the name of the theme directory on the filesystem. This should not contain spaces or special characters other than the '_' underscore character. You are strongly advised to only use lower-case characters in the name to avoid case sensitivity issues.

title the human-readable theme title. This may contain any text (quotes should be replaced by &quot;).

indexorder location in the course-wide index, should be numeric and each theme should have a unique value. In general, the first theme should have the indexorder set to 1, the second to 2, and so on, but you are free to start your indexing at any non-negative integer.

Example

A theme element, without any contents set, could look like:

<theme name="Balsa" title="Introduction to Balsa" indexorder="1">
    ...
</theme>

The module element

The theme element acts as a container for one or more module elements, each module element corresponds to one module in the theme. Each module element may optionally contain any number of step elements, at most one leadsto element, at most one prerequisites element, and at most one filters element.

Attributes

name name of the module directory on the filesystem. This should not contain spaces or special characters other than the '_' underscore character. You are strongly advised to only use lower-case characters in the name to avoid case sensitivity issues.

title the human-readable module title. This must match the module page title exactly, excluding the namespace.

level module difficulty/specialisation. This should contain either 'green', 'yellow', 'orange', or 'red' depending on the difficulty or specialisation of the module in question.

indexorder location in the flat theme index, should be numeric and each module should have a unique value. In general, the first module should have the indexorder set to 1, the second to 2, and so on, but you are free to start your indexing at any non-negative integer.

Example

<module title="Introducing Balsa" name="balsa_1" level="green" indexorder="1">
    ...
</module>
<module title="Simple Balsa examples" name="balsa_2" level="green" indexorder="2">
    ...
</module>

The step element

Each module may contain zero or more step elements. Each step element corresponds to a step in the module, and it is usually not necessary to specify a step element for each step in the module: you will generally only specify a step element when you intend to place a filters element within it.

Attributes

title The step title. This must match the title for the step in question exactly, including case.

Example

<step title="Identifying a Gug">
    <filters>
    ...
    </filters>
</step>

The prerequisites element

Each module may contain at most one prerequisites element. The prerequisites element allows the course author to list the modules the student should have studied prior to studying the current module. The prerequisites element must contain at least one target element. A prerequisites element without any target elements will cause the processor to halt with an error.

Attributes

None. This element is a container only.

Example

<module title="Simple Balsa examples" name="balsa_2" level="green" indexorder="2">
    <prerequisites>
        <target>balsa_1</target>
    </prerequisites>
</mooule>

The leadsto element

Each module may contain at most one leadsto element. The leadsto element allows the course author to list the modules the student can study after studying the current module. The leadsto element must contain at least one target element. A leadsto element without any target elements will cause the processor to halt with an error.

Attributes

None. This element is a container only.

Example

<module title="Introducing Balsa" name="balsa_1" level="green" indexorder="1">
    <leadsto>
        <target>balsa_2</target>
    </leadsto>
</module>

The maps element

This element is an optional child of the theme element. If specified, you must include one or more map elements in the maps element body.

Attributes

This element is a container only.

Example

Please see the theme map element description for usage examples.

The map element

This element is an required child of the maps element. If specified, and the element passes filtering checks, the contents of the element will be used in the body of the course-wide map (the page from which the user may select the theme to browse, usually via a graphical system such as buttons). If you do not specify a map element, or none of the map elements remain after filtering, the processor will generate an appropriate map for you based on the indexorder of the themes. You must wrap the contents of the map with <![CDATA[ ... ]]> to ensure the contents are interpreted correctly.

Attributes

include allows you to specify a comma separated list of filters under which this map will be included. See the Docs:Filtering page for more information

exclude allows you to specify a comma separated list of filters under which this map will be excluded. See the Docs:Filtering page for more information

Example

This example shows map element whose contents will be placed in the theme map unless the processor has been passed the filter keyword 'autoonly', in which case the system will generate a theme map.

<maps>
    <map exclude="autoonly"><![CDATA[
        <img src="../images/C_Theme6_map.png" width="687" height="480" border="0" alt="" usemap="#Theme6_map_Map">
        <map name="Theme6_map_Map">
            <area shape="poly" alt="" coords="285,315, 407,315, 408,365, 285,365" href="warnings/step01.html">
            <area shape="poly" alt="" coords="443,241, 559,241, 558,315, 445,315" href="differences/step01.html">
            <area shape="poly" alt="" coords="125,241, 240,241, 242,315, 130,314" href="similarities/step01.html">
            <area shape="poly" alt="" coords="286,186, 394,187, 396,241, 285,239" href="introduction/step01.html">
        </map>
    ]]></map>
</maps>

Filtering

Filtering permits themes, modules, or steps to be included or excluded based on keywords provided when the processor is run. The filtering system is discussed in more detail in the filtering documentation. The following metadata elements are used to mark resources for filtering purposes.

The filters element

The filters element can be added to the metadata for any theme, module, or step that needs to be included or excluded depending on the filtering option passed to the processor by the user. If a theme, module, or step has no filters element, or an empty filters element, then it will always be included in the course regardless of the filters specified by the user on the command line.

Attributes

None. This element is a container only.

Example

<filters>
    <include>socs</include>
</filters>

The include element

The include element is a filter selector that can only appear within a filters element. The include element acts as a marker that says "Only include this resource in the course if one or more of the specified include filter keywords matches one or more of the keywords in the list passed to the processor, otherwise do not include this resource in the course". When a resource has a filters element that contains one or more include elements, the resource will only be included in the course when at least one of the filter keywords in the includes appears in the list of keywords provided via the processor's --filter argument. This is the only situation in which a resource with one or more include elements in its filters element will be generated: if the processor is run without a --filter argument, or with a --filter argument whose list of filter keywords does not include one of the keywords set in the resource's includes, the resource will not be included. For example, a resource that has the following filters element will only be generated when the filter list provided to the processor includes 'socs', otherwise it will not be included:

Attributes

None. This element is a container only.

Example

In this example, the resource will only be added to the generated course if the list of filter keywords passed to the processor includes the keyword "socs".

<filters>
    <include>socs</include>
</filters>

The exclude element

The exclude element is a filter selector that can appear inside a filters element. The exclude element acts as a marker that says "If a resource can be included (subject to any restrictions imposed by any include elements) always include it, unless the filter keyword matches any of the keywords in the list passed to the processor". When a resource has a filters element that contains one or more exclude elements, the resource will always be included in the course unless:

1. The filters element for the resource contains one or more include elements, and none of the filter keywords specified in the resource's include elements appear in the list of keywords the processor was given on the command line.
2. One or more of the filter keywords specified in the exclude elements are present in the list of filter keywords the processor was given on the command line.

Attributes

None. This element is a container only.

Example

In this example, a resource with the following filters element will always be included in the generated course, unless the filter list provided to the processor includes 'socs', in which case it will not be included:

<filters>
    <exclude>socs</exclude>
</filters>

This is a more complicated example, where the resource will only be included in the generated course if the filter list provided to the processor includes 'socs', and it does not also include 'demo':

<filters>
    <include>socs</include>
    <exclude>demo</exclude>
</filters>

Outcomes and Objectives

In order to support the inclusion of both objectives and outcomes in course material (and include them in the processed courses so that students may read them), the processor toolchain provides a number of outcome and objective related metadata elements.

The objectives element

The objectives element acts as a container for objective elements. It may be placed inside a theme element (in which case it contains theme-level objectives), or inside a module element, in which case it contains module-level objectives. objectives may not be placed in a course element (ie: the specification of course-level objectives is not supported at this time). Each theme or module element may contain at most one objectives element at any given level (ie: you may have one in the module element for 'module 1', another in the module element for 'module 2', and one in the theme that contains those modules, but you may not have two separate objectives elements inside the theme element.

The objectives element must contain at least one objective element. An objectives element without any objective elements will cause the processor to halt with an error.

Attributes

None. This element is a container only.

Example

<theme ...>
    ...
    <module ...>
        ...
        <objectives>
            <objective>A learning objective for the module it is defined within.</objective>
        </objectives>
    </module>
    <objectives>
        <objective>A learning objective for the whole theme. Will be listed separately from module-level objectives</objective>
    </objectives>
</theme>

The objective element

The objective element is a required child of the objectives element (meaning that, if you specify an objectives element, it must contain at least one objective). Each objective element should contain one learning objective for the theme or module it is defined within, and each learning objective should have its own objective element. The contents of the element may include HTML (in which case, you must be sure to enclose the element's contents in <![CDATA[ ... ]]> to prevent parsing problems), but you are strongly advised to restrict the HTML to basic formatting (em, strong, etc) if you use it.

When generating the objectives list for a theme or module, the processor toolchain will include an introductory message like "On successful completion of this module, you will be able to:" and you should phrase your objectives accordingly.

Attributes

None. This element is a container only.

Example

<objectives>
    <objective>Describe the important features of a Dhole.</objective>
    <objective>Identify the Sign of Koth and explain its meaning.</objective>
</objectives>

The outcomes element

The outcomes element acts as a container for outcome elements. It may be placed inside a theme element, in which case it contains theme-level outcomes, or inside a module element, in which case it contains module-level outcomes. outcomes may not be placed in a course element. Each theme or module element may contain at most one outcomes element at any given level (ie: you may have one in the module element for 'module 1', another in the module element for 'module 2', and one in the theme that contains those modules, but you may not have two separate outcomes elements inside the theme element.

The outcomes element must contain at least one outcome element. An outcomes element without any outcome elements will cause the processor to halt with an error.

Attributes

None. This element is a container only.

Example

<theme ...>
    ...
    <module ...>
        ...
        <outcomes>
            <outcome>A learning outcome for the module it is defined within.</outcome>
        </outcomes>
    </module>
    <outcomes>
        <outcome>A learning outcome for the whole theme. Will be listed separately from module-level outcomes</outcome>
    </outcomes>
</theme>

The outcome element

The outcome element is a required child of the outcomes element: if you specify an outcomes element, it must contain at least one outcome. Each outcome element should contain one learning outcome for the theme or module it is defined within, and each learning outcome should have its own outcome element. The contents of the element may include HTML (if you use HTML, enclose the element's contents in <![CDATA[ ... ]]>), but you are strongly advised to restrict the HTML to basic formatting (em, strong, etc) if you use it.

When generating the outcomes list for a theme or module, the processor toolchain will include an introductory message like "On successful completion of this module, you will be able to:" and you should phrase your outcomes accordingly.

Attributes

None. This element is a container only.

Example

<outcomes>
    <outcome>Recall the various denizens of the underworld.</objective>
    <outcome>Navigate the regions of the Great Abyss.</objective>
</outcomes>