From 209d7361aa349933ea7dcaf7f55d56addef63fc6 Mon Sep 17 00:00:00 2001
From: Antoine Nguyen <tonio@ngyn.org>
Date: Mon, 2 Feb 2015 15:48:20 +0100
Subject: [PATCH] Documentation updated.

---
 doc/extending/events.rst     | 34 +++++++++++++++++++++++
 doc/extending/plugin_api.rst | 53 ++++++++++++++++--------------------
 2 files changed, 57 insertions(+), 30 deletions(-)

diff --git a/doc/extending/events.rst b/doc/extending/events.rst
index af9c1a5b6..8b780d4a6 100644
--- a/doc/extending/events.rst
+++ b/doc/extending/events.rst
@@ -591,6 +591,29 @@ Raised to request extra parameters for a given parameters form.
 
 Must return a dictionary. Each entry must be a valid Django form field.
 
+.. _getextrarolepermissions:
+
+GetExtraRolePermissions
+=======================
+
+Let extensions define new permissions for a given role.
+
+*Callback prototype*::
+
+  def callback(rolename): pass
+
+* ``rolename`` is the role's name (str)
+
+Callbacks listening to this event must return a list of list. The
+second list level must contain exactly 3 strings: the application
+name, the model name and the permission name. Example::
+
+    [
+        ["core", "user", "add_user"],
+        ["core", "user", "change_user"],
+        ["core", "user", "delete_user"],
+    ]
+
 .. _getextraroles:
 
 GetExtraRoles
@@ -650,6 +673,17 @@ the following prototype::
 * ``row`` is a string containing the object's definition (CSV format)
 * ``formopts`` is a dictionary that may contain options
 
+InitialDataLoaded
+=================
+
+Raised a initial data has been loaded for a given extension.
+
+*Callback prototype*::
+
+  def callback(extname); pass
+
+ ``extname`` is the extension name (str)
+
 MailboxAliasCreated
 ===================
 
diff --git a/doc/extending/plugin_api.rst b/doc/extending/plugin_api.rst
index 59d9f1d2e..984072927 100644
--- a/doc/extending/plugin_api.rst
+++ b/doc/extending/plugin_api.rst
@@ -14,7 +14,7 @@ implementation provides the following possibilities:
 * Register callback actions for specific events
 
 Plugins are nothing more than Django applications with an extra piece
-of code that integrates them into Modoboa. Usually, the *__init__.py* file
+of code that integrates them into Modoboa. The *modo_extension.py* file
 will contain a complete description of the plugin:
 
 * Admin and user parameters
@@ -38,23 +38,22 @@ this (into Modoboa's directory)::
   $ python manage.py startapp
 
 Then, you need to register this application using the provided
-API. Just copy/paste the following example into the :file:`__init__.py` file
+API. Just copy/paste the following example into the :file:`modo_extension.py` file
 of the future extension::
 
   from modoboa.core.extensions import ModoExtension, exts_pool
+
   
   class MyExtension(ModoExtension):
+
+      """My custom Modoboa extension."""
+
       name = "myext"
       label = "My Extension"
       version = "0.1"
       description = "A description"
       url = "myext_root_location" # optional, name is used if not defined
       
-      def init(self):
-          """This method is called when the extension is activated.
-          """
-          pass
-          
       def load(self):
           """This method is called when Modoboa loads available and activated plugins.
 
@@ -62,19 +61,19 @@ of the future extension::
           """ 
           pass
           
-      def destroy(self):
-          """This function is called when a plugin is disabled from the interface.
-          
-          Unregister parameters and events here.
-          """
+      def load_initial_data(self):
+          """Optional: provide initial data for your extension here."""
           pass
 
   exts_pool.register_extension(MyExtension)
 
-Once done, simply add your plugin's module name to the
-``INSTALLED_APPS`` variable located inside :file:`settings.py`. Optionaly,
-run ``python manage.py syncdb`` if your plugin provides custom tables
-and ``python manage.py collectstatic`` to update static files.
+Once done, simply add your extension's module name to the
+``MODOBOA_APPS`` variable located inside :file:`settings.py`. Finally,
+run the following commands::
+
+  $ python manage.py migrate
+  $ python manage.py load_initial_data
+  $ python manage.py collectstatic
 
 **********
 Parameters
@@ -107,14 +106,6 @@ Both functions accept extra arguments listed here:
 * ``help`` : help text,
 * ``values`` : list of possible values if ``type`` is ``list``.
 
-To undeclare parameters (for example when a plugin is disabled is
-disabled from the interface), use the following function::
-
-  parameters.unregister_app(appname)
-
-``appname`` corresponds to your plugin's name, ie. the name of the
-directory containing the source code.
-
 ***************************
 Custom administrative roles
 ***************************
@@ -122,15 +113,17 @@ Custom administrative roles
 Modoboa uses Django's internal permission system. Administrative roles
 are nothing more than groups (``Group`` instances).
 
-If an extension needs to add new roles, it needs to follow those steps:
+If an extension needs to add new roles, the following steps are required:
 
-#. Create a new ``Group`` instance. It can be done by providing
-   `fixtures <https://docs.djangoproject.com/en/dev/howto/initial-data/>`_ 
-   or by creating it into the extension ``init`` function
-
-#. A a new listener for the :ref:`getextraroles` event that will return
+#. Listen to the :ref:`getextraroles` event that will return
    the group's name
 
+#. Listen to the :ref:`getextrarolepermissions` event that will return
+   the new group's permissions
+
+The group will automatically be created the next time you run the
+``load_initial_data`` command.
+
 *********************
 Extending admin forms
 *********************