Technical Note - Web Site

Welcome to the ECS web site. This site is actually built on a wiki, which means that if you are a staff member (or other authenticated user with permission) you are able to update the site in your browser.

Foswiki

Our site is built with Foswiki. Foswiki is a wiki platform, like Wikipedia. This means that the site doesn't exist as flat HTML files anymore, but rather a program generates the site dynamically from formatted text files. You may have seen or used wikis that have grown very quickly, and seemed disorganised. Wikis encourage this as "organic content." We don't need to worry about this! The ECS programmers will provide the skeleton from which the new site will grow, and only ECS staff (and trusted others, see Authentication) can edit the pages. This will ensure responsible editing. Pages that are automatically generated, like the undergraduate course list, will be locked so that only the programmers can change them, preventing accidental changes.

We've chosen Foswiki as it already works correctly with many of our systems, and offers many powerful plugins. Foswiki is a fork of TWiki that we previously used.

Using Foswiki

Getting Started / Editing pages

There are formatting hints on the editing pages. So get started! Use the "Edit" button at the bottom of each page (you must be authenticated to see this) to change things around. Remember, if you make an unintended change, you can always roll the topic back to a previous revision, so don't be scared. However, please keep in mind that the ECS web site is our external face to the world, and it is up to all of us to make sure we look professional throughout. If you have any questions or concerns, email the programmers.

General documentation on Foswiki is available from the System Web. New users will especially want to look at:

• Beginners Start Here
• Editing Shorthand
• Macros and Variables
• The Image Plugin (for handling images on your pages)

"Edit" vs "Edit Wiki Text"

"Edit" uses a WYSIWYG interface (like Microsoft Word) where as "Edit Wiki text" lets you edit pages directly using the Foswiki syntax. You should try using Edit Wiki Text, and if you feel comfortable with it, stick to it. You'll write cleaner pages and feel more comfortable using the more powerful features of Foswiki, like the plugins. If you do find Edit Wiki Text difficult, please be aware that Edit's WYSIWYG interface is not perfect. It has an annoying habit of adding unwanted whitespace, which you may need to remove with Edit Wiki Text later.

Images

Use the System.ImagePlugin to put images on pages. You do this by attaching the image you want to the page (make it so it doesn't show in the attachments table) and then referencing it with the System.ImagePlugin syntax.

Linking to courses

If you wish to link to a course, simply type

Course:[CourseCode, eg. COMP102]

Using the above example results in: COMP 102

Linking to people

If you wish to link to a person, type:

Person:FirstnameLastname
PersonTitle:FirstnameLastname

PersonTitle will add their academic title to the link. For example, John Hine and Prof John Hine.

Time-sensitive pages

If a page needs to be revisited every year, such as one used in a prospectus, place at the top of the topic:

%INCLUDE{"Main.ValidYear" YEAR=X"}%

where X is the current academic year. That way, we can keep track of pages we need to go back and update. Staff can find these pages with the :locked: Main.WikiAdmin page.

Editing your personal page

Your personal page is set to only be editable by you. It includes a template that will populate the page with a template, your photo (if it exists) and information about yourself. Do not remove this included file.

The included file finishes with a "Research Interests" heading. You should write something about your research in this area, preferably in the third-person. You may then include any wiki formatting you like, so you could have a heading called "Biography" and discuss your professional history.

Do not abuse this page! It is your official, professional page to the wider world. If there are personal things you wish to put online, put them in your own public_html folder, or a personal Web..

To change your personal picture on the page, click on Attach in the bottom bar. Select "manage" for the current picture attached there and select a new local file to update it from. The template looks for files called FirstnameLastname.jpg. So for Chris Lewis to put up a jpg of himself, he attaches a file called ChrisLewis.jpg. (Remember to make the attachment so it doesn't show in the attachments table, or you will get a list appearing at the bottom of your page.)

Shell scripts

The following shell scripts are available to make some tasks on Foswiki quicker or easier. Please note: you need a valid Kerberos ticket to run them.

• twiki-attach - This allows you to attach files to a topic.
  The syntax is as follows:

  twiki-attach [options] -w wikipage filename(s)
     Options are:
       -c comment
       -h (hide attachment table)
       -l (create a link to the file)

  For example - to attach two files to the WebHome page of COMP 102 and not show them on the attachment table:

  twiki-attach -h -w https://ecs.wgtn.ac.nz/Courses/COMP102_2012T2/WebHome file1.txt file2.txt

• twiki-edit - This allows you to edit a topic using an editor installed on your computer.
  The syntax is as follows:

  twiki-edit -w wikipage

  For example - to edit the WebHome page of COMP 102:

  twiki-edit -w https://ecs.wgtn.ac.nz/Courses/COMP102_2012T2/WebHome

• twiki-remove - This allows you to remove attachments from a topic.
  The syntax is as follows:

  twiki-remove [options] -w wikipage filename(s)
     Options are:
       -a remove all attachments on page

  For example - to remove the file1.txt attachment from the WebHome page of COMP 102:

  twiki-remove -w https://ecs.wgtn.ac.nz/Courses/COMP102_2012T2/WebHome file1.txt

Structure

Foswiki is split into webs. These are self-contained areas of the site. Almost all pages live in the Main web, with the exclusion of events (in Events). More webs will be opened up when we need them.

Foswiki pages are called topics. The name for a new topic should be a WikiWord if it makes sense. The name should describe what is in it. For example, this topic is called TechNoteWebSite, and it correctly points out that this is a Tech Note. Notice how the title of the page in the title bar and the breadcrumb trail is built from spacing out the WikiWords. However, it is OK to use a single word if nothing else makes sense, as we very rarely use Foswiki's autolinking feature for WikiWords.

WYSIWYG Editor Bugs

Known bugs with the WYSIWYG editor:

• It puts extraneous white space into topics.
• It sometimes refuses to save text into a topic. Possible remedies:
  • Press the back button on your browser, and try to save again (this happens with Safari in particular)
  • If you cut and pasted the text, try pasting it in a text editor first, then cutting and pasting that, so as to remove the formatting
  • Type it by hand

To avoid all these bugs, you should try editing with the Edit Wiki Text functionality (click the pickaxe in WYWIWYG mode) where possible.

Authentication and Access Control

Foswiki works natively with our authentication systems, you should be able to use your normal username and password. You are able to access the pages as https:// if you would rather.

Because we are no longer reliant on the file system to check access permissions, we can now use access control lists. These are a good thing! This means that you can set the permissions to allow all of your normal research group members, plus any collaborators you would like, provided they have ECS usernames. Often collaborators are already issued with an ECS username so they can access the ECS file system. If they aren't, send a request to jobs@ecs.vuw.ac.nz.

Permissions will be set by the programmers for your research web when we create it. If you need to over-ride specific pages (perhaps to show a page to a PhD student, or perhaps hide one!), you can read the documentation at AccessControl.

Anyone with edit capability on a page has the ability to change the permissions of that page. If you don't trust someone, don't give them edit permissions! However, the programmers can always roll-back a page to a previous revision if any vandalism takes place.

Access Control Examples

Access control can be modified on an entire Foswiki web or on a single topic. Settings for webs are done in the WebPreferences topic of the web you are restricting and topic settings are done on the page/topic itself by clicking on "More topic actions" at the bottom and then "Edit settings for this topic". The only further difference between these settings is in the use of the WEB or TOPIC keyword. Settings on a topic will override the web's settings (see AccessControl for more detail)

The default access settings are set up as follow:

• Main web - allows everyone (authenticated and unauthenticated) to view topics and staff members to edit topics.
• Staff web - allows only staff members to view and edit topics.
• Course pages webs - allows only staff members to view and edit until the ALLOWWEBVIEW setting is changed (see Course pages).

• Examples: (There must be 3 spaces before the "* Set" for the setting to work correctly.)
  • To set view access to only authenticated users (anyone with an valid ECS/MSOR account, ITS account or configured OpenID) on a topic. (This is done by denying access to the account used for unauthenticated users):

       * Set DENYTOPICVIEW = WikiGuest 

  • Allow only users john and bob to edit a topic:

       * Set ALLOWTOPICCHANGE = john, bob 

  • Allow only users john and bob to view a topic:

       * Set ALLOWTOPICVIEW = john, bob 

  • Allow only staff members to view a topic:

       * Set ALLOWTOPICVIEW = EcsGroup 

Course pages

At the beginning of each year a Foswiki Course web is automatically created for each course. The topics on this web needs to be changed by the lecturer responsible for the course. The created WebHome page contains instructions for the changes needed. (You can also request that the previous year's content be copied to this year's by submitting a job).

Pages on a Course web can also be created by clicking on any red links in the left sidebar. If you create a page using this method please also set the page's 'topic parent' setting after editing. You can do this by clicking on 'More topic actions', then enter 'none' or the parent page name in the 'Set new topic parent' section and then click on 'Set new parent'.

This web is only readable by ECS Staff when created. When you are ready to make it publicly accessible and have it linked off the course's info page and the Course Homepages list you should edit WebPreferences (use Edit wiki text) and remove anything on the right hand side of the "* Set ALLOWWEBVIEW ="

Plugins

There are over 200 plugins for Foswiki. We've got a number of installed plugins, but the most interesting are LatexModePlugin, SpreadSheetPlugin and InterWikiPlugin. These will make editing pages a lot simpler, and provide a lot of power to those who wish to utilise them.

LatexModePlugin

LatexModePlugin allows you to type LaTeX equations directly into a web page, like so:

You can even type equations in-line with normal text, so you could specify without having a line-break. This should be of great use to a number of mathematicians who wish to share their work correctly. Some commands that pose a security risk, like newcommand and include have been disabled. If you type your equation incorrectly, an error message will appear at the bottom of the page.

SpreadSheetPlugin

SpreadSheetPlugin provides functionality for performing calculations on the fly, say to add up the contents of a table. The final cell is defined as

%CALC{"$SUM( $ABOVE() )"}%

Course	Students
COMP101	12
COMP102	64
COMP103	2
Total enrolled	78

There are far too many functions to list here, but they are all standard spreadsheet functions.

InterwikiPlugin

InterwikiPlugin lets you quickly form links that search other sites. It was designed to link disparate wikis together, but actually can prove very useful for searching other sites that don't use WikiWords. For example, one might want to find out about Victoria University of Wellington at Wikipedia:Victoria_University_Of_Wellington or Google:Victoria_University_Of_Wellington. You don't need to know the URLs, TWiki will fill them in for you. There is a list of possible sites to search. We've made changes to the original plugin that allows it to create links using different separators. By convention, where you would use a space in a search query, use an _ . If you are referencing a language API, you should be able to use the actual class name, such as Java:java.util.ArrayList .

SyntaxHighlighter

There is a syntax highlighter installed. To use it, write

%CODE{lang="languagename"}% CODE_HERE %ENDCODE%

where language name is the name of the language in all-lowercase. Most languages are supported.

Thanks to Sun Microsystems for this code snippet:

/** 
 * The HelloWorldApp class implements an application that
 * simply prints "Hello World!" to standard output.
 */
class HelloWorldApp {
    public static void main(String[] args) {
        System.out.println("Hello World!"); // Display the string.
    }
}

Non-Foswiki Pages

Personal homepage

Staff and students with valid ECS user accounts are able to host a personal website on the ECS homepages webserver. In each user's home directory there is by default a directory called public_html which is used for the content of this website.

The personal homepage will be located at http://homepages.ecs.vuw.ac.nz/~your_username

To start using your personal homepage some initial setup needs to be done.

The first step is to make you home directory searchable by 'others' . By default the permissions on this directory is 700 (user has full permission and nobody else has any access). This needs to be changed to 711 for the web server to be able to find your public_html directory (groups and others need search access). A command that can do this is:

chmod a+x ~

Next you also need to make sure that the public_html directory has the same permissions. This command will show the permissions on the public_html directory:

ls -ld ~/public_html

if the permissions are not 'drwx--x--x' (user has all permissions and group and others only search) you need to run this command as well:

chmod a+x ~/public_html

(After running these commands it might take a little while for the web server to update with the new permissions.)

Please Note:
Any files viewable on the web, must have world read permission set.
If you make this change you also need to be aware about the protections on any sub-directory within your home directory and tighten them up as appropriate. Other users (ie: students) won't be able to list the contents of your top-level directory (as long as they only have 'search' and not 'read and search' permission). But if they could somehow learn (or correctly guess) the name of any of those sub-directories, and these sub-directories had the system default permissions of 755, they would be able to list the contents of these directories.

Also note that with current settings on the web server you need an index.shtml file for the base address http://homepages.ecs.vuw.ac.nz/~your_username/ to work. Any direct page link eg: http://homepages.ecs.vuw.ac.nz/~your_username/example.html for a .html file should work however. (If you make your public_html directory world readable index.html will work for the base address)

If you also plan to run PHP or other CGI scripts please see the following pages as well: TechNotePersonalPHP and TechNotePersonalCGI

Course directories

Location

Each course offering has a directory for the current year / trimester, under /vol/ecs/courses/XXXXnnn/YYYYTn or https://ecs.wgtn.ac.nz/courses/XXXXnnn/YYYYTn (where XXXX is the subject code, COMP, MATH, OPRE, STAT etc, and nnn is the course number, eg 201. YYYYTn is the year / trimester combination for the course offering (e.g. 2003T1)).

This directory is owned by the course co-ordinator, and is typically group-writable for all group staff. We recommend that all public, internet-accessible material about the course be kept in that directory somewhere.

Each web directory has a corresponding private directory (e.g. 2003T1-prvt), that is not accessible through the website. This directory is where you should place private, staff-only course material (such as grades, lecture preparation, assignments).

Structure recommendations

EXPL000 is an example course homepage that you can use to create the recommended structure. In particular, the $course_home variable may be useful to you (see the SSI Helper)

You can look at the example pages in the following directory: /vol/ecs/courses/EXPL000/2003T1

If your course doesn't have a directory yet, contact the programmers to get one created. The course co-ordinator is responsible for maintaining the documents within each course directory. There is no automated rollover of course material from year to year; course co-ordinators should review the material available to students in those directories regularly.

Content and Naming

You can keep any/all information in these directories. A world readable index.shtml or index.html will be recognised and linked-to from the course prospectus page as the course's homepage.

The text of the official course web pages is maintained centrally by the programmers.

Protection

The course co-ordinator should ensure that all the information in the course directory is protected appropriately. Please look at the Authorisation section for more information.

FAQ

Is my personal site/course site going anywhere?

Course pages are now part of the wiki. Personal pages continue as is but if you want a personal wiki, ask and one will be created for you.

Why is the site slower?

Foswiki is a Perl program that dynamically generates every page, taking into account your authentication, parsing the Foswiki markup, and running searches. This inevitably is slower than simply reading a file from the file system. However, we've managed to speed up page loads to less than a second in 99% of cases.

Are there any security concerns?

No. Foswiki is designed from the bottom-up to work with enterprise-level authentication, and has a formalised process for security alerts. Between the access control lists, and a custom ECS plugin to ensure other forms of security that Foswiki was not capable of natively, the site is as secure as it has always been.

Who has permission to do what?

• Staff: Can edit the Main web, but are not able to edit pages that are automatically generated by the programmers. There is also edit permission for the private staff area.
• Students: Nothing, unless permission is explicitly given

In addition: revisions are only viewable if you have permission to edit that page. Staff can also view/edit the Sandbox. Non-authenticated users cannot see the Sandbox, and will not see any of the wiki scaffolding (such as edit buttons).

Can I use HTML?

Yes, but please do not use HTML if you can at all help it. A large amount of time has been spent to make sure that our web site validates (this is like coding web pages with the warnings on; there aren't any obvious errors, but unexpected things might go wrong). Much of the last site did not validate, and we would like to avoid that this time. The easiest way to write valid, correct HTML code is to not write any HTML at all, and stick to the wiki markup. Foswiki will make sure that it generates correct code. If you do write HTML, use the "Valid XHTML" link at the footer of every page to make sure that what you wrote is correct.

Is the URL case-sensitive?

No, but making new topics is! For example:

ECSCourses and EcsCourses

Foswiki will allow you to make both topics, as it is case-sensitive. We have a plugin that makes a "best-guess" as to which page to choose if the chosen URL doesn't match an existing topic. So for:

https://ecs.wgtn.ac.nz/main/ecscourses/

It will match the Main web, and then match EcsCourses (as UNIX has a precedence for lower-case letters). We don't know whether the user wanted ECSCourses or EcsCourses

To avoid this problem: Don't make topics with the same name as others! Be careful what you link to!

I have another question

If it's a question or comment, email the programmers. If it's a bug report, please refer to Support.

Acknowledgements

ECS's web site is part of a wider Internet community, and we are proud to draw on, and properly cite, the talent of programmers, artists and photographers around the world.

We use FamFamFam's Silk icons in some places, licensed under Creative Commons. There are other photos around the site also used under a CC license, and the author's are credited next to the photo where at all possible.

The site is built on Foswiki and before that a heavily-customised build of TWiki. Many thanks to the members of the TWiki IRC Channel for their help during the building of the site, in particular Sven Dowideit, and all the authors of the plugins that we rely on.

We utilise Google's expertise to power our search, and interface with Google Maps.