Per https://scuttle.atlassian.net/browse/WDBUGS-129, the current templating system is not effective and should be improved. In this document we’ll describe Wikidot’s templating system, what we want the new templating system to achieve, and how we’ll go about implementing it.

The old system

A template is a framework that is applied to all pages in a given category. There are two kinds: the default, which results in a form consisting of fields title and content; and “data form”, which allows the template to be created with a “form” (both structure-wise and interface-wise) that defines what fields will be available. The template also defines what of those fields is shown on the page: for the default mode, this is simply the content of the page; and this can be customised for data form mode.

The new system

In the new system, the templates should not be arbitrarily divided into these two categories which are effectively the same. The default - and only - mode should be “data form” mode. The template page should define any number of fields which will determine what data the pages in a category can be created with. Additionally, on creation of a new category (including _default on the creation of a new wiki), a default template should be created that provides fields for title and content. This unifies the two modes into one.

Defining templates

Templates as a page

The old system uses a dedicated template page to store both the output (i.e. the placeholders that will compose the rendered page by substituting its data) and the input (i.e. the structure of the form and therefore the fields that make up the page). The following is a truncated version of the now-deleted Log of Unexplained Locations template by AJMansfield:

Template pages were made of two sections, separated by ====, with the first being the content substitution and the second creating the data form.

Templates as a page are probably the easiest to implement as they don’t require any special rendering. It’s also convenient to have both the rendering section and the parsing section in the same place. The problem lies in the flexibility of plaintext entry: it’s very easy to fuck it up. Depending on how page content is stored internally, a syntax error could result in data being lost.

Templates as a form

Instead of being presented as a free text-entry interface, template creation could be presented as a form.

Meta-templates

Like how templated pages are edited via a form, editing templates via a form implies the existence of a meta-template that defines the fields for a given template.

For example, the following meta-template could produce the following-following template, which could produce the following-following-following page creation form:

Open

Note that in order for that to be possible I’ve had to add both a types and array system to templates, both of which are vast increases in complexity that need to be discussed and make this a pretty poor example. Also note that while the intent of the meta-template is to allow for form-based templating instead of text-based, the meta-template is itself text-based. This is because adding another level of form templating requires a further level of form templating behind it, and so on - you must eventually end up at a text-based template.

It occurs to me that this extra layer is probably made null and void by the assumption that users who are fiddling with templates are likely powerusers who know exactly what they’re doing and are capable of reading documentation. In fact they’d probably prefer to disable the form-based interface altogether and just edit the configuration file that it’s wrapping directly.

Also, rendering templates as a form and therefore creating a meta-template introduces another level of implementation and documentation that we, the developers, need to make sure is consistent throughout the entire codebase and documentation, and that sounds like an entire ass.