Template Lookup

The discovery of templates is handled by Mako, and is configurable.

WuttaWeb comes with all templates it needs, in the path designated as wuttaweb:templates.

When the app renders a page, it invokes the Mako lookup logic, which searches one or more folders and returns the first matching file it encounters. By default wuttaweb:templates is the only place it looks.

A template is searched for by “name” but it is more path-like, e.g. /page.mako or /master/index.mako etc. So for example the file at wuttaweb:templates/home.mako is used for home page (using lookup name /home.mako) by default.

Overriding the Search Paths

The basic idea is to give it a list of paths it should search when trying to find a template. The first template file found for a given search name is used and no further search is done for that name.

You can define the Mako lookup sequence in your web.conf as follows:

[app:main]
mako.directories =
    /random/path/on/disk
    poser.web:templates
    wuttaweb:templates

This setting is interpreted by pyramid_mako (docs).

Here wuttaweb:templates/home.mako would still be used by default for home page, unless e.g. /random/path/on/disk/home.mako existed in which case that would be used.

Each path can have an arbitrary set of templates, they will effectively be combined to a single set by the app, with the definition order determining search priority.

If you are already using a custom app.main() function for constructing the web app during startup, it may be a good idea to change the default search paths to include your package.

Setup for custom app.main() is beyond the scope here, but assuming you do already have one, this is what it looks like:

from wuttaweb import app as base

def main(global_config, **settings):

    # nb. set the *default* mako search paths; however config can
    # still override with method shown above
    settings.setdefault('mako.directories', ['poser.web:templates',
                                             'wuttaweb:templates'])

    return base.main(global_config, **settings)