Changes between Version 1 and Version 2 of DeveloperGuidelines/TemplatePlugins

Timestamp:

07/25/16 13:50:25 (9 years ago)

Author:

Dominic König

Comment:

--

DeveloperGuidelines/TemplatePlugins

@@ -14 +14 @@
 == Implementation ==
 
- * ''tbw''
+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}}}
+ - plugins '''must not''' redirect (HTTP 30x) unconditionally (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