Docs:Course Structure/Module

Each Module page contains one or more steps, and each step contains one or more paragraphs of text that form a small part of your course material. A step starts with a level 2 title (== ... ==) giving the step title, and anything after the title to the next level 2 title or the end of the page (whichever is encountered first) is treated as the content for the step.

Any content on a module page that appears before the first level 2 title will be stripped and ignored during export. You can use this for notes or other temporary data if you desire, or just start the page with a step title.

Layout example

== Step Title ==
First step contents... 

== Another Step Title ==
Second step contents...

<noinclude>{{NS:CourseNav}}</noinclude>

This example contains two steps, and the special <noinclude>{{NS:CourseNav}}</noinclude> line at the end of the page: this line will make your course's navigation block appear at the bottom of the Module page, and it should appear at the bottom of every page in your course material (for more about this, see the CourseNav documentation.)

For a complete example of a Module page, see C:Introduction_to_Arrays

Notes about content, formatting, etc

The steps in a Module page may contain any valid wiki or html markup as described in the Help:Formatting and Help:Editing pages, although links are only partially supported in limited situations (see below for more about this). The following sections provide additional details or instructions regarding various aspects of formatting.

Steps may also contain course processor tags for formatting and structural support. For a full list of supported course processor tags, and examples of their use, consult the input and output hander documentation on the Docs:Course Processor page.

Code/pseudocode in steps

The wiki provides a source tag that allows you to show blocks of syntax-highlighted code in your steps. The tag supports over 150 different programming or markup languages, and a wide variety of highlighting styles. You are strongly advised to use the source tag for all code and pseudocode in your material, as it makes the resulting text far more readable. Please see Help:Editing#asHighlight for full details.

Tables in steps

As of v3.7 of the processor toolchain, you may use html or mediawiki markup for tables. If you want to use an automatically coloured zebra table in your material, you may do so by adding the 'class="zebra"' attribute to the table element:

<table class="zebra">
<tr>
    <td>.... </td>
</tr>
</table>

Creating complex tables can be a difficult and frustrating job. In order to address this, you may author your tables in Microsoft Excel or OpenOffice/LibreOffice, and then use Chris' Sheet to Table web application to convert the spreadsheet into markup that you can copy and paste into your material.

Linking

Links between steps, modules, and themes can be done using normal MediaWiki links, or the course processor [target] and [link] tags. At this time, the ability to use MediaWiki links is subject to the following restriction:

• MediaWiki links between steps, from a step to a module (effectively the first step in a module), or from a step to a theme, will only be exported correctly when the page being linked to is in the course namespace. So, for example, Foo:PageA may contain a link [[Foo:PageB|Name]] and the link will be exported and processed correctly. However, if Foo:PageA contains [[Bar:PageA]], a broken link will be generated in the processed course. If you need to link to material across namespaces, you must use [target] and [link].

Popups in steps

If you have content relating to a step that you wish to hide from the user until they mouse over a piece of test, you may place it within <popup> tag as discussed in Help:Editing. If you want to share a popup between multiple steps, you can place the popup content on a separate page (which does not need to be linked to directly from any pages in the course), and then use page transclusion to include the page content in <popup> tags.

It is important to note that the popup system is not designed to hide large amounts of text. While the popup system conceivably can handle large amounts of text, and you can actually place any content you want in a popup (or transclude any content), it is strongly recommended that you use popups only for shorter explanatory texts, additional information (such as might be placed in footnotes in print pages), additional diagrams or other resources that might confuse the flow and contents of a step, or to let you set up answers to simple self-testing questions. If you find yourself planning to include large amounts of text (over a couple of paragraphs) in popup texts, consider restructuring your content.

Mathematical expressions in steps

The development wiki has <math> support enabled, and you may use it to insert mathematical expressions into your content and the contents will be interpreted correctly by the export tool. The content of the <math>...</math> should be LaTeX maths directives. You may also use \displaystyle, \textstyle, \scriptstyle, and \scriptscriptstyle to control the size of the equations generated. Please see the Formula Help page for an exhaustive explanation of how to use the <math> element.

You may also utilise the [latex]$maths$[/latex] course processor tag to insert mathematical expressions (or any other latex formatting you desire), however the contents of [latex] blocks is not interpreted until processing, and you will not see an interpreted version in the wiki.

Images and Flash in steps

Images should generally be inserted using MediaWiki's [[Image:imagename]] format, but you may use the [image] tag if you desire. Similarly, flash animations should generally be inserted using the <flash> tag described on Help:Editing, or you can use the [anim] tag. Note that, as of v3.5 of the course processor, [image] and [anim] are deprecated, and may be removed in future - wherever possible, please use the MediaWiki tags instead of the course processor tags.

Please do not use 'normal' flash animations for embedding video over 2 MB or so in size, please use the streamed video process as described below.

Image and animation size guidelines

When creating images and animations to include in your material, it is important to keep in mind some restrictions placed on the width and, to a lesser extent, height imposed by the CBT template.

width

The width of images and animations should not exceed 960 pixels. If an image or animation is wider than this, it will not fit within the width of a standard CBT page, and it will result in broken page layout.

height

height is trickier, as that depends on the user's browser window: the page just gets longer to fit the animation as needed, so if an animation or image is too tal to fit in the window, the user will need to scroll to see it all. If you assume a screen size of 1024x768 as a minimum, and ignore browser buttons, menus, etc and window decoration, for an animation to fit in the available space it can be up to 534px high. Realistically, 450-500px is likely to be more accurate depending on the browser.

The value given for the height is based on a very conservative screen size (a leading survey of home computers shows 1024x768 is used on only 5% of machines, while higher resolutions like 1280x1024 and 1920x1088 are more prevalent) so you may be more flexible with the height of your images and animations.

Applets in steps

You may include applets in steps using the <java_applet> tag as described in Help:Editing.

YouTube videos in steps

You may insert embedded YouTube videos in steps using the <youtube> element. For a full description of this facility, please see YouTube Video Embedding on Help:Editing.

Including streamed video in steps

If you want to provide the student with a large video, uploading it inside a swf is not a good idea - any video over a couple of MB should probably be streamed. In order to set up streaming you should follow these steps (See Docs:Embedding Video Streams for more information):

1. convert the video to .flv, including full keyframe metadata.
2. upload the generated .flv file to the wiki
3. optionally grab an indicative frame from the animation, add a 'play' image (sample image available available here), and upload the image to the wiki. If you do not generate and include a splash image, the video will begin playing as soon as the page loads, and you can only include one streamed video per page. It is highly recommended that you generate and include splash images!
4. insert the following code into your page

 <streamflv splash="splash image name" width="width in pixels" height="height in pixels">flv file name</streamflv>

If you did not create a splash image in step 3 above you can omit the 'splash="splash image name"' attribute. For example, if you insert

 <streamflv splash="Animusic_03_splash.png" width="320" height="240">Animusic2_03_ResonantChamber.flv</streamflv>

it will generate the following:

<streamflv splash="Animusic_03_splash.png" width="320" height="240">Animusic2_03_ResonantChamber.flv</streamflv>

Page transclusion

Page transclusion is the name given to the ability to include the contents of one wiki page in another. MediaWiki's template system is a specific form of this, but as described on Help:Templates, you can use the system to include the contents of any page inside another. The wiki2course script has complete support for page transclusion since v3.7, and you can use normal page transclusion, simple templates, and templates with arguments and the resulting step will show the content correctly.

How is this useful? Imagine that you have a piece of text, image, or the like that appears in multiple places in your course (or even in several courses!) Instead of duplicating the content in several places, you can create a page (which does not need to be directly linked from the course data, theme, or module pages - in fact, it does not need to be explicitly linked from anywhere save from the transclusion marker) containing the data that should appear in the various locations, and then place {{NS:Page name}} at the locations you want the content to appear.

As hinted above, the namespace in {{NS:Page name}} does not necessarily need to be the namespace of your course: you can transclude pages from anywhere in the wiki, be that within your own course namespace, from a different course namespace if courses share content, or anywhere else!