Notes on Templating

Introduction

This document was turned into a document from some notes by WilliamC. These notes where the basis for TimJ's abstraction of the templating engine and most of the points in this note have been addressed.

Melati and templates

Melati is an open source, Java-based infrastructure for the rapid and convenient development of web-based database applications. This guide describes how to write Webmacro templates which exploit Melati's facilities for automatic rendering of displays and forms for database fields and records.

Markup language support

This is what the *MarkupLanguage classes do:

Text escaping

Escaping ("rendering") of text according to the conventions of the language. In fact there are several different kinds of escaping to be done in HTML, depending on the context:

Doc body, attribute value "
Javascript value\042
URL=22

Exception rendering

Rendering of exceptions for display to the user, where the VariableExceptionHandler returns them to be displayed rather than simply throwing them out to terminate expansion. Again, this is context-dependent:

Doc body <I>error!</I>
Attribute value (e.g. input box content) [error!]

As of 21/07/2000, the representation of the exception is determined from a sub-template or "templet". The MarkupLanguage tries to load a WebMacro template (through the servlet's Broker) from a directory named after the markup language. The filename of the template is taken at first to be the package-qualified class name of the exception with .wm appended; if that doesn't exist, it tries the superclass, and so on until it finds java.lang.Exception.wm, which just does

[$ml.rendered($exception.toString())]

The templet is expanded to a string against a specially constructed Context, and the string is returned to WebMacro for interpolation into the parent template. It would obviously be nice if the templet could be expanded directly to the output stream, so that the extra buffering could be avoided.

Smart field handling

Field rendering

Rendering of POEM Fields, i.e. values wrapped up with PoemTypes, for display. (N.B. do we need a PoemTypedValue which is like a Field but doesn't have a name? The name isn't needed here, only for rendering input controls.)

The functionality is: compute the field's localised ‘cooked string’ representation; size-limit it; escape it for the doc-body context.

Persistent rendering

Rendering of POEM Persistents, which just means calling up their localised displayString and rendering that in the doc-body context.

Input control rendering

Rendering of an input box, dropdown, etc. appropriate for entering the value of a POEM Field. This has always used a ‘templet’ mechanism similar to that used for exceptions: a markup language-specific directory is searched for a templet named after the PoemType of the field, except that the templet name can also be set explicitly in the field's getRenderInfo property (ultimately, in the admin interface).

The name of the field is prefixed with field_ (the prefixing is done in each templet individually, which doesn't seem right). When the returning form is interpreted, Melati.extractFields knows to put that prefix on the field names of the Persistent into which things are going.

General observations

Desirable features for cleaner version

Note all of these suggestions have been implemented.

The idea of making ‘Melati’ essentially a utility object ($melati) accessible within templates still seems a good one. However,

Generalising from that last point,


About this document

Readership and purpose

This document is also intended to give the wider open source community an insight into Melati, so that they can give us feedback pre-release and evaluate the finished product in an informed manner.

History

The CVS log for this document is:

$Log: Templating.html,v $
Revision 1.1 2005/11/21 22:01:49 timp
Moved from site/doc

Revision 1.9 2003/07/11 23:47:41 timp
remove a few broken links

Revision 1.8 2003/04/15 02:26:39 jimw
Largely cosmetic fixes

Revision 1.7 2002/12/13 01:12:06 timp
Auto save prior to moving