Design and maintenance of the SJTU-SV.com web site
This article describes how we design and maintain the Shanghai Jiaotong University Silicon Valley Alumni Association's web site so the knowledge can be passed on to co-maintainers or the next web masters. This is also helpful for people who need to design and maintain a small community web site. It should be noted that maintenance of the SJTU-SV web site is based on voluntary efforts, so time constraint always plays an important role here.
Design principles
All the web pages should follow the World Wide Web Consortium (W3C) and various open standards as much as possible. It should work for all the major browsers such as Internet Explorer, Firefox and Opera. It should also be friendly to text-based browsers such as Lynx and Links. All HTML files should comply with the HTML 4.01 strict standard and pass the check done with the W3C markup validation service.
We also strive to separate content (structure), presentation and interactivity from one another as clearly as possible. HTML files define content and structure of the pages. They should not specify directly how the pages should be styled or at least they should keep the style information minimal. External CSS (Cascading Style Sheet) files decide how the pages should be rendered, so people can change the style easily without changing the HTML files. Javascript can be used to enhance the interactivity of the web site as long as it doesn't jeopardize the site's basic functions. That is, people having Javascript disabled or using non-Javascript browsers should still be able to navigate the web site and read its pages.
We use the free Concurrent Versions System (CVS) to manage all the source files except most image files. With version control in place, we can easily revert to older versions or compare the changes between any two versions.
Because many pages share quite a few common elements such as header, footer, navigation menu and etc, it is important that we use a template system to manage all the pages so we can just make changes in one place and then they are propagated automatically to all the pages during the generation process. We use Mason, a perl-based template management system because of our familiarity with Perl and its powerful features.
In the beginning, the SJTU-SV web site didn't have the capacity to serve dynamic content easily, so we generated all the pages beforehand and then uploaded them to the web server. Since September 2008, we have moved to a different web hosting company that provides PHP. However, we still keep the old way because it is much faster to serve static pages because no extra textual processing is required from the server. Given that the web site is in a shared Web hosting environment, it is important that processing overhead is minimized.
Development environment setup
You can first follow the guide on creating a local LAMP (Linux, Apache, MysQL and PHP/Perl) development environment and install those useful perl packages for web site development, including Mason. We never modify the files on the hosting server directly without first modifying and testing them in our local development environment. So it is important that you have such a local development environment ready. Then you can request the source file package from the current web masters of the SJTU-SV web site.
Directory layout
Once you get the source file package, e.g.,
sjtusv-files.tar.gz, you
can unpack it with Winzip under Windows or run
tar xfvz sjtusv-files.tar.gz under Linux/Unix.
Needless to say, Linux is the preferred development environment.
The js/ directory contains all Javascript files,
styles/ CSS files and
images/ image files.
The mason/ directory contains all the template files
managed with Mason.
To generate all the HTML files from the Mason templates, you can
run the tools/mason.pl script from the mason/
directory, i.e.,
cd mason; perl ../tools/mason.pl
Template management with Mason
For any html file such as events2008.html, it is
generated from the corresponding events2008.html.mas file,
a Mason template file with the .mas suffix.
Usually a mas file defines the structure of the page
and includes other files, also known as component files. For example,
the Preamble component file defines the character encoding
and includes common CSS files used by all the pages. Additional style
files can be added between the Preamble and
EndPreamble
components for individual pages.
The TopHeader component includes the images for
the school's symbol, the association's name and the school's
motto.
The EventHeader component includes the image
of the school building shared by all the pages and the image for
the events shared by all events pages.
The NavBarHome component includes the navigation
links and images to the various parts of the web site and
the EventLeftNav component includes the links
to the events in different years.
The Event2008MainBody contains the main body
of the page for 2008 events.
The Footer contains the
Google analytics Javascript code to track the site's
visitors so we can learn how to improve our web site.
It also includes the copyright notice.
Chinese text handling
Most of our web pages are written in English, though sometimes we have Chinese text in them. To display a page with a mix of English and Chinese characters, the best way is to use the UTF-8 encoding so Web browsers can display them correctly. However most of the time when editing Chinese characters, we use native encodings such as GB2312 for simplified Chinese, its successor GB18030 or Big5 for traditional Chinese. Therefore conversion between UTF-8 and these native encodings are needed. Luckily, we can use the GNU libiconv package to do it easily, e.g., the following command
iconv -f GB18030 -t UTF8 -o mason/StatusUpdate.utf8 mason/StatusUpdate
converts the StatusUpdate file (in GB18030 encoding)
to the StatusUpdate.utf8 file (in UTF-8 encoding).
Additional notes
There are also some Makefiles in the source file package that help to manage some common tasks such as copying files around, creating symlinks, converting files to different encodings and etc.
References
- Embedding Perl in HTML with Mason written by Dave Rolsky and Ken Williams: This is one of the best resources on web site development with Mason. The book is available freely online from the Mason book web site.