Introduction

The shezhu (the honeyguide) is well known among the Shona for guiding hunters, or indeed anybody who may happen to be passing by, to a beehive. It uses three distinct calls. On first meeting a person and desiring to guide him to a beehive, it will call without ceasing "Tse, tse, tse!" until it gets to the vicinity of the hive. Then it alters its call to just one "tse" and continues with this call until the hive is almost discovered. It then alters the call to "Kwadziya, kwadziya!" ("It is warm, it is warm!"), meaning that the hive is nearby. Shona hunters say that if you do not reward this bird with some honey, it will lead you to some savage animal the next time!
- Claude G. Mararike, extract from The Use of Trees, Birds and Animal Behaviour as Measures of Environmental Change by the Shona People of Zimbabwe

About

The Shezhu Resource Sharing System (pronounced Says-Who) is an application for scheduling and booking shared resources such as rooms and equipment. It was developed for the School of Informatics in the University of Edinburgh.

Features:

Portable - client only needs a modern web browser
Point and Click - almost no typing required
Intuitive - simple, obvious, consistent and user friendly
Innovative - visual filters for making block/repeat bookings
Powerful - concurrent users and double booking prevention
Configurable - local site customization supported
Useful - built in support for configurable academic term, semester and session blocks
Free!

Screenshots

Basic display	Making a booking	With bookings

Show bookings	Filtered

Requirements

In order to run or build the Shezhu Resource Sharing System you need some third-party software available on your machine.

Client

The client needs a modern web browser and the best browsers for this application are Firefox, Mozilla (including the Netscape branded equivalent and Gecko derivatives such as Galeon) and Microsoft Internet Explorer. The newest versions of all these browsers will work best. This application also works with the Konqueror and Opera browsers but these have some issues which may affect functionality. All browsers need JavaScript enabled. Any of these browsers may not work properly (or at all) depending on the operating system they are running under. Text based browsers (such as Lynx) are not supported.

For a comprehensive list of supported client browsers and operating systems refer to this browser compatibility chart from the most recent release of the application.

Server

The server needs recent versions of the Apache web server (preferably v2.2) and the MySQL database server (preferably v5). It also needs Perl (v5) and some Perl modules (DBI and DBD::MySQL). To reconfigure the system the Perl modules Date::Manip and Image::Magick are also needed.

The server has been tested on FedoraCore6 and FedoraCore8 Linux/i386 platforms although there is no specific reason why it should not work on other Linux platforms and distributions.

Development

Rebuilding this application from source requires a standard Unix development environment with the sh, make, cc, cpp, sed and awk utilities. Also required are RCS, Perl (5.6+) and the ImageMagick program. Also required is RPM to build a distribution. All these programs would probably come as standard in Linux distributions, other platforms may not have all of them by default.

License

The Shezhu Resource Sharing System is licensed under the GPL and is available free of charge for personal use, educational institutes (schools, colleges and universities), not-for-profit organizations (registered charities, pure research centers and government bodies) as well as commercial organizations.

Copyright and Warranty

The Helvetica font face used is Copyright © 1984-1989, 1994 Adobe Systems Incorporated and Copyright © 1988, 1994 Digital Equipment Corporation. All Rights Reserved. Helvetica is a trademark of Linotype-Hell AG and/or its subsidiaries.

BECAUSE THE APPLICATION IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE APPLICATION, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE APPLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE APPLICATION IS WITH YOU. SHOULD THE APPLICATION PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE APPLICATION AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE APPLICATION (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE APPLICATION TO OPERATE WITH ANY OTHER APPLICATIONS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Download

The newest release of the Shezhu Resource Sharing System can be downloaded by right clicking on one or other of the links below and selecting Save As or Save Target As.

shezhu-1.20-1.noarch.rpm (320KB)
shezhu-1.20.tar.gz (342KB)

The above provides a default installation which should work on FedoraCore8 systems and can then be customized for your own site.

In order to use the software on other platforms and configurations you will probably need to recompile from the source by getting one or other of below.

shezhu-1.20-1.src.rpm (136KB)
shezhu-1.20.src.tar.gz (133KB)

Installation

Instructions for installing the Shezhu Resource Sharing System.

Install the default build. You should do this first to make sure it works (unless you have a different platform):

rpm -i shezhu-1.20-1.noarch.rpm

Or if you prefer/need to use the .tar.gz file then:

tar zxvf shezhu-1.20.tar.gz

Both will install the system into /etc/shezhu, /usr/lib/shezhu, /var/lib/shezhu, /var/run/shezhu and /var/shezhu and will add /usr/sbin/shezhuctl. Change directory into /var/shezhu and look at the README for instructions on bootstrapping the database structure and starting the server. There are also instructions on reconfiguring the date range, resources, users and site localization included in the README.

If you need to install onto a different platform or if the above has worked and you want to make permanent local site customizations in an RPM you need to rebuild. First you need an RPM build structure, or as root:

su

rpm -i shezhu-1.20-1.src.rpm

cd /usr/src/redhat/SPECS

rpmbuild -ba shezhu.spec

rpm -i ../RPMS/noarch/shezhu-1.20-1.noarch.rpm

The above will rebuild the default RPM on the local platform. To make local customizations do:

rpmbuild -bp shezhu.spec

cd ../BUILD/shezhu-1.20

Then follow instructions in BUILD to edit the files to localize the build and make an RPM for your own site.

To rebuild from the .tar.gz file instead do as follows:

mkdir shezhu-1.20

cd shezhu-1.20

tar zxvf shezhu-1.20.src.tar.gz

make

make install

See the BUILD file for more detailed instructions and for a list of additional pre-requisite software.

The source RPM's should build on most modern Linux distributions, but on all platforms you may need to be careful to make sure all the build requirements are met first.

Inside

The Shezhu Resource Sharing System has ended up built upon a large menagerie of modern web application development technologies. What they are and what they are used for is summarised below - as well as if they are any good! All comments reflect my own personal view of course. There are also links to further resources about each technology. Personal comments aside, everything here is first class technology and all of it is available free of charge!

DHTML (Dynamic HTML) - Not a techology in itself but a term covering any web application using a combination of HTML, CSS, DOM and a scripting language (such as JavaScript).

HTML - This application uses JavaScript to dynamically create the markup for the interface page on the fly.

CSS (Cascading Style Sheets) - This application uses JavaScript to dynamically create large and very complex CSS on the fly to correlate with the HTML.

DOM (Document Object Model) - The object API to the document (web page). Most stuff is compatible between browsers but there are some annoying discrepancies. Used to dynamically change the HTML and CSS in the document.

JavaScript/JScript/ECMA-262 - Wonderful, fast, easy to use, yet powerful and flexible web browser scripting language. Based on the ECMA-262 scripting language and now very compatible between browsers. Absolutely no relation to Java.

DynAPI - This is Dan Steinmans excellent cross-browser DHTML library for JavaScript. Design your application using this and it should work on most browsers. There are some other good cross-browser APIs as well and also DynAPI2, the new version of this.

MySQL - Fast SQL database server, very popular for web applications and ideal for this application.

Apache - The web server. Simply the best.

The build procedure also makes use of a number of tools.

GNUMake/CC/CPP - The GNU code development environment. So commonplace it tends to be forgotten about - that is until you try to do anything under Microsoft Windows where you will be cursing at the increased hassle and development time - solution is get Cygwin, the Unix environment running under Windows.

Perl - The ubiquitous and very popular scripting language. While not desperately user friendly and not always easy to find documentation on how to do the more obvious and common operations it is powerful and relatively unlimited in scope.

RPM - The Redhat Package Manager. Simple yet powerful tool to wrap up binary and source for distribution and installation.

ImageMagick - The gran-daddy of all image format conversion programs. Not only does it convert between just about every image format known to man it also lets you manipulate images in various ways including adding text and transparency, all of which can be done from the command line or scripted.

Future

Below are some of the intended future developments for the Shezhu Resource Sharing System in no particular order. If there are other enhancements you think would make the system better please contact us.

Support mouse dragging to select/deselect slots
Support whole day horizontal resolution
Support whole week/month vertical resolution
Support resource type/group switching (extra feature)
Include public holiday and other special day info in date images
Preserve feature settings across sessions in user cookie
Re-design grid update routines to improve speed/clarity
Integrate scrolling layer into grid object for efficiency
Add tooltips

Contact

For any other queries and support please mail <tcolles@shezhu.org>. Do not expect an immediate response though, we have plenty of other things to do!

News

Release 1.20/01-02-2008

More changes to specfile and localization to support Fedora packaging, including user/group setup in pre script and corrected attributes.

Release 1.19/11-01-2008

Switched to GPLv3.

Added support for MySQL v4 and v5 (by Neil Brown).

Converted specfile and build process to meet Fedora packaging conventions.

Anchor to UTC rather than local time - this makes it more portable outside of GMT but may cause problems for DST.

Supports Apache 2.2 by default.

Release 1.18/25-01-2006

Checked builds and runs under FC3 (yes) and added support for Apache 2 (the default with FC3) by tweaking and simplifying the httpd.conf file (remains backwards compatible with Apache 1.3).

Installed file structure revamped, instead of everything going under /usr/lib/shezhu files are now installed into /etc/shezhu, /var/shezhu, /var/lib/shezhu and /var/run/shezhu as well.

Supports multi-site installations (each site shares the mysql and http servers but has its own database and also directories for configuration and web files) - allows one host to serve more than one site.

Access control and initial installation tweaked to fit in with new installed structure and multi-site support.

Added a favicon.ico.

Base configuration file local.mk split into site.mk and server.mk.

Fixed the warning message on compacting (occurs with newer CPP).

Image building now does not generate any screen output by default.

Scripts renamed: myinstall->setup, myaccess->access, mypurge->purge and configure->build.

User access control file (originally users, now users.cnf) has been combined into normal access control mechanism (via build).

MySQL now configured via generated my.cnf file rather than command line arguments.

Building RPM no longer attempts to create debuginfo package.

Release 1.17/11-04-2005

Fixed a bug in the CGI bookings page that meant bookings were not being properly sorted into time order on each day.

Changed the display of bookings in "hover" mode so that they are sorted and listed in time order (on first time slot) rather than just default booking order.

Changed so that the CGI connector script uses a separate file containing the remote user password rather than it being embedded in the script itself (makes post-install re-configuration simpler).

Replaced edudm.src with datemap.src (dropped mkedudmXX as a separate script, function now incorporated into mkbasedata which replaces the mkdates script). The new date mapping syntax supports sessions, allows multiple mappings in one file and different mappings per year. An extra field in dates.src specifies the particular local site mapping to use. The edudm.js file is no longer generated as the values are now derived via the array in base-data.js (which replaces dates.js) and edudm.pl is also redundant.

Dropped the mkrsrcsjs script and the generated resources.js file. The functionality has been incorporated into mkbasedata instead and the generated output has become part of base-date.js. Some of the image generation has moved from mkimages to mkbasedata because it has now become dynamic.

Dropped the mkstart script and the generated start.js file. The functionality has been incorporated into mkbasedata instead and the generated output has become part of base-date.js.

Now dynamically includes term, semester and session features based on whether they are referenced in the datemap (the feature display has eight modes and is adjusted based on the presence or absence of these features, with the number of available resources being adjusted to compensate in each arrangement of features).

Dropped the Slot feature from display (retained internally).

Dropped the kiosk (only worked with NN4).

Dropped NN4 browser support.

Dropped CLI as LiveConnect is broken with SpiderMonkey (Mozilla Bugzilla entry #205520) and it is no longer practical to maintain and it was never really used in earnest anyway.

Dropped the JDBC connector. While technically superior to the CGI connector its use of LiveConnect makes it less browser portable. It is also harder to setup and it cannot support the additional authentication features of the CGI connector. The CGI connector is surprisingly almost as fast (not perceptibly slower). Using the CGI connector means Java/LiveConnect are no longer required on the client and SMTP is no longer required on the server and MySQL no longer needs a network connection on the server. Also simplifies configuration and build and runtime requirements.

Dropped browser detection code and replaced with object detection instead which should allow the application to work with a wider range of browsers with minimal source modification.

Initial support added for the Konqueror browser (3.3.1+, minor issues), Opera browser (7.54+, minor issues and one major issue) and the Galeon browser (1.3.20+, no known issues).

Font made smaller on submit panel so the submit/cancel buttons are not hidden with most browsers default font size setting.

Fixes for Internet Explorer browser support.

Updates to browser compatibility chart.

Allow support contact to be a link to a web page instead of an email address. Changed the default for the generic build so as it has no support contact.

Release 1.16/01-11-2004

Fixed a bug introduced in V1.14 that exposed a double booking hole that would only have occured when using the new CGI connector or Internet Explorer.

Release 1.15/16-08-2004

Added an authority email address to each resource. This address is mailed whenever a booking is made using that resource. The address is mailed the same details as the normal confirmation message. The index page has been updated so it also lists the authority address for each resource.

Allow line trailing comment in edudm.src.

Added support for post-install configuration of resources, dates and other options by copying most of the build tree into the installed directory with a separate configure script that does the rebuild. Included changes to the make/install process and image directory structure. Also changed the way the title banner image is created so an X server is not required during build.

Taint checks added to CGI Perl scripts.

Updated requirements paragraph and added text dependency on browser version support as determined by configuration.

Added validation on booking purpose text - silently drops ", &, ?, %, ), and ( characters since they conflict with CGI and HTTP forms.

Fixed problem with scrollbar. Before if held mouse to drag bar and then released mouse after leaving scrollbar pane then when moved back onto scrollbar pane bar will jump erratically to mouse position until click and release explictly. This has been sort of fixed, when leaving the scrollbar pane it will now become inactive. Less confusing for the user but not ideal as a scrolling solution.

Added separate mail address configuration option for sending booking requests by email (previously used same as support mail address).

Release 1.14/13-05-2004

Put in a workaround for a bug in Mozilla on the Linux platform that causes startup interaction problems with Java, see Bugzilla entry #160982.

Fixed the problem of CPP now inserting an extra space in the expansion of #! during pre-localization processing of the bookings perl cgi script.

Upgraded to latest stable version of MySQL Connector/J (replaces MM.MySQL).

Added support for JDBC connector to be configurable via local.mk.

Dropped JDBC Connector class tree from installation (just use archive).

Added support for removing existing booking records, including extending the refresh mechanism to handle removed/changed booking records and changing the booking detail panel and submission panel to handle choosing bookings for removal with improved formatting.

Restyle submission panel using CSS for consistency with changed detail panel.

Really dropped mkcg.c this time.

Mozilla now works best so rejigged index page to reflect this.

Added browser compatibility chart page.

Added GPL license file.

Added a user manual!

New Connector/J is not compatible with Netscape Communicator, added notes in BUILD on how to change configuration to revert to MM.MySQL.

Added a CGI Connector (Perl DBI/DBD) with support for building either a CGI or JDBC installation configurable via local.mk. Honors the Apache REMOTE_USER environment variable for third party authentication modules. Supports more advanced access control than currently possible via JDBC. MySQL network connectivity is disabled when using CGI connector. The log files directory is now protected.

Added myaccess script allowing changes in user access control (via the new etc/users file) to be made after installation.

New syntax for handling password prompting in users.src (and etc/users after install) - use "-" for prompt, and "-x" for prompt if x not already defined else use previous definition of x.

Added LOCAL_PROTOCOL configuration option (default=http) so that we can support SSL (https).

Release 1.13/17-02-2004

Changed mktitle to use Image::Magick module directly.

Rewrote mkcg.c as a Perl include file mkim.pl using Image::Magick module directly for conversion from xbm to gif without system call. At the same time enhanced to be able to draw all characters (lower case and symbols now supported properly).

Modified mkfont to produce a suitable Perl header file for mkim.pl instead of a C header file.

Added command line script mkim as equivalent to mkcg (uses mkim.pl).

Changed mkdates, mkhours, mkimages and mkrsrcsjs to use new mkim include file for image creation instead of system calls.

Dropped gcc/convert as build requirements and added Image::Magick.

Dropped mkcg.c and font.h (and generated mkcg executable).

Changed Makefile.p to use rpmbuild (needed for RH9).

Changed bookings.pre.p as multi-line string literals are deprecated in the RH9 version of Perl (5.8.0).

Release 1.12/11-05-2003

Enabled half hour and quarter hour slot resolution handling.

Fixed bug meaning slot resolution was always set as hours in a booking.

Fixed display of multi-resolution slots so as to prevent double bookings.

Fixed a bug in the simultaneous double booking check and completed the backend support. After a double booking a failure message is now sent.

Fixed a gap in double booking detection. Now as soon as the BOOK button is enabled the display refresh is disabled. This means if selections or the confirmation panel left active for long periods any double bookings get picked up through the normal simultaneous check. As soon as the BOOK button is disabled (through submit or cancel and selections cleared) the display refresh is enabled again.

The slot-hover bookings-list and the CGI bookings page have been extended to handle quarter and half hour slot resolution bookings.

Changed the slot-hover bookings list, the CGI bookings page and the confirmation mail message so times and resources are now always shown in the correct slot order.

Changed the slot-hover bookings list, the CGI bookings page and the confirmation mail message so times are shown as ranges and so consecutive slots are merged taking into account the booking scope.

Changed the CGI bookings page so as it orders bookings on each day by the first time slot of the booking.

Changed the slot-hover bookings list so the bookings shown are now restricted by current hour and resource filter settings.

Hover trigger time reduced from 1.5s to 1s.

Changed local.mk default values and Java SDK paths to match newer Linux versions.

Added a LOCAL_MYSQL_DAEMON variable so MySQL daemon can be configured differently as safe_mysqld doesn't always seem to work (always creates socket in /var/lib/mysql despite --socket argument).

Changed socket filename from mysql.sock to mysqld.sock for consistency.

First Public Release!
Version 1.11 is officialy released into the wild. Naturally its very excited.

Release 1.11/11-11-2002

Hopefully we've now finally fixed the DST date indexing offset problems.

Fixed Sunday not showing in current date/time display.

Fixed day mapping to term week (from above).

Fixed making a booking on same day as base date disappearing from display.

Quick booking check page returns explicit message when there are no bookings.

Release 1.10/06-11-2002

Correction to purge script (missing db argument).

Fix localizer bug when values have embedded equals characters.

Add ssh tunnelling options.

Release 1.09/08-10-2002

Fix Mozilla crash on null exception (eg. incorrect username/password).

Always print ID on Java startup now.

Release 1.08/07-10-2002

Added Internet Explorer support.

Tidied up README for service support.

Added a purge script to remove old booking records.

Added copyrights to index/README pages.

More extensive browser support comments added to index page.

Command line interface for checking resource availability added, with basic usage on index page. Uses JavaScript/LiveConnect shell from Mozilla (not included in this package).

Rewrite of dbc java so as threads aren't used. These are believed to be causing a number of startup problems, including: not loading dates on first startup; second startup on NN4/Win2k platform hanging; long startup or hung startup on NN6/Mozilla Linux 7.1 based platforms.

Correct support for Apache/MySQL paths.

Profiler/Follower(trace)/Debugger support added, enablable at build.

Tidying of localizing/preprocessing stuff, including local site build framework and shifting of resource and date localizations to this.

Loads of changes for public distribution management, ie. removal of any site specific stuff. Also converted to using CVS as a master repository for the site generic distribution. Associated package building framework and rework.

Improved ACL/account support.

Fixed occasional startup problem (didn't load booking data onto display).

Added quick current bookings check page (CGI) linked from index page.

Felix only enabled for NN4 now.

MM.MySQL loaded as an archive now for speed.

MySQL install script made quieter.

Main index page re-ordered for user brevity (launch links at top).

Fixed mailing bug in IE support (duplicate java function).

Changed initialisation sequence to resolve occasional java startup problems.

Fixed fetch data threads increment after every booking.

Faff about with Java.

Release 1.07/21-04-2002

Added framework for cross-browser support, and initial support for Mozilla (Netscape Navigator 6), although only limited QA done.

Changed so its really a resource booking thang rather than just a room booking thang.

Added DP (DataProjector) as an additional bookable resource.

Updated hardcoded horizontal scroll routines to support room/resource grid scrolling (needed now we have >3 resources to choose from). Changed the horizontal and vertical scroll routines so they don't have absolute object references anymore.

Added some missing copyrights.

Upgraded to most recent stable MM.MySQL version.

Upgraded DynAPI layer for Netscape6/Gecko support.

Now builds whole localized distribution directory (plus start scripts and apache configuration files).

Cleaned up local configuration into one file.

List of bookable resources included in the index.html file.

Marginally more flexible access control processing.

Put back the SMNR room.

SQL install script now returns control to terminal properly on errors.

Release 1.06/17-02-2002

Fixed date timezone offset to use date booked rather than current date so that forward bookings (over a DST change) aren't displayed after submit offset by one day back.

Dropped SMNR room.

Release 1.05/03-02-2002

Changed so can only select 0% used cells. This doesn't restrict booking options but does mean in some situations the room slot must be clicked before the hour slot and vice versa to make a free slot selectable. This was done to prevent a possible double booking hole.

Disabled resolution/offset selection of less that 1hr. The double booking checks have not been quality assured for this feature.

Changed expiry/range dates.

Changed title copyright and added copyright message to source program.

Day of month is now correctly zero padded for release date.

Various improvements to index/launch page.

Changed date format in booking confirmation mail message.

Fixed so filter/scroll events clear current selection and update the display pattern accordingly. This also prevents a double booking and incorrect selection for booking defect.

Release 1.04/08-02-2002

Made sure all local variables are explicitly declared as such to avoid conflict with any global variables or function parameters. Should fix any weird bugs. Created one bug which was an error in vertical scrolling which was fixed.

Also made date adjustment hack more generalized which means it can be applied now and will hopefully work on into BST.

Changed title bar copyright message.

Release 1.03/14-12-2001

Another fix to initial data fetch. Race conditions can occur so data is requested and returned before it has been fetched. Fixed this hopefully.

Release 1.02/05-12-2001

Added a reconnect to fetch initial data in java dbc as first connect sometimes breaks (bad handshake) and an empty data set is returned even if there are bookings.

Release 1.01/23-11-2001

Added kiosk.html to allow startup from browser command line in primary window instead of opening another window.

Added major date adjustment hack (see head.js.src) but since the build is for 01/10/2001 (within BST) we don't use it yet (see TODO also).

Release 1.00/??-??-2001
The first internal release!