The Monash Unit Description Avatar

A.J.Hurst

Version

Table of Contents

1. Global Constants

Define whether we are running in test mode

Define the location of the home web page, and the base server address

Set this to the name of the unit descriptions directory. There is one of these directories for each faculty using the avatar

Define the base page for any cgi scripts.

Define where all XML and XSL support scripts and files are stored.

2. Overview

This document describes Version 2 of the Infotech Subject Avatar, now know as MonAtar (MONash AvaTAR).

The purpose of the system is to maintain on-line documentation associated with course and unit offerings, originally within the Faculty of Information Technology at Monash, but recently extended to other faculties (Business and Economics, Medicine). The system is built using XML technology, while the actual Common Gateway Interface (CGI) components are written in Perl. This document details the main Perl component MonAtar, with links to the other components.

The XML components of the system include document type definitions (dtds), XML templates, and eXtensible Stylesheet Language Transformations (XSLT). The latter perform significant amounts of processing within the system, and are invoked from within the main Perl cgi script, the MonAtar program itself. These documents are defined separately, as defining XSLT documents within an XML document can get a bit bizarre!

2.1 The Manifest

Files used in this system are described below. In general, XSL files are maintained separately, because of the editing issues mentioned above.

a2x.w

The literate program (old style) to convert text to XML markup. This is actually uploaded to the cgi web site as the derived file a2x.pl.

basic2html.xsl

XSLT transformer for basic markup items

maketest.pl

A hastily cobbled together perl script to generate a test version for running on the local host.

monatar.xlp

The source form of this document. This is a literate program, translated to the output file MonAtar by a suite of XSLT scripts. MonAtar is a perl cgi script.

UnitDescriptionV2.dtd

The document type definition for the unit description itself.

UnitTemplateV2.xml

This defines the initial form of a freshly created unit decription.

V1toV2.xsl

XSLT script to convert unit description documents from Version 1 to Version 2 format

V2Guidelines.xml

An XML file that is converted to V2Guidelines.html and uploaded to the web site. This file contains helpful instructions on how to edit the various parts of the unit description file.

xml2html.xsl

XSLT script to convert unit description documents from Version 2 to HTML, presented as a viewable document or editable document, depending upon the value of the parameter ViewOrEdit (View or Edit respectively).

xml2txt.xsl

XSLT script to translate XML markup to formatted plain text, for editing by novice editors.

xmlextract.xsl

xslt.dtd

A link to the document type definition for all the XSLT scripts that form part of this package.

MakeReviewForm.xsl

mergexml.xsl

MonAtar-appr.xsl

Merge approval information with an XML unit description.

MonAtar-version.xsl

Review2html.xsl

ReviewV1.dtd

sanitiseV2.xsl

stylesheet.dtd

2.2 User Issues

1. Have separate edit buttons for each section.
2. Incorporate a2x.pl into monatar litprog
3. Design Version Control interface
4. Create a lock file on the no version comment page. Delete this lock file when edits are saved or submitted. Good question is what happens if the user doesn't save or submit. Should the lock be removed say after 24 hours? (The edits are saved, but not in the archive.)
5. add StartPoint mechanism to always display description at edit point.
6. Generate the prohibitions matrix; change wording of submit statement; include subject description in email; define interest groups

2.3 Pedagogic Issues

Ainslie Ellis writes:

2.4 Legacy Issues

1. Write a conversion xsl script from old format to new. Complete, called V1toV2.xsl
2. Create copy of units directory and archive wherein all descriptions can be converted. Keep this up-to-date until change-over. Done.
3. The new cgi script will be cookie based, to avoid reauthentication. Done.
4. The new cgi script will be monolithic, to eliminate a majority security hole in the previous version. Done.

2.5 Directories and files

There are various locations where the files are to be stored, defined symbolically within this script as:

XMLPAGE

The directory containing all xml and xsl files required for MonAtar use. On shelob this is $WEBPAGE/cgi-bin, while on ararat it is $WEBPAGE/xml

basic2html.xsl

XSL script included by xml2html.xsl

canonical.pl

perl script to convert an XML file into canonical form. I'm not sure this is required any longer, since sanitise.xsl has been written?

3. The MonAtar Main cgi script and Authentication

The order of tests in here is very important, and controls the security of the system. Do not reorder these tests without obeying the following rules! The key issue is that the avatar can be used without authentication for viewing or comparing unit descriptions, but for all other purposes, the user must be authenticated. A cookie is issued once the user has authenticated, and this avoids having to re-authenticate on repeat visits to the home avatar page.

Two pages generated by the avatar have special significance. They are the login page and authenticating page. The login page requires the user to enter details of their AuthCate userid and password, while the authenticating page performs the authentication of these details by looking up the Monash Directory Pages, and returning information about what is found. This page also sets a cookie, to avoid the user having to re-authenticate.

The first test therefore checks to see if the desired display is to view a unit description. This is prompted by a single parameter UnitCode=unitcode. Any additional parameters and this non-authenticated display will fall through to require authentication.

The next page that can be viewed without authentication is the authenticating page itself. This is the second test, and is driven by the parameter authaction=Authenticate, generated by the login page. It must appear before the login page itself, since no cookie has yet been issued, and we want all attempts to visit pages without cookies to trap to the login page. If authentication is successful, we move to the Unit Selection Page.

If the avatar is invoked with an explicit request to authenticate, or no cookie has yet been issued, we generate the login page.

If the avatar is invoked with no explicit parameters, but a cookie has been issued, then this is a revisit to the avatar, and we generate the Welcome (Back) Page.

Subsequent tests branch into other sections of the avatar for handling.

The final step, if no tests succeed, is to issue a warning about illegal parameters to the avatar.

3.1 avatar initialization

This is my timestamp. I use a contraction of the ISO standard, where the date and time are in most significant order, with a colon separating the day of the month from the hour of the day. The year is 4 digits, all others are 2 digits with a leading zero if required.

Does this editor want to edit the XML markup directly, or does she prefer to use plain text? Set to 1 (in doEdit) if the former.

3.2 avatar main control branches

3.2.1 re-entering the avatar

We have cookie data, so the user has already authenticated and re-entered the avatar. Convert the flattened equals signs back to equals, and extract the given name as the first word in the common name or cn field. Print the Welcome Back heading, and then generate the Unit Selection Page.

3.2.2 Logging in to the Avatar

No parameters supplied to avatar, or authentication forced, so print the login page.

3.2.3 Perform avatar authentication

Handle the authentication process. I am very grateful to Nate Bailey for the original code upon which this subroutine is based, but as it has been significantly altered, all responsibility rests with me!

If authentication succeeds, we get back a domain name dn, which is analyzed to extract the user's given name, and then encoded to avoid problems with internal equal signs, before being returned to the client as a cookie for subsequent authentication purposes.

Finally, we generate the Unit Selection Page.

3.2.4 Handle Illegal Parameters

Note that we should not normally enter this code. If we do, it is because the avatar has been called with unknown parameters, so we print that fact, together with a synopsis of the parameters in error.

3.3 avatar subroutines

doAuthenticate collects username and password parameters from the call, checks that they are non-empty, and calls the LDAP authentication routine.

(Bug 20031009:115255) When extraction the school, department or faculty information, we must allow for leading words before the school/department/faculty key word, so that places like Peninsula School of Network Computing are not discriminated against.

If the faculty is not one of those directly handled, print log message and use InfoTech as default.

3.4 getLatestApproved: subroutine to find most recent approved version

4. The Unit Selection Page

Collect the domain name from the parameter, and analyse it for school and faculty data. If the person identified is not staff, then they cannot use the avatar.

Generate the main content of the Unit Selection Page. The purpose of this page is to allow the user to choose between a range of options for the unit description document. These options are specified by buttons on the page, and cause reinvocation of the avatar with appropriate parameters.

5. View a Unit Description

5.1 doView: view a unit description

doView is responsible for collecting the nominated unit description document, and formatting it using xsltproc under the stylesheet xml2html.xsl, the standard html view of a unit description for version 2 descriptions. (If a version 1 description is encountered, use FECSA-html.xsl instead.) Since this page is intended for printing, it uses a standard text/html header, and does not call printHtmlHeaders!

The following parameters are passed to MonAtar.

UnitCode

The unit code

Editor

If present, an authenticated user

EditExpert

If present, a boolean indicating the expert status of the user

Force the unit code to be upper case. Get the document. Set xslt processing parameters, and process the description to html. Gather the error output, and if that is non-empty, display in an error page, otherwise the output of the translation is used. Discard all temporary files.

xsltproc requires 2 parameters, the stylesheet $xsl defining the translations, and the source xml document $src. In addition, we specify the destination html document $dest, an error file for stderr $erf, a date and time parameter $datetime, an editor parameter $Editor, and a unit code parameter $UnitCode. The latter three are used within the xsl stylesheet.

This avatar may be called upon to handle version 1 documents. Read the first few lines of the document to see what version it is, and set the xsl stylesheet appropriately.

There were errors. Before we display the error file, we munge out all ampersands into ampersand entities, and all less than signs into less than entities.

5.2 getDocument: retrieve a unit description file

The getDocument subroutine retrieves the XML unit description document for the unit $UnitCode. There are two parameters to the routine:

readonly

A boolean which hen true indicates that the document is to be accessed read only.

createOK

A boolean which when true indicates that the document can be created if it does not already exist.

If the document is to be created, the template UnitTemplateV2.xml is retrieved, and the new unit code merged into it using the XSLT transformation mergexml.xsl.

We used to just copy the document here, with the only alteration being to force the DOCTYPE line. However, a transformer sanitiseV2.xsl is now used to render the current document into a canonical form.

6. Edit a Unit Description

There are three stages to editing the unit description, each of which is handled by a separate invocation of the avatar.

Before anything else, ensure that we have a Version Comment.

Next, doEdit generates a rendered version of the unit description, marked up with buttons to change the various editable fields of the document. Each of these buttons forces a call on the next stage of the avatar, with parameters indicating the unit, the field, and the user.

The next stage doChange renders the selected field in an editable text window. The XML of the selected field is extracted from the master document, and converted to ascii text according to the markup. This is done so that naive users are not required to edit XML text directly.

The final stage doUpdate converts the ascii text back into XML, and replaces the original field of the master document with this new text.

6.1 doEdit: Generate an Edit Markup of the Unit Description

doEdit is responsible for collecting the nominated unit description document, and formatting it using xsltproc under the stylesheet xml2html.xsl, the standard html view of a unit description. Gather the error output, and if that is non-empty, we display that in an error page, otherwise the output of the translation is used.

Now (v2.6.13) that there are auto version comments, the final macro call has been reduced from a choice (which depended on a non-null $VersionComment) between the two <doEdit: do NOT have a Version Comment 44> and <doEdit: have a Version Comment 45> macros.

The routine was invoked with no Version Comment parameter. This is essential for version control, so we first invoke a simple textarea screen for the user to enter a version comment. This will be passed around on all subsequent updates following this doEdit call, but discarded once out of the edit-change-update cycle. This allows users to edit multiple fields on the one version comment.

(20031020:152839) omitted. Now that there is an automatic version history comment added, this is no longer essential. The user can still edit the field in the final edit pane.

The first part of this part asks the user to nominate whether they wish to edit plain text ('Novice' user) or XML ('Expert' user). The value of $EditExpert is set on entry to the doEdit subroutine (see above).

We have to sanitise the version comment for passing as a parameter into xsltproc. The call on xsltproc renders the XML unit description document into HTML, with clickable buttons to change the various editable fields.

Question: what should be done with the version comment at this stage?. One option is to insert it into the XML document as soon as possible, another is to defer it until the document is saved and/or archived, yet another is to add it as an editable field (but not yet part of the XML).

xsltproc requires 2 parameters, the stylesheet $xsl defining the translations, and the source xml document $src. In addition, we specify the destination html document $dest, an error file for stderr $erf, a date and time parameter $datetime, an editor parameter $Editor, and a unit code parameter $UnitCode. The latter three are used within the xsl stylesheet.

There were errors. Before we display the error file, we munge out all ampersands into ampersand entities, and all less than signs into less than entities.

6.2 doChange: Generate an Editable Text of the specified Field

The following parameters are passed to MonAtar.

change

a value passed in from the doEdit generated form, with the structure Change FieldA/FieldB, where FieldA and FieldB are hierarchical field tags from the Unit Description document. These are used to extract the original value from the document for setting the default editing value.

UnitCode

The unit code

Editor

an authenticated user

EditExpert

a boolean indicating the expert status of the user

6.3 doUpdate: Incorporate changes into the Unit Description

doUpdate is called when the user has edited a field of the description, and clicks the "Update the ...." button. The avatar is invoked with the following set of parameters:

We grab the new text to replace the field. This is the raw ascii text, as edited by the user. Write this text into a file, for conversion by the ascii to xml translator, a2x. Call the translator, and read the translated text (now in XML markup) back into $newtext.

sanitise the new text to be inserted by

1. removing all new lines and replacing them with spaces
2. replacing multiple spaces with a single space
3. changing double quotes (which foul up the parameter passing at the command line level) to XML entities
4. ditto for single quotes
5. ensuring that all characters are 7-bit ASCII

We add the edited field into the unit description with the aid of the mergexml.xsl XSLT transform. This script takes an existing XML unit description and merges the NexText parameter into the field FieldA/FieldB. This is a two level addressing operation, since many fields of the unit description are subfields of top-level fields. See the mergexml.xsl documentation for further details of this transformation.

6.4 doSave: Incorporate changes into the Unit Description

doSave is called when the user clicks the final "Save" button on the doEdit page. The avatar is invoked with the following set of parameters:

6.5 doSubmit: Incorporate changes into the Unit Description

doSubmit is called when the user clicks the final "Submit" button on the doEdit page. The avatar is invoked with the following set of parameters: