allura.lib.package_path_loader

A Jinja template loader which allows for:

• dotted-notation package loading

• search-path-based overriding of same

Dotted notation

• Allow a Tool implementer to use a dotted-notation module name (as occuring in the PYTHONPATH), then the given path within the module:

  @expose('jinja:<module.name>:<path/within/module.html>')
  

  e.g.:

  @expose('jinja:allura:templates/repo/file.html')
  

Overriding dotted notation

Allow a Tool implementer to override the theme baseline (or any other Tool’s) templates. This can be lighter-weight than subclassing allura.plugin.ThemeProvider, plus will allow for more fine-grained changes.

This will also override extends and import Jinja tags.

This approach uses a:

• setup.py entry point to a class with…

• magic files and…

• (optionally) a class property to specify ordering

File Structure for Overriding dotted notation

For the examples, assume the following directory structure:

NewTool/
|- setup.py                     <- entry point specified here
|- newtool/
   |- app.py                    <- entry point target here
   |- templates/
   |  |- index.html             <- Tool's regular templates
   |- override                  <- override_root
      |- allura/                <- magic directory named after module
         |- templates/
            |- repo/
               |- file.html     <- actual template

To override the above example, a Tool implementer would add the following line to their Tool’s setup.py (assuming usage in Allura, with the default app_cfg):

[allura.theme.override]
newtool = newtool.app:NewToolApp

Then, in the neighbor path (see below) for the file containing the Tool class, add the following path/file:

override/allura/templates/repo/file.html

The template will be overridden. Note that after changing setup.py, it would be required to re-initialize with setuptools:

python setup.py develop

Specifying search path order with template_path_rules

If a highly specific ordering is required, such as if multiple Tools are trying to override the same template, the entry point target class can also contain a class property template_path_rules:

class NewToolApp(Application):
    template_path_rules = [
        ['>', 'old-tool'],
    ]

Each rule specifies a postioner and an entry point or “signpost”. If no rule is provided, the default is ['>', 'allura'].

The “signposts” are:

• Any other app’s override entry point name

• site-theme

• allura (you probably shouldn’t do this)

• project-theme NOT IMPLEMENTED

• tool-theme NOT IMPLEMENTED

The positioners are:

>

This overrider will be found BEFORE the specified entry point

<

This overrider will be found AFTER the specified entry point

=

This will replace one of the “signpost” entry points (if multiple apps try to do this for the same signpost, the result is undefined)

TODO: Support multiple partial themes

class allura.lib.package_path_loader.PackagePathLoader(override_entrypoint='allura.theme.override', default_paths=None, override_root='override')

get_source(environment, template)

Returns the source for jinja2 rendered templates. Can understand… - path/to/template.html - module:path/to/template.html

init_paths()

Set up the setuptools entry point-based paths.