Template engines

Micro provides a means for plugging in a variety of template engines. This flexible system allows Designers to use the view Template engine of choice and even mixing them in the same rendering process. Imagine having the power of Velocity and Freemarker for accessing objects while for simple stuff such as: "Term and Conditions", "About us", "Contact", etc., you could bring in the versatility of Markdown. All these are possible in Micro.

By default Micro currently uses the Velocity template language as the default template engine. You can control the template engines by modifying the micro-config.yml file, excerpt:

template_engines:
  - engine:
      name: velocity
      class: ca.simplegames.micro.viewers.velocity.VelocityViewRenderer
      options:
        resource_cache_enabled: true
        resource_cache_interval: 15
        global_macro_library: global_library.vm
      default: true

All the engines above are provided out-of-the-box with Micro but you can implement your own template engine, if you wish. We will highly appreciate your contribution to this project and looking forward for your pull requests.

Velocity

The Velocity view renderer uses the Velocity template engine from the Jakarta project.

If you want to learn more about Velocity you can visit the following links:

or:
- the Velocity developer guide

Markdown

Markdown to quote the author, is:

... a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

The Markdown implementation in Micro is a simple and efficient view renderer. Since this implementation is not allowing the interpolation of dynamic objects, Micro allows you to chain pre-processed Velocity or FreeMarker templates with pages using the Markdown syntax, obtaining an efficient method to merge complex content while using a minimal formatting syntax.

To enable the Markdown support in Micro, add the following configuration in your micro-config.yml file:

- engine:
    name: markdown
    class: ca.simplegames.micro.viewers.markup.MarkupViewRenderer

The Markdown implementation from Micro is based on two very nice libraries: prgdown and parboiled. With pegdown the following extensions are supported over the standard Markdown:

  • SMARTS: Beautifies apostrophes, ellipses ("..." and ". . .") and dashes ("--" and "---")
  • QUOTES: Beautifies single quotes, double quotes and double angle quotes (« and »)
  • SMARTYPANTS: Convenience extension enabling both, SMARTS and QUOTES, at once.
  • ABBREVIATIONS: Abbreviations in the way of PHP Markdown Extra.
  • HARDWRAPS: Alternative handling of newlines, see Github-flavoured-Markdown
  • AUTOLINKS: Plain (undelimited) autolinks the way Github-flavoured-Markdown implements them.
  • TABLES: Tables similar to MultiMarkdown (which is in turn like the PHP Markdown Extra tables, but with colspan support).
  • DEFINITION LISTS: Definition lists in the way of PHP Markdown Extra.
  • FENCED CODE BLOCKS: Fenced Code Blocks in the way of PHP Markdown Extra or Github-flavoured-Markdown.
  • HTML BLOCK SUPPRESSION: Suppresses the output of HTML blocks.
  • INLINE HTML SUPPRESSION: Suppresses the output of inline HTML elements.
  • WIKILINKS: Support [[Wiki-style links]] with a customizable URL rendering logic.

(content above was extracted from source).

Learn more about Markdown:

FreeMarker

<FreeMarker> engine provides a larger set of features when compared to Velocity and therefore may be a desirable alternative to Velocity.

To enable FreeMarker in a Micro application, add the following configuration in your micro-config.yml file:

- engine:
    name: freemarker
    class: ca.simplegames.micro.viewers.freemarker.FreemarkerViewRenderer

Learn more about the FreeMarker engine:

Mustache

Used at Twitter for their web site, email, syndicated widgets, etc., the Mustache(.java) is a derivative of mustache.js

You can use the Mustache templates with Micro via the Mustache extension. To install it, please follow the simple steps described in this README file.

The extensions folder will contain at least the following:

extensions/
  ├── mustache/ 
  ├── mustache.yml
  └── ...

And this is the mustache.yml extension configuration file will contain the following:

class: ca.simplegames.micro.extensions.MustacheExtension
engine:
  name: mustache
  class: ca.simplegames.micro.viewers.mustache.MustacheViewRenderer
  options:
    cache: views 
    #      ^^^^^ the name of the cache used for the compiled mustaches.

Where you can specify the cache name to be used for the compiled templates. A very basic setup.

Visit Mustache to learn more about this template engine.

StringTemplate

StringTemplate is a java template engine (with ports for C#, Python) for generating source code, web pages, emails, or any other formatted text output. StringTemplate is particularly good at code generators, multiple site skins, and internationalization/localization.

source: http://www.stringtemplate.org/

Micro supports the StringTemplate engine through a recent extension; the ST, respectively.

Installing and using the StringTemplate extension

Copy (or create symbolic links) the st folder and st.yml file to your application extensions folder. The extensions folder will contain at least the following:

extensions/
  ├── st/ 
  ├── st.yml
  └── ...

The st.yml may contain various configuration options for the StringTemplate engine. Example of a config file switching the StringTemplate expression delimiters from the default: < and >, to: $ and $:

class: ca.simplegames.micro.extensions.STExtension
engine:
  name: st
  class: ca.simplegames.micro.viewers.st.STViewRenderer
  options:
    delimiters: "$$"

See this link for more details.

Edit the application.bsh startup controller and require the st extension, example:

site.ExtensionsManager
    .require("i18N")
    .require("st"); // <-- just added

That's all. The StringTemplate engine will be automatically configured by this extension and made available to the entire application.

Restart the app and use your StringTemplate views.

Building Your Own

To build your own Template engine you must implement the ca.simplegames.micro.viewers.ViewRenderer interface. Take a look at the available implementations to have an idea about how it is done. Please send us a pull request, if you would like your implementation to be included in the Micro default distribution.

Heads up!

ViewRenderer implementations should strive to make use of caching mechanisms provided by their respective template engines or use the cache support form Micro. 

This will avoid unnecessary parsing and it will boost the site performance.
Fork me on GitHub