Advanced Usage¶
Theme Inheritance¶
Themes can stack on top of another theme by subclassing them.
Templates¶
An inheriting theme’s templates will layer on top of the superclass theme’s templates. The renderer will attempt to resolve templates to the child-most class first, then traverse up the inheritance chain.
Inside a template, you can refer to files with the prefix super: to make the filename resolve in the theme that is being inherited from.
Image Filters¶
An inheriting theme’s image filters will layer on top of the superclass theme’s image filters. If an image filter of the same name is specified, the child class will override the superclass.
Assets¶
An inheriting theme’s asset entry points will layer on top of the super class theme’s entry points. If an entry point of the same name is specified, the child class will override the superclass.
Static Files¶
Each theme has exactly one static file directory. It will be served up at an underscore-prefixed path corresponding to the theme’s key.
Asset Compilation¶
The assets dict attribute maps entry point names to a tuple of URL paths and asset type.
In development, simply call request.asset_tag(key) to generate an asset tag.
In production, assets must be compiled before that call. The asset compilation step does the following for each entry point in each theme:
- Resolve the entry point path to a filesystem path.
- Collect static dirs from the theme and superclasses for use in resolving references during the compilation process.
- Compile the asset by calling a Compiler instance with the theme and the asset entry point.
- Save the result to a file in pyramid_frontend.compiled_asset_dir with a filename based on the sha1 of the contents. - Collect all filenames for compiled files, mapping entry point name to filename.
- Write the filename to a file with a path like <compiled asset dir>/<theme key>/<entry point>.map.
For normal usage, you can compile assets simply with:
$ pcompile production.ini
Other options which can be useful are:
$ pcompile --no-minify production.ini
Print debugging output:
$ pcompile -vv production.ini
It’s also possible to programmatically call the asset compilation step (for example, for embedding in other deployment tools), with the compile() function.
- pyramid_frontend.compile.compile(registry, minify=True)[source]
Compile static assets for all themes which are registered in registry.