manual/docs/en/plugins.txt

@@ -1,9 +1,15 @@
 This chapter describes various plugins availible for Doctrine. When refering to plugins we refer to classes that extend Doctrine_Plugin. All the components in this chapter can be considered 'core' plugins, that means they reside at the Doctrine main repository. There are other official plugins too which can be found at the homesite of the Sensei project (www.sensei-project.org).
 
-++ Validators
-++ View
-++ Profiler
-++ Locking Manager
+Usually plugins are used side-to-side with template classes (classes that extend Doctrine_Template). The common workflow is:
+
+# A new template is being initiliazed
+# The template creates the plugin and calls buildPluginDefinition() method
+# The template is attached to given class
+
+As you may already know templates are used for adding common definitions and options to record classes. The purpose of plugins is much more complex. Usually they are being used for creating generic record classes dynamically. The definitions of these generic classes usually depend on the owner class. For example the columns of the auditlog versioning class are the columns of the parent class with all the sequence and autoincrement definitions removed.
+
+
+
 ++ Internationalization with I18n
 
 Doctrine_I18n is a plugin for Doctrine that provides internationalization support for record classes. In the following example we have a NewsItem class with two fields 'title' and 'content'. We want to have the field 'title' with different languages support. This can be achieved as follows:
@@ -23,6 +29,12 @@ class NewsItem extends Doctrine_Record
     }
 }
 </code>
+
+Now the first time you initialize a new NewsItem record Doctrine initializes the plugin that builds the followings things:
+
+1. Record class called NewsItemTranslation
+2. Bi-directional relations between NewsItemTranslation and NewsItem
+
 +++ Creating the I18n table
 
 The I18n table can be created as follows:
@@ -200,3 +212,40 @@ $record->save();
 $record->delete();
 var_dump($record->deleted); // true
 </code>
+
+++ Creating plugins
+
+This subchapter provides you the means for creating your own plugins. In order to grasp the concepts of this chapter you should already be familiar with the ideas of Doctrine_Template. 
+
+Lets say we have various different Record classes that need to have one-to-many emails. We achieve this functionality by creating a generic plugin which creates Email classes on the fly.
+
+We start this task by creating a plugin called EmailPlugin with buildDefinition() method.
+
+<code type="php">
+class EmailPlugin extends Doctrine_Plugin
+{
+    public function initOptions()
+    {
+        $this->setOption('className', '%CLASS%Email');
+    }
+    
+    public function buildDefinition()
+    {
+        // build the foreign key definitions
+        $fk = $this->buildForeignKeys($this->_options['table']);
+
+        $relations = $this->buildRelation($fk);
+
+        $columns['address'] = array('type'   => 'string',
+                                    'length' => 255,
+                                    'email'  => true,
+                                    'primary' => true);
+        $columns += $fk;
+        
+        $this->generateClassDefinition(array(), $columns, $relations);
+    }
+}
+</code>
+
+++ Nesting plugins
+