Template Plugins

Introduction

Plugins for templates are Python modules (or packages) which are hooked into the request cycle and can thus extend the current template configuration.

Those modules can be developed independently of Sahana, and are installed by simply placing them into the modules/plugins folder.

Installation

• tbw

Implementation

A template plugin can be a Python module or a Python package. The name of the module/package becomes the plugin name.

It must expose a function setup():

• setup() takes no arguments, and returns nothing
• setup() will be called during every request cycle (so minimize the load!)
• setup() will be called immediately before the controller is executed

# Example plugin

__version__ = "0.0.0"

def setup():

    # The plugin can access and alter deployment settings
    settings = current.deployment_settings

The plugin module/package can additionally define a __version__ string, which becomes accessible via current.session:

# The session holds the registry of current plugins
registry = current.session.s3.plugins

# The registry is a dict of tuples {plugin_name: (version, status)}
plugin_info = registry.get(plugin_name)

# - version is the __version__ string defined by the plugin or "unknown"
# - status is True if the plugin's setup function was successful, otherwise False
if plugin_info:
    version, status = plugin_info
else:
    # Plugin has not been loaded yet
    version, status = None, None

Notes:

• plugins should raise an exception in case of unrecoverable errors during setup, in order to deactivate themselves
• plugins are responsible to log all their errors themselves, using current.log
• a plugin's setup() must not redirect or otherwise raise HTTP30x (that would give an indefinite redirection loop)
• there is no particular order in which plugins are run - plugins with conflicts should auto-detect each other (via registry), log the problem, and then raise an exception during setup in order to deactivate themselves
• a plugin with status=False will not automatically be reloaded. Reloading can be enforced by restarting the server thread, by calling PluginLoader.load(plugin_name, force=True), or by setting the registry entry to None:

# Enforce immediate reload of a plugin
from plugins import PluginLoader
PluginLoader.load(plugin_name, force=True)

# Setting the registry entry to None triggers a reload in the next request cycle
registry = current.session.s3.plugins
registry[plugin_name] = None

It is also possible to reload all plugins:

# Re-run plugin detection and run all setups:
from plugins import PluginLoader
PluginLoader.setup_all(reload_all=True)

# Re-run plugin detection, but without running setups:
from plugins import PluginLoader
PluginLoader.detect(reset_all=True)

---

DeveloperGuidelines DeveloperGuidelines DeveloperGuidelines