Changes between Version 35 and Version 36 of TracDev/PluginDevelopment

Timestamp:

May 6, 2010, 9:29:59 PM (14 years ago)

Author:

Carsten Klein <carsten.klein@…>

Comment:

Added information on how to author custom extension point interfaces and make use of these

TracDev/PluginDevelopment

@@ -7 +7 @@
 
 Trac offers an increasing number of ''extension points'' that allow you to plugin custom extensions for various functions. You can view a list of provided extension points on the page ''About Trac/Plugins'' of your Trac installation.
+
+=== Declaring Custom Extension Points ===
+
+Plugins can declare additional extension points. In order to do so, one must inherit from [source:trunk/trac/core.py trac.core.Interface].
+
+{{{#!python
+from trac.core import Interface
+
+class ICustomExtensionPoint(Interface):
+    """The extension point interface allows plugins to ...
+    """
+
+    def do_something():
+        """Does something."""
+}}}
+
+Please note that all extension point interfaces need to be authored so that their declared methods are unbound, that is, you simply omit the 'self' as first parameter to the method.
+This is so, that future extensions or changes to the API can be introduced, by for example adding new or removing existing parameters without causing breakage of existing components implementing the interface.
+
+== Implementing Extension Points ==
+
+In order to implement an extension point, your class must be derived from [source:trunk/trac/core.py trac.core.Component] and it must implement the extension point interface.
+
+{{{#!python
+from trac.core import Component, implements
+
+class CustomComponent(Component):
+
+    implements(ICustomExtensionPoint)
+
+    # ICustomExtensionPoint methods
+
+    def do_something(self):
+        self.log.debug("Hello World")
+}}}
+
+When implementing the methods of the interface, the methods have to be bound to the instance, so you will have to specify 'self' as the first parameter.
+
+More detailed information on this can be found below under [wiki:TracDev/PluginDevelopment#Writingtheplugincode].
+
+== Using Extension Points ==
+
+In order for your custom component making use of plugins that implement all or one custom extension point interface provided by you, you will have to again derive your component from trac.core.Component, and then use [source:trunk/trac/core.py trac.core.ExtensionPoint] to get the instances that implement your custom extension point interface.
+
+{{{#!python
+from trac.core import Component, ExtensionPoint
+
+class SampleModule(Component):
+
+    custom_extensions = ExtensionPoint(ICustomExtensionPoint)
+
+    def example():
+        for ext in self.custom_extensions:
+            ext.do_something()
+}}}
 
 === Available Extension Points ===