Theming Sites

Defining custom colors for the ashes theme.
Defining templates to override sections of themes.
1. Mention overriding the internal parser, too.
Defining your own themes.

Defining your own Templates

Templates are the basis of themes. They define which HTML (or other) code to be generated by supplying partial code with holes that must be filled in. Templating for foonoo is provided by the honam template engine that ships with the ntentan framework. Honam provides a hierarchical template resolution system where a given hierarchy of paths is searched in its order when searching for templates to render HTML files.

The template hierarchy for resolving any foonoo template is somewhat fixed, and it's defined as follows in decreasing order of search priority:

Templates in the _foonoo/templates directory are searched and applied first. These templates will typically be supplied by the person building the site, and they carry the highest priority to override any other templates.
Next templates in special template paths supplied through the templates configuration of the site.yml file are searched. These templates can also be supplied by the site designer, and they are useful when you want to add your own templates outside the _foonoo directory.
Afterwards, templates from the current active theme are searched. These templates are supplied by theme designers and are part of the current theme in use. Most template requests are expected to resolve here.
Finally, the last place searched contains the built in templates for foonoo's tag parser. These templates are built into foonoo and they are meant to provide the templates for the HTML code generated by the tag parser (for things like links and images).

So, now that we know how to find templates, how do we override them? Well, it's quite simple: the actual templates available at any time are mainly defined by the active theme and foonoo's tag parser. To override those, you best option will be to create your own templates and place them in the _foonoo/templates directory.

Overriding the Layout wrapper for the default theme

As an example, let's override the layout of the Ashes theme. To do this, you could create a layout.tplphp file and place it into the _foonoo/templates directory. This template is required by Ashes to wrap all rendered content. A PHP variable named $body, which contains the rendered HTML for any content, is exposed to the layout. You can put the following code into the layout.tplphp file:

<html>
    <head><title>Some Title Site!</title></head>
    <body>
        <h1>Some Title Site</h1>
        <hr/>
        <?= $body ?>
    </body>
</html>

Now, if you go ahead and place this layout.tplphp file into the _foonoo/templates directory of our earlier example, you should have the following output:

Neat! Right? Well, if you look carefully you should realize a big problem. Compared to the earlier example, this output is devoid of any styling, and rightfully so, because all the styling is supplied by Ashes whose template we just overrode. But even more prominently, you should notice that only the raw HTML code was output. This is because the HTML code for the content has been escaped by the template engine. To fix this escaping, you can go ahead and use the following layout code, which has the content unescaped by changing $body to $body->u().

<html>
    <head><title>Some Title Site!</title></head>
    <body>
        <h1>Some Title Site</h1>
        <hr/>
        <?= $body->u() ?>
    </body>
</html>

And this should now be properly rendered as:

A properly rendered output from the custom template

We just overrode the layout! The default site builder has several other templates we can override. Heck, we can also define our own templates to be used within our overridden template. The possibilities for extending the look of your foonoo sites are endless.

TODO

[ ] Don't forget to add references here to overriding templates for the tag parser.