Overview¶

Extensions are a way to enhance a program’s feature set through pluggable third-party modules. This works much like browser extensions, but for your own program.

This guide will go over some of the basics of an extension, to help you write your own.

Extension Subclasses¶

All extensions must be subclasses of Extension. Note that the application you’re writing an extension for may have their own class you must subclass instead (for example, Review Board uses reviewboard.extensions.base.Extension), so consult their documentation.

Configuration¶

If an extension supports configuration in the UI, it should set Extension.is_configurable to True.

If an extension would like to specify defaults for the settings dictionary it should provide a dictionary in Extension.default_settings.

If an extension would like a django admin site for modifying the database, it should set Extension.has_admin_site to True.

Static Media¶

Extensions should list all other extension names that they require in Extension.requirements.

Extensions can define static media bundle for Less/CSS and JavaScript files, which will automatically be compiled, minified, combined, and packaged. An Extension class can define Extension.css_bundles and Extension.js_bundles. Each is a dictionary mapping bundle names to bundle dictionary. These mostly follow the Django Pipeline bundle format.

For example:

class MyExtension(Extension):
    css_bundles = {
        'default': {
            'source_filenames': ['css/default.css'],
            'output_filename': 'css/default.min.css',
        },
    }

source_filenames is a list of files within the extension module’s static/ directory that should be bundled together. When testing against a developer install with DEBUG = True, these files will be individually loaded on the page. However, in a production install, with a properly installed extension package, the compiled bundle file will be loaded instead, offering a file size and download savings.

output_filename is optional. If not specified, the bundle name will be used as a base for the filename.

A bundle name of default is special. It will be loaded automatically on any page supporting extensions (provided the load_extensions_js and load_extensions_css template tags are used).

Bundles can also specify an optional apply_to field, which is a list of URL names for pages that the bundle should be automatically loaded on. This works like the default bundle, but for those specific pages.

Bundles can also be loaded manually within a TemplateHook template by using {% ext_css_bundle extension "bundle-name" %} or {% ext_js_bundle extension "bundle-name" %}.

JavaScript extensions¶

An Extension subclass can define one or more JavaScript extension classes, which may apply across all pages or only a subset of them.

Each is defined as a JSExtension subclass, and listed in Extension’s Extension.js_extensions list. See the documentation on JSExtension for more information.

Any page using the init_js_extensions template tag will automatically initialize any JavaScript extensions appropriate for that page, passing the server-stored settings.

Middleware¶

If an extension has any middleware, it should set Extension.middleware to a list of class names. This extension’s middleware will be loaded after any middleware belonging to any extensions in the Extension.requirements list.

Template Context Processors¶

Extensions may need to provide additional context variables to templates. This can usually be accomplished through a TemplateHook, but sometimes it’s necessary to provide context variables for other pages (such as those controlled by a third-party module).

To add additional context processors, set Extension.context_processors to a list of class names. They will be added to settings.TEMPLATE_CONTEXT_PROCESSORS automatically.