Changes between Version 1 and Version 2 of DeveloperGuidelines/TemplatePlugins

07/25/16 13:50:25 (6 years ago)
Dominic König



  • DeveloperGuidelines/TemplatePlugins

    v1 v2  
    1414== Implementation ==
    16  * ''tbw''
     16A ''template plugin'' can be a Python module or a Python package. The name of the module/package becomes the plugin name.
     18It must expose a function {{{setup()}}}:
     19 - {{{setup()}}} takes no arguments, and returns nothing
     20 - {{{setup()}}} will be called during ''every'' request cycle (so minimize the load!)
     21 - {{{setup()}}} will be called immediately before the controller is executed
     24# Example plugin
     26__version__ = "0.0.0"
     28def setup():
     30    # The plugin can access and alter deployment settings
     31    settings = current.deployment_settings
     34The plugin module/package can additionally define a {{{__version__}}} string, which becomes accessible via current.session:
     37# The session holds the registry of current plugins
     38registry = current.session.s3.plugins
     40# The registry is a dict of tuples {plugin_name: (version, status)}
     41plugin_info = registry.get(plugin_name)
     43# - version is the __version__ string defined by the plugin or "unknown"
     44# - status is True if the plugin's setup function was successful, otherwise False
     45if plugin_info:
     46    version, status = plugin_info
     48    # Plugin has not been loaded yet
     49    version, status = None, None
     54 - plugins '''should''' raise an exception in case of unrecoverable errors during setup, in order to deactivate themselves
     55 - plugins are responsible to log all their errors themselves, using {{{current.log}}}
     56 - plugins '''must not''' redirect (HTTP 30x) unconditionally (that would give an indefinite redirection loop)
     57 - 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
     58 - 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:
     61# Enforce immediate reload of a plugin
     62from plugins import PluginLoader
     63PluginLoader.load(plugin_name, force=True)
     65# Setting the registry entry to None triggers a reload in the next request cycle
     66registry = current.session.s3.plugins
     67registry[plugin_name] = None
     70It is also possible to reload all plugins:
     73# Re-run plugin detection and run all setups:
     74from plugins import PluginLoader
     77# Re-run plugin detection, but without running setups:
     78from plugins import PluginLoader