Changeset 5658 for main/waeup.sirp/trunk/src/waeup

Timestamp:

24 Jan 2011, 22:35:32 (14 years ago)

Author:

uli

Message:

Tell more about the plugin mechanism.

File:

• main/waeup.sirp/trunk/src/waeup/sirp/interfaces.py (modified) (2 diffs)

main/waeup.sirp/trunk/src/waeup/sirp/interfaces.py

@@ -240 +240 @@
 class IWAeUPSIRPPluggable(Interface):
     """A component that might be plugged into a WAeUP SIRP app.
+
+    Components implementing this interface are referred to as
+    'plugins'. They are normally called when a new
+    :class:`waeup.sirp.app.University` instance is created.
+
+    Plugins can setup and update parts of the central site without the
+    site object (normally a :class:`waeup.sirp.app.University` object)
+    needing to know about that parts. The site simply collects all
+    available plugins, calls them and the plugins care for their
+    respective subarea like the applications area or the datacenter
+    area.
+
+    Currently we have no mechanism to define an order of plugins. A
+    plugin should therefore make no assumptions about the state of the
+    site or other plugins being run before and instead do appropriate
+    checks if necessary.
+
+    Updates can be triggered for instance by the respective form in
+    the site configuration. You normally do updates when the
+    underlying software changed.
     """
     def setup(site, name, logger):
         """Create an instance of the plugin.
 
-        The method is meant to be called by the central app on startup.
+        The method is meant to be called by the central app (site)
+        when it is created.
+
+        `site`:
+           The site that requests a setup.
+
+        `name`:
+           The name under which the plugin was registered (utility name).
+
+        `logger`:
+           A standard Python logger for the plugins use.
         """
 
@@ -251 +281 @@
 
         This might be called by a site when something serious
-        changes. It is a poor-man replacement for Zope generations.
-        """
+        changes. It is a poor-man replacement for Zope generations
+        (but probably more comprehensive and better understandable).
+
+        `site`:
+           The site that requests an update.
+
+        `name`:
+           The name under which the plugin was registered (utility name).
+
+        `logger`:
+           A standard Python logger for the plugins use.
+        """