When preparing to implement a calendar interface for our Vermont travel planner site GoVermont which would allow users to specify hotel arrival and departure dates, we experimented with alternatives to the typical approach of having two separate calendars for arrival and departure, respectively. Personally I have always thought this interface to be a little odd. After all, when people use real, physical calendars to mark off the days of a trip (say), they don’t put two calendars side-by-side and mark the arrival date on one, and then the departure date on the other. Instead, they typically just circle or mark off a block of days on the calendar–in other words, they define an interval of days on the calendar.

The near standardization on the web of the two-calendar interface stems primarily, I think, from the underlying form-based HTML input mechanism where there is one field for arrival date and a separate field for departure date. Given this framework, it seems natural to just attach a separate calendar to each field. But stepping back from HTML forms for a minute, it seems more natural to me, if one is going to implement a clickable calendar at all, to make it more like a real calendar, and for purposes such as the above just allow the user to easily define an interval of dates on a single calendar.

With this idea in mind I created an extension of the YUI CalendarGroup control (a generalization of the YUI Calendar supporting multiple pages) called the iCalendarGroup, which is designed specifically for user selection of an interval of dates. On this calendar, one simply clicks on two different dates to define an interval, and clicks a third time to start over. It functions similarly to the non-multi-select version of the YUI CalendarGroup, but the basic unit is now an interval of dates instead of a single date. Here is a working example:

When using this control in an application, you can easily set and reset the interval selection programmatically, as well as obtain the lower and upper dates for use with other user interface elements (e.g. fields for arrival and departure date, etc.). You can also respond to selection events and take advantage of the other things that the YUI CalendarGroup provides.

The code for this example is extremely simple. The HTML consists of:

<div class="yui-skin-sam">
 <div id="iCalSample"></div>
</div>

The Javascript consists of:

// create interval calendar control
var ical = new YAHOO.whardy.iCalendarGroup('iCalSample',
               { pages: 1, title: 'iCalendar Sample' });
ical.render();

Here is a working two page example, obtained by changing the ‘pages’ value above:

You can obtain the complete, fully documented JavaScript source code for this control here.

Thanks to Eric and Satyen at the YUI team, this control is also now available on the YUI site here.

In the code that follows I use both the Google Maps API as well as the Yahoo! User Interface (YUI) API. The YUI API is only used to simplify HTML DOM event handling, and can be easily replaced with equivalent code from elsewhere.

Let’s take a look at the main JavaScript code first:

// some places
var places = [
	{
		name: 'San Francisco',
		lat: 37.798391,
		lon: -122.419968,
		link_id: 'maplink_sf'
	},
	{
		name: 'Berkeley',
		lat: 37.878918,
		lon: -122.270622,
		link_id: 'maplink_bky'
	},
	{
		name: 'Mill Valley',
		lat: 37.912378,
		lon: -122.548199,
		link_id: 'maplink_mv'
	}
];

if(GBrowserIsCompatible()) {
	// create map
	var map = new GMap2(document.getElementById(’map’),
				{ size: new GSize(500,300) });

	// initialize map
	map.setCenter(new GLatLng(places[0].lat, places[0].lon), 10);
	map.addControl(new GSmallMapControl());
	map.addControl(new GMapTypeControl());

	// mark places and set links
	var coords;
	var marker;
	for(var i = 0; i < places.length; i++) {
		// create and add marker
		coords = new GLatLng(places[i].lat, places[i].lon);
		marker = new GMarker(coords);
		marker.bindInfoWindowHtml(places[i].name);
		map.addOverlay(marker);

		if(places[i].link_id) {
			// set link
			set_map_link(places[i].link_id, map, marker);
		}
	}
}

This code first defines an array of places, each of which has a name, geographical coordinates, and a link identifier. The link identifier is just the ID of an HTML link (anchor) that exists in the HTML and will be used to trigger the map marker associated with the place.

The code then creates a Google Map, places markers on the map corresponding to each place, and for each marker calls a function set_map_link which configures an HTML link to be able to trigger the marker. This function can be implemented as follows (using the YUI API):

// function which makes a link trigger a map marker
function set_map_link(id, map, marker) {
	YAHOO.util.Event.addListener(id, 'click',
		function(e) {
			map.setCenter(marker.getPoint(), 12);
			GEvent.trigger(marker, 'click');
		}
	);
}

This code simply registers an event handler for the ‘click’ event on the specified HTML element (in our case, a link). The event handler centers the Google Map on the specified marker (adjusting the zoom a bit), and then triggers the ‘click’ event on the marker in order to open the info window associated with it.

The corresponding HTML code might look as follows:

<p>Check out these locations on the map:</p>
<ul>
	<li><a id="maplink_sf" href="#">San Francisco</a></li>
	<li><a id="maplink_bky" href="#">Berkeley</a></li>
	<li><a id="maplink_mv" href="#">Mill Valley</a></li>

</ul>

The end result is that, whenever any of these links is clicked, the appropriate marker is displayed on the Google Map, and the info window for that marker pops up. To see this code in action, click here.

I needed to add a feature to one part of the application that required recall of the user’s most recent search. It needed to take into account any AJAX page changes, so that the most recent page would always be recalled. After considering several options, I decided to copy the user’s latest search parameters into session data on each search request. The other component could then later read the stored data and reconstruct the user’s most recent search.

Of course, this raised the issue of preserving the integrity of session data in the presence of AJAX components. As is well documented elsewhere, when one or more asynchronous requests can occur during the course of a page load, or during the course of user interaction with a page, corruption of any shared data (such as session data) can occur. Asynchronous requests can, for example, modify such data in ways that the rest of the application ignores or does not account for. The variable timing of such requests can also create race conditions, and prevent coordination of different parts of the application.

While I recognized this and took efforts to prevent it, still something like this was exactly what seemed to be causing a problem in our application. The search parameters were being correctly stored in the session on non-AJAX requests, but with AJAX requests, the behavior was intermittent; sometimes the correct parameters were stored, and other times they would seemingly get reset to the most recent non-AJAX parameters.

But after doing some logging on the server, I noticed that in these instances two requests were actually happening on an AJAX page change–one for the newly selected page, followed by one for the page corresponding to the latest non-AJAX search. This was very bizarre. And it was not (totally) browser dependent; both Firefox and IE (6 and 7) exhibited this behavior. After enabling the Firebug request logger in Firefox, I could even see the second requests happening–right as new result sets were being loaded in. But I had no idea why they were occurring.

Of course, nothing in the AJAX code suggested that they should be. After examining a number of different things with no success in locating the problem, I thought perhaps this was some sort of obscure bug (or feature?) within either the YUI Connection Manager (which we use to initiate AJAX requests) or else the asynchronous request mechanisms implemented in both Firefox and IE. Googling for help, I initially located nothing useful until I finally stumbled across a helpful blog post…

In the post, the author describes experiencing a superfluous request on page load when an HTML IMG tag on his site contained an empty SRC attribute. And (guess what?) this just happened to be the case for some of our own images! Because some of our images were created as part of a JS-based UI component, being dynamically assigned SRC values by JS code on page load, the SRC attributes were left blank in the HTML. But this was causing both Firefox and IE to (usually) send requests to the current document’s URL–the one in the address bar–when these IMG tags were encountered. This wasn’t a critical problem for non-AJAX search requests since in those cases the document URL contained the latest search parameters; but on AJAX page changes, this was a very critical problem, as it was causing the stored AJAX search parameters to be overwritten!

The fix was, of course, to just point the offending tags to some placeholder image until the JS code updated them on page load. Once this was done, everything worked fine.

While this problem was only indirectly caused by a JS/AJAX component, it illustrates the need to take great care in preserving shared data integrity when building AJAX-enabled applications. All parts of the application must be built with AJAX in mind, accounting for the fact that shared data might be modified in unexpected ways as a result of asynchronous requests.

Contents

• Preliminary Installations
  • Installing Prerequisite Packages
  • Installing MySQL
  • Installing PHP
• Configuring Sun Web Server
• Installing Moodle
• Slash Arguments

Preliminary Installations

As the documentation indicates, Moodle requires several pieces of software to be installed before it can run. First it requires a web server, which in my case was the Sun Java System Web Server 7.0. Second, the web server must have a fairly recent version of PHP installed, with a number of options and extension modules enabled (see below). Finally, a database server is required, which in my case was going to be MySQL.

The PHP installation needs the following options and extensions to be enabled for best results:

• The mysql extension—or the pgsql extension if you are using a PostgreSQL server (required).
• The GD and FreeType 2 libraries.
• The mbstring option.
• Basic extensions: tokenizer, session, etc. (usually enabled by default).
• Other extensions: iconv, zlib, curl, and openssl.
• Additional extensions if you are using some more advanced Moodle features (see Moodle docs).

You also, of course, need a suitable compiler and make utility for compiling and installing PHP with the above options configured (and also for your web and database server software if those are not already compiled or installed).

Since the Sun web server was already installed and running on our server, I only needed to install PHP, MySQL, and all other prerequisite software on which these two items depended.

Installing Prerequisite Packages

For the prerequisites, I used the packages available at Sunfreeware.com. The installations were very straightforward for the most part (just a bit tedious in high concentration!), so I will not document them in detail. As an example, to install the zlib package on our server, I downloaded the file zlib-1.2.3-sol10-x86-local.gz to /tmp, and then ran the following commands from the shell (as root):

cd /tmp
gunzip zlib-1.2.3-sol10-x86-local.gz
pkgadd -d zlib-1.2.3-sol10-x86-local

Note that a number of the packages have dependencies on other packages, which must be installed as well. Most of the packages are installed to /usr or /usr/local. Also, for the GD package, you have the option of either installing it separately or using the bundled GD package that comes with PHP. I simply used the bundled package.

Installing MySQL

The MySQL server software can also be downloaded as a package from Sunfreeware, but it requires some additional manipulation. The relevant additional instructions are placed in /usr/local/doc/mysql. They involve adding a new system user/group, adjusting permissions, running a script to set up the basic grant tables, and starting the server daemon. It is also necessary to configure default MySQL user accounts and secure the server properly. I am not documenting these procedures here; see the MySQL installation docs for more information. (Note: if you are using a MySQL package from a different source, or are compiling it manually, you must use a version that is compatible with the PHP distribution you are installing. For example, if you will be running a 32-bit installation of PHP, you must install a 32-bit version of MySQL, or else you will get errors. Note also that ’strict mode’ should remain turned off in the configuration file for MySQL to work with Moodle.)

Once MySQL is installed and running, it is necessary to create a new empty database for Moodle to use, and this database must be configured to use the utf8 character set. Using the command line MySQL client, I did this as follows:

cd /usr/local/mysql/bin
./mysql -u root -p
...
mysql> CREATE DATABASE moodle;
mysql> ALTER DATABASE moodle
    -> DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci;

It is also recommended to create a MySQL user account specifically for Moodle:

mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,CREATE TEMPORARY TABLES,
    -> DROP,INDEX,ALTER ON moodle.*
    -> TO moodleuser@localhost IDENTIFIED BY 'somepassword';
mysql> QUIT
...
./mysqladmin -u root -p reload
...

(Note the password above should be changed for an actual installation.)

Installing PHP

Once MySQL and all of the prerequisite packages were installed, I was able to begin the PHP installation. I downloaded php-5.2.5.tar.gz from the PHP web site to /tmp, and got the source files extracted:

cd /tmp
gunzip php-5.2.5.tar.gz
tar -xvf php-5.2.5.tar
cd php-5.2.5

I was now ready to run the included configure script to configure the PHP build. This step involves enabling the options and extensions mentioned above, specifying the install locations of any relevant dependencies, and also specifying any other parameters necessary for build.

The installation of PHP with the Sun Java System Web Server actually presents several options at this junction: PHP can be compiled as a regular CGI module, a FastCGI module, or an NSAPI module. Roughly, these options are in order from the simplest but least efficient to the more complicated but most efficient. I decided to take the middle ground and install PHP as a FastCGI module. (For more information on the different types of installations and their pros and cons, see Sun documentation.)

Below is the code I used to configure the build. (Note that it is necessary to export the install location of your C compiler to PATH, so that the configure script can make use of it. In my case, I was using the Sunfreeware gcc package. If you are using a different compiler, make the appropriate adjustments.)

PATH=/usr/local/bin:$PATH
export PATH

./configure --prefix=/usr/local \
  --enable-fastcgi \
  --enable-force-cgi-redirect \
  --enable-mbstring \
  --with-mysql=/usr/local/mysql \
  --with-gd \
  --with-png-dir=/usr \
  --with-jpeg-dir=/usr \
  --with-xpm-dir=/usr \
  --with-freetype-dir=/usr \
  --with-zlib=/usr/local \
  --with-curl=/usr/local \
  --with-openssl=/usr/local/ssl

(Note: if you are installing an older version of PHP, you may run into an error at this point stating that the ‘GD build test failed’. A closer inspection of the config.log file may reveal that the build test for GD failed because it was unable to locate necessary libiconv symbols. If this is the case, you may need to adjust environment variables manually or edit the configure script directly by adding -liconv wherever -lgd appears in a build. For more information, see this article.)

Once the configure script completed successfully, it was time to build and install PHP:

make
make install

This installed PHP in /usr/local. In particular, it installed /usr/local/bin/php-cgi, which was the FastCGI module.

To configure additional PHP options after it is installed, it is necessary to use a php.ini file. You can copy one of the distribution files into /usr/local/lib and then edit it, e.g.:

cp php.ini-recommended /usr/local/lib/php.ini

The following options should be set in php.ini for Moodle to work:

; The memory limit must be at least 16M
memory_limit = 128M
safe_mode = Off
file_uploads = 1
session.auto_start = 0
session.bug_compat_warn = 0
session.save_handler = files
magic_quotes_runtime = 0
; The following setting is recommended
magic_quotes_gpc = 1

Consult the PHP documentation for more information on php.ini.

Configuring Sun Web Server

Sun Java System Web Server 7.0 now needed to be configured to use my PHP FastCGI module. This involved editing a few different configuration files. First I navigated to the appropriate directory (note that the path below is specific to my setup, which was running on moodle.whardy.com):

cd /var/opt/SUNWwbsvr7/https-moodle.whardy.com/config

Then I enabled the FastCGI module by adding the following line to the file magnus.conf:

Init fn=load-modules shlib="libfastcgi.so"

Next I had to add a Service type directive to the file obj.conf, placing it inside the default object as follows:

<Object name="Default">

  Service type="magnus-internal/php"
          fn="responder-fastcgi"
          app-path="/usr/local/bin/php-cgi"
          bind-path="localhost:3101"
          app-env="PHPRC=/usr/local/lib"
          app-env="PHP_FCGI_CHILDREN=2"
          app-env="PHP_FCGI_MAX_REQUEST=200"
          app-env="FCGI_WEB_SERVER_ADDRS=127.0.0.1"
          app-env="LD_LIBRARY_PATH=/usr/local/lib/php"

  PathCheck fn="find-index"
            index-names="index.php,index.html,home.html,index.jsp"

  ...
</Object>

Note that the PathCheck directive above includes index.php. This allows the web server to run a PHP script (named index.php) as the default document in a directory. Note also that there are usually lots of other directives in the obj.conf file, which I am not displaying above for brevity.

Finally, I associated file extensions with the new type by adding a line to mime.types:

type=magnus-internal/php exts=php,php3,php4,php5

The web server needed to be restarted for the changes to take effect:

../bin/stopserv
../bin/startserv

Installing Moodle

At long last I was ready to install Moodle! Well, almost. First I needed to create a data directory outside of web root where Moodle would be able to store course documents, user pictures, and so on. I created it directly above the web root (note again the path below is specific to my server setup):

cd /var/opt/SUNWwbsvr7/https-moodle.whardy.com
mkdir moodledata
chmod -R 770 moodledata

Finally, I was able to run the web-based installer at http://moodle.whardy.com/install.php. Here I entered basic configuration parameters including database type/host/username/password/table, web root path, data directory path, etc. These parameters were all obtained from the installation steps above. After this, I accessed http://moodle.whardy.com/admin/ to complete the installation. (Note: the installation scripts provide status information during installation. If you run these scripts and encounter errors, consult the Moodle installation docs for information on the possible causes.)

Once these steps were complete, Moodle was ready to go! Or was it?

Slash Arguments

After setting up some test courses and adding documents to the courses, I noticed what seemed to be some bugginess in the displaying of uploaded files. When I would click on any links to access files, I would just get a page that said "No input file specified". In addition, none of my user pictures were showing up in my profile. All of this despite the fact that the files had been successfully uploaded into my moodledata folder.

After poking around, I realized that the URL’s for these resources in Moodle’s HTML output looked a little funky, coming out in the form:

http://moodle.whardy.com/file.php/1/mycourse/myfile.html

It turns out this is a feature, however, not a bug, in Moodle’s implementation. Moodle writes the URL’s in this way by default in order to improve caching performance for clients and proxy servers. It’s called the ’slasharguments’ feature, and while it means well, it unfortunately did not work well with my server setup.

Luckily there are ways around it! The simplest workaround is to just disable slasharguments. From the Moodle administrator, you go to Server -> HTTP, uncheck ‘Use slash arguments’, and click ‘Save Changes’. Easy enough. URL’s will then be written in the form:

http://moodle.whardy.com/file.php?file=/1/mycourse/myfile.html

But what if you like the caching benefits provided by the slash URL format? It is possible to keep the slashes when running Moodle on the Sun Java System Web Server; you just have to code silent URL rewriting into the web server configuration. This is done by first returning to the web server configuration files:

cd /var/opt/SUNWwbsvr7/https-moodle.whardy.com/config

Then you make the following addendum to obj.conf, again in the default object:

<Object name="Default">
 ...

 <If $uri =~ "^/file\\.php/(.*)$">
  NameTrans fn="restart" uri="/file.php?file=/$1"
 </If>

</Object>

Of course the web server must be restarted for the changes to take effect:

../bin/stopserv
../bin/startserv

And now Moodle should work fine even with slasharguments enabled.

To see our Moodle installation in action, visit www.SunStudentCourses.com

References

• Sun Solaris 10
• Sun Java System Web Server 7.0
• Sunfreeware
• Installing MySQL Server
• Installing PHP
• Using PHP on Sun Java System Web Server
• Installing Moodle
• MySQL 4, Apache 1.3 and PHP 4.3 on Solaris x86