Editing your web site with Jigsaw

This tutorial is devoted to collaborative editing of your web site through Jigsaw. The tools described here are still undergoing test, but as of today, it has been used to edit entirely Jigsaw's documentation.

The basic guideline for that project is to avoid reinventing the weel, by reusing an existing revision control system, namely cvs. The set of resources described here act as a front end to that tool, and assume a particular organization of your web site.

Before reading further, you should be familiar with:

cvs

GNU's Revision Control System.

Jigsaw admin

The configuration process of Jigsaw. You should at least have a good understanding of the configuration tutorial.

The basic model

As we rely as much as possible on CVS, this first section explains how your website has to be organized in order to support Jigsaw's editing capabilities.

The idea is for the server space (ie documents served by the server) to be one "local" cvs space, corresponding to the state of the CVS repository at publish time. Each user that has authoring access to the site also has its own "local" space, following CVS conventions. A typicall setting would be for example:

/usr/local/jigsaw/WWW

To be a checkeout module of CVS, used by the server to serve documents

~fred/WWW

The "local" CVS space of user fred.

~joe/WWW

The "local" CVS space of user joe.

Two instances of Jigsaw are run: one for editing each user's local space - we will call it JigEdit in the rest of that document, and the main "public" one for serving the server space. The rest of this documents describe the tools to be used on JigEdit (the public server is just a normal server, it can even not be Jigsaw).

The tools described here provide a mean for each user to keep track of the documents he/she has edited, to publish them to the public server (by cvs updating it's space), and to run any CVS command through a form based interface.

Setting up JigEdit

Jigsaw comes with three tools to support collaborative editing:

A CVS front end (w3c.jigsaw.cvs.CvsDirectoryResource)

A single resource, that provides a full featured form based CVS interface

A AutoLookupDirectory (w3c.jigsaw.cvs.AutoLookupDirectory)

That will checkout on-the-fly appropriate directories in particular user's space.

The PutFilter (w3c.jigsaw.filters.PutFilter)

That will keep track of the documents edited by one user, but which have not yet been published.

When working in conjunction, these resources and filters provide a way for each user to edit its own copy of the web site, and to publish (potentially later on) a set of ready-for-delivery documents.

To set JigEdit up, the first step is to create a directory template, mapping all CVS directories to the CvsDirectoryResource. To do this, go to /Admin/Directories, and create a non-generic directory template for directories named CVS; map them to the w3c.jigsaw.cvs.CvsDirectoryResource class.

Once this is done, you need to register authoring users to JigEdit. To do so, you must first export their local space to JigEdit, the best way is to use a w3c.jigsaw.resources.PassDirectory resource.

Then for each user, create an instance of the PutListResource (w3c.jigsaw.filters.PutListResource) to keep track of their edits. This resource is fed by the PutList filter (w3c.jigsaw.filters.PutFilter), that you should plug on each user's top resource. The PutFilter communicates with the PutListResource, by getting its URL from the put-list attribute (which should provide the absolute path of the PutListResource that handles that user's put list).