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) Then uses the   helper function (described below) to render the revision.content

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

During development, a templates can be compiled as necessary.

TODO check that compiling in production is actively disabled.

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.

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

Currently all the Flow templates and styles are packaged in one RL module.

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?