mod_annot editor

Annotate Section

The Editor

The editor supports two handlers: editing or annotating a section. Each operation has two parts: displaying a Form, and submitting the Form to commit the update.

This is not considered so performance-critical ad displaying an article, as it is likely to be a relatively infrequent (and non-cacheable) operation. Nevertheless, it is implemented as a module mod_annot. But mod_annot does allow itself the overhead of parsing the document to a DOM and using XPATH expressions to check document metadata and extract the section we are working on. If a document is not well-formed, the parse will fail and an HTTP Error 500 will be returned.

On all requests, mod_annot first checks that the user is authorised for the attempted operation and that the document is not locked against any update. If this check fails an HTTP 401 or 503 error response will be returned as appropriate.

After these checks, one of two things happen. If the request was an HTTP GET, it will display an editor form. If the request was a POST, it will submit the form, making the update.

In either case, the next operation is to extract the section we are working on from the DOM. This relies on the user submitting valid inputs to the editor: if the inputs are not acceptable to the system (i.e. if someone is trying to tamper with it), it will return an HTTP 400 error. If the section cannot be extracted despite well-formed inputs, it will return an HTTP 500 error: this could happen either on a tamper attempt or because the section was updated between loading a page and selecting the editor operation.

Either the annotation or edit forms are displayed within a general page template. The annotation form displays the section with an empty text box to enter the user's comment, while the edit form displays the section title and the section contents (markup) in form fields to be edited.

Submitting either of the forms causes an update to the document. So in the case of a POST operation, the editor will take an exclusive lock to prevent a race condition. It will also check the section timestamp to ensure that the section is still the same as what the user is working on, and hasn't been updated by someone else in the meantime, returning an HTTP 409 error on failure.

An Annotation operation will insert a new annot node in the section, escaping any markup to plain text.

An Edit operation will first validate the markup, returning an HTTP 422 error on failure (if no section DTD is supplied, it would merely check well-formedness). If successful, it will replace the section title and contents in the DOM with the new values entered, together with the timestamp and editor id.

The DOM will then be saved to a new file, and moved atomically to the filename used to display the document. Finally, an internal redirect returns the updated document to the user.