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.
TWiki
Our site is built with TWiki. TWiki 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 TWiki as it already works correctly with many of our systems, and offers many powerful plugins.
Using TWiki
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. The
Sandbox web exists for you to play around in. All authenticated users can see this web and try editing pages. 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 TWiki is available from the
TWiki Web. New users will especially want to look at:
"Edit" vs "Raw Edit"
"Edit" uses a WYSIWYG interface (like Microsoft Word) where as "Raw Edit" lets you edit pages directly using the
TWiki syntax. You should try using
Raw Edit, 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 TWiki, like the plugins. If you do find Raw Edit 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 Raw Edit later.
Images
Use the
TWiki.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
TWiki.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
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 "Biography" heading. You should write something about yourself in this area, preferably in the
third-person. You may then include any wiki formatting you like, so you could have a heading called "Research" and discuss your research interests.
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.)
If you attach more than one file with one of the valid extensions (say
ChrisLewis.png and
ChrisLewis.jpg)
both images will be displayed!
Structure
TWiki 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.
New pages should be in TWiki.WikiNotation
if it makes sense to. The page should describe what is in it. For example, this topic is called %TOPICNAME%, 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 TWiki.WikiWords. However, it is OK to use a single word if nothing else makes sense, as we very rarely use TWiki's autolinking feature for TWiki.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 Raw Edit functionality (click the pickaxe in WYWIWYG mode) where possible.
Authentication
TWiki 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
TWikiAccessControl.
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.
Plugins
There are over 200 plugins for TWiki. 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() )"}%
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-TWiki Pages
Course pages
Location
Each course offering has a directory for the current year / trimester, under
/vol/ecs/courses/XXXXnnn/YYYYTn or
http://ecs.victoria.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?
TWiki is a Perl program that dynamically generates every page, taking into account your authentication, parsing the TWiki 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. TWiki 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 TWiki was not capable of natively, the site is as secure as it has always been.
Who has permission to do what?
All authenticated users can view/edit the
Sandbox. Revisions are only viewable if you have permission to edit that page. In addition:
- 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
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. TWiki 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
TWiki 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:
http://ecs.victoria.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 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.
EResearch