Separate views from logic with a template engine

[tuxayo]

Motivations

Separate business logic from presentation logic/views to:

• work more easily when editing the views only (easily see what the HTML code will be)
• reliably implement logic without risking to break the view(example: https://github.com/Coral-erm/Coral/issues/73)
• reduce duplication and code necessary to generate the HTML
  • consistency across the whole app for the same components

We need a template engine because:

• doing it in pure PHP (no library) is hard (inheritance and reusable blocks) and require discipline to keep the logic out
• in the end we would build our own engine: see Plates and Foil for engines with a similar philosophy
• it's not possible to achieve the same level of readability with pure PHP. (one, maybe not representative example of a project where they have their own engine) see also Plates and Foil.

  Caveats/Disclaimer

I only have ~50 hours of experience with PHP and Coral so the following initial work is expected to contain, errors, biases and irrelevances about

• the chosen criteria
• the listed alternatives
• the chosen characteristics, pros and cons of the alternatives

That being said, any template engine will allow to make huge progress toward the goals listed in the Motivations section. So there is no choice that is inherently bad. (except never choosing)

And the work to switch from one engine to another should in any case be lower than the work to separate the views from the business logic (for which a template engine will help a lot).

So don't be afraid that we could take decisions that might have terrible future consequences for the development of Coral. That's a perk of the current situation, we will necessarily remove more technical debt than increasing it.

Choice criteria

• how far can it go to help us making Coral better
  • good, useful and comprehensive features → quality of result
• ease of implementation (cost)
  • bonus if long term Coral developers have experience with it
• long term sustainability: because it's better if there is no need to change it
  • will still be maintained for many years
  • bonus if long term Coral developers have experience and feel good with it because they will benefit the most from this choice

    Alternatives

    Twig

• comprehensive DSL
  • handle in a readable way all the view logic(conditions, loops)
  • share code between templates to reduce duplication (inheritance, reusable blocks)
  • syntax similar to other template languages like Django's and Jinja so learning the language can be even easier when already having experience with a template language.
• flexible: for example there is Twital, a plugin that changes the DSL to one closer to HTML which we might prefer compared to the default one.
• documentation said to be good
• future proof/will last many years as it's very popular and it's the template engine chosen by Symfony and Drupal 8
• easy to find help and resources online due to it's popularity
• seems to be more "polished" than Smarty which still carries some legacy
• seems to easier to integrate with bigger projects than Smarty
• I18n is straightforward as we can directly call to the I18n function in the template.

  Smarty

• DSL at bit less comprehensive than Twig but not sure if anything important is missing

  Plates

• no DSL → PHP with helper functions
  • heavier to write than a DSL, but less than pure PHP
  • less readable (more boilerplate code but less than pure PHP)
• inheritance
• reusable blocks
• needs discipline to keep logic and DB interactions out
• seem to lack some useful features of Twig²
• user base a bit small

  Foil

• no DSL → PHP with helper functions
• needs discipline to keep logic and DB interactions out
• fixes some of the criticisms made to Plates²
• user base really small
  • future proof concerns
  • finding help will be difficult

    Mustache

• logic-less templates: just send an array with the values to be replaced in the template
  • enforces separation of concerns as all logic must be out, no slippery slope that can lead to complex templates
  • simpler syntax to learn compared to classic engines but being forced to keep the logic out also adds it's own difficulties
  • still allows to achieve results like with conditions and loops
  • reusable blocks (partials)
  • inheritance
• possibly limited in some use cases but I can't figure out their relevancy³
• compared to classic engines like Twig, it seems that usually the logic-less nature of Mustache makes it harder to implement but on the long term, not being able to put logic in a template keeps them maintainable. ⁵
  • actually it could be easier to use when no template experience⁴
• I18n seems tricky but doable ⁶
• If we plan to someday send JSON to the client(browser) instead of HTML to let it do the rendering(or mutualize the work for making an API), then we could switch to Mustache.js at a low cost by reusing a great part of the templates.

  Rain TPL

• Dead project
  • http://raintpl.com/
  • https://rainphp.github.io/raintpl
  • https://github.com/feulf/raintpl/graphs/contributors
• finding help is difficult
• Might be too simple and limited for a big project like Coral

  Some of the references when searching the differences between the alternatives

[1] https://www.quora.com/What-are-the-pros-and-cons-of-Smarty-versus-Twig-php-web-templates

[2] http://gm.zoomlab.it/2015/template-engines-i-moved-from-love-to-meh-for-plates/

[3] Search for "as little logic as possible" in http://www.sitecrafting.com/blog/top-5-php-template-engines/

[4] Someone on the #php IRC: I'd say using Mustache makes writing maintainable templates easier for developers with no template experience, IF they understand why Mustache is limited

[5] Someone on #php IRC: Separation of concerns. also better IDE support (for refactoring, find usages etc) and using the tool better designed for expressing business logic: a programming language (and yes, IMO display logic like "show the profile as yellow if the subscription is about to end" is business logic too) and that's where discipline comes in it's getting harder and harder to decide what should be "in" and what should be "out"

[6] I18n with Mustache.php

• https://github.com/bobthecow/mustache.php/blob/master/test/fixtures/examples/i18n/I18n.php
• https://github.com/bobthecow/mustache.php/issues/291#issuecomment-209967350
• https://stackoverflow.com/questions/8695970/mustache-i18n-with-parameters

  Conclusions

If I didn't missed something huge then the choice would be between Twig and Mustache.

To make the final choice I think if one or some of the Coral developers have experience with one of the two then it will make the difference. It will weight more in the balance than the difference found between Twig and Mustache (especially with the Caveats that alone create an error margin where the difference between Twig and Mustache fits)

So this is where we need feedback from those of us that already worked with template engines.

[jsavell]

I think a template engine is a secondary concern to adopting a true MVC pattern for the codebase. That would properly separate our data, logic, and presentation layers.

Shoehorning a template layer in now would only serve to make it more difficult to correct the overall codebase, later.

[tuxayo]

Shoehorning a template layer in now would only serve to make it more difficult to correct the overall codebase

Why? It would be just a tool to help separating the views and this could be the first step towards #80

[jsavell]

Without a clear definition of the MVC pattern goals and requirements, we'll just end up with a different set of problems to solve when we try to implement a MVC pattern.

The MVC pattern should be implemented in such a way that supporting a new view renderer is just a matter of implementing an interface. At that point, we'll be able to render CORAL views in HTML or JSON or XML with a few lines of code in a single class file and a configuration change.

We'll be able to support theming and skinning, easily.

We'll be able to drop in new template engines without entrenching them into the CORAL code and with significantly less commitment.

If we start integrating a specific template engine into CORAL without all that in place, we're likely to end up with a new dependency, tightly coupled between our controllers and views, which we'll then have to untangle and reimplement when we settle on the MVC design pattern.

That being said, https://github.com/Coral-erm/Coral/issues/80 wasn't opened at the time I made my comment, so if bringing in a template engine is done in the context of that Issue having well defined goals and requirements, then my concerns will have been addressed.

[tuxayo]

The MVC pattern should be implemented in such a way that supporting a new view renderer is just a matter of implementing an interface. At that point, we'll be able to render CORAL views in HTML or JSON or XML with a few lines of code in a single class file and a configuration change.

If I understand correctly we should use an intermediary layer (the view) to which the controller would pass the data to render. And the view would pass it to the appropriate renderer. (HTML template engine or JSON generator) So the actual calls to the template engine would not be scattered a over the controllers.

If we start integrating a specific template engine into CORAL without all that in place, we're likely to end up with a new dependency, tightly coupled between our controllers and views, which we'll then have to untangle and reimplement when we settle on the MVC design pattern.

We would pass the values to a template, is that such a high coupling? Would the intermediary layer proposed above be enough?

[tuxayo]

Updated first post with I18n consideration for Twig and Mustache

[jsavell]

It's the difference between our controllers being filled with lines like this:

$this->site->getViewRenderer()->registerViewVariable("widget",$widget); $this->setViewName('widgets.parts');

Or lines like this: $template = $twig->loadTemplate('widgets.parts.html'); echo $template->render(array('widget' => $widget));

In the first example, if we need to change ViewRenderers, or support more than one simultaneously (Twig,JSON, and XML, for example), it's no big deal. We just teach the $site class to instantiate the correct ViewRenderer implementation through Configuration settings or request parameters, long before the controller is even invoked: $site->setViewRenderer(new TwigViewRenderer()); or $site->setViewRenderer(new JSONViewRenderer()); $site->setViewRenderer(new XMLViewRenderer());

Nothing has to change in the controllers. They don't even know about it.

In the second example, though, our controllers know all about Twig. That's all they know how to do. If we want to change template engines, we have a lot of work to do in a lot of controllers. And we can't support XML or JSON globally. We have to fill our controllers with conditionals to test for when we should bypass Twig.

None of that is a knock on Twig. It was just an example to demonstrate the implementation concerns.

[tuxayo]

I see, the dependency injection would also allow to test only the controller or only the view, which is nice.

Would your proposed interface be enough or are there more things that need to be defined?

Also, as you posted a small example with Twig, does this mean that you have at least some experience with it?

[tuxayo]

Updated first post with possibility with Mustache to switch to client side rendering in the future.