Changes between Version 23 and Version 24 of TracDev/ComponentArchitecture

Timestamp:

Nov 21, 2010, 7:15:19 PM (13 years ago)

Author:

Sebastian Krysmanski <sebastian@…>

Comment:

Some more notes

TracDev/ComponentArchitecture

@@ -187 +187 @@
 Now, the following list describes the stages a component goes through until it's ready to be used:
 
- 1. ''Registration:'' The first step is to register a component so that Trac knows about it. This happens automatically when the Python file contain the component gets imported for the first time. This is done either with a `import` statement in a file that has already been imported, or - like in most cases - by listing the file in `entry_points` section of a plugin (see [wiki:TracDev/PluginDevelopment#Packagingplugins Packaging Plugins]).[[BR]]
-    The registration is handled by `trac.core.ComponentMeta` using [http://www.ibm.com/developerworks/linux/library/l-pymeta.html metaclass programming].
- 1. ''Activation:'' A component gets activated when it's first used. So, "activation" is basically just another word for "instantiation", though since a component is a singleton it's only activate/instantiated once. When a component gets activated, Trac's component manager adds some useful fields to the component (specifically: `env`, `log`, and `config`).[[BR]]
-    A component can be activated by one of the following ways:
-      * when its manually constructed for the first time (using `Component(compmngr)`) 
+ 1. ''Registration:'' The first step is to register a component so that Trac knows about it. This happens automatically when the Python file contain the component gets imported for the first time.[[BR]]
+ A component can be registered using one of the following methods:
+  * with an `import` statement in a file that has already been imported
+  * by listing the file in `entry_points` section of a plugin (see [wiki:TracDev/PluginDevelopment#Packagingplugins Packaging Plugins])
+
+ The registration is handled by `trac.core.ComponentMeta` using [http://www.ibm.com/developerworks/linux/library/l-pymeta.html metaclass programming].
+ 2. ''Activation:'' A component gets activated when it's first used. So, "activation" is basically just another word for "instantiation", though since a component is a singleton it's only activate/instantiated once. When a component gets activated, Trac's component manager adds some useful fields to the component (specifically: `env`, `log`, and `config`).[[BR]]
+    A component can be activated using one of the following methods:
+      * when it's manually constructed for the first time (using `Component(compmngr)`) 
       * when one of the extension points the component implements is used for the first time. Note that the component must be enabled for this way to work (see below).
     
@@ -204 +208 @@
 Enabling a component is done in the `[components]` section of [wiki:TracIni trac.ini]. This is implemented in `trac.env.Environment.is_component_enabled()`. Whether a component is enabled or disabled is check ''only once'' when an extension point that component implements is first used.
 
-''Note:'' Not all components require to be enabled to work properly. ''Only'' components implementing an extension point interface ( using `implements`) need to be enabled and therefor listed in the `entry_points` section of a plugin. If you just want to have the utility class (like a database manager) that takes the benefits of a component (like being a singleton and/or having access to Trac's database or configuration) that doesn't implement any extension point interfaces, it doesn't need to be enabled (or even listed in the `entry_points` section).
+''Miscellaneous notes:'' 
+* Components can be marked "abstract". This is done simply by adding a member field `abstract = True` to the component class.
+  {{{
+  #!python
+  class MyAbstractComponent(Component):
+      abstract = True
+      # implementation stuff here
+  }}}
+  Abstract components can't be enabled and therefor don't appear in the plugin panel of Trac's web interface.
+* Not all components require to be enabled to work properly. ''Only'' components implementing an extension point interface (using `implements`) need to be enabled and therefor listed in the `entry_points` section of a plugin. If you just want to have the utility class (like a database manager) that takes the benefits of a component (like being a singleton and/or having access to Trac's database or configuration) that doesn't implement any extension point interfaces, it doesn't need to be enabled (or even listed in the `entry_points` section). Such a component should then be marked "abstract". 
+* Components should be listed in the `entry_points` section, if they define any options (from `trac.config`). This way `trac.ini` editors can find this option even if it still has its default value. Options are registered when the component is registered. The component that defines the option doesn't need to be enabled for the option to be registered and can even be abstract.
+
 
 == How components are used in Trac's code ==