Flow/Architecture/Templating

The Flow/Epic Front-End rewrite of April 2014 uses Handlebars to render in JavaScript, and the lightncandy PHP implementation. This allows templates to be shared between front-end and back-end.

MediaWiki is in the middle of Requests for comment/HTML templating library, but the Flow team couldnt wait.

Using
The templates are in the handlebars subdirectory.

For example, :

This
 * 1) sets the scope to the 'revision' key of the API response.
 * 2) outputs some HTML
 * 3) uses handlebars' limited logic to conditionally output a class if the key   is true in this scope
 * 4) sets the scope to the 'author' key within 'revision', in preparation of outputting the usual MediaWiki Username (talk | contribs) HTML.
 * 5) outputs the value of various bits within the response.revision.author structure.
 * 6) Uses the   helper function to output some message strings.
 * 7) Then uses the   helper function (described below) to render the revision.content.

General template structure
In handlebars templates:
 * includes in another template
 * outputs the string value of some key in the current "this" scope
 * inside the curly braces eats whitespace, thus eats all whitespace before the   and   eats all trailing whitespace.
 * invokes a block function, like  above. Flow has its own block helper function, like
 * invokes a block function, like  above. Flow has its own block helper function, like

In general one main template includes other templates, often in #if or #each or #eachPost blocks.

PHP
We compile the templates into PHP in advance by make compile-lightncandy, and we check the compiled templates into git.

On your development server, set a variable to compile templates as needed (you may have to change permissions on handlebars/compiled.

JavaScript
The API response is in JSON.

We use a ResourceLoader add-on in extension:Mantle allowing us to specify "resource blobs". This makes the template available to front-end. See that extension's page for some documentation.

TODO compile JS templates in advance? Use ResourceLoader to do this?

Helper functions
Handlebars helper functions have to be re-implemented in JavaScript (in ) and PHP in order for a template to work both front-end and back-end.

E.g. invokes the   helper function to render HTML (rather than escaping '<' and '>', etc.).

Another example, the template code invokes the  helper to get the timestamp from the UUID   and format it using the 'time_ago' i18n message.

Debugging
Comment out a line in View.php to view the JSON output before it's templated.

Best practices
Handlebars has implicit triple-braces to output pre-computed HTML. This is easy to miss, so invoke an explicit  when we want to output HTML

TODO: have a flag to disable this?