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.