From 913ec9e39ff6326d0d3e4bea92dc6d06b3d2d1bd Mon Sep 17 00:00:00 2001
From: Frederic Guillot <fred@kanboard.net>
Date: Sun, 3 Jan 2016 19:17:45 -0500
Subject: Add doc to create new automatic actions

---
 doc/plugin-automatic-actions.markdown | 60 +++++++++++++++++++++++++++++++++++
 doc/plugins.markdown                  |  1 +
 2 files changed, 61 insertions(+)
 create mode 100644 doc/plugin-automatic-actions.markdown

(limited to 'doc')

diff --git a/doc/plugin-automatic-actions.markdown b/doc/plugin-automatic-actions.markdown
new file mode 100644
index 00000000..b309fac9
--- /dev/null
+++ b/doc/plugin-automatic-actions.markdown
@@ -0,0 +1,60 @@
+Adding Automatic Actions
+========================
+
+Adding a new automatic action is pretty simple.
+
+Creating a new action
+---------------------
+
+Your automatic action must inherit of the class `Kanboard\Action\Base`.
+Several abstract methods must be implemented by yourself:
+
+| Method                              | Description                                                      |
+|-------------------------------------|------------------------------------------------------------------|
+| `getDescription()`                  | Description visible in the user interface                        |
+| `getCompatibleEvents()`             | Get the list of compatible events                                |
+| `getActionRequiredParameters()`     | Get the required parameter for the action (defined by the user)  |
+| `getEventRequiredParameters()`      | Get the required parameter for the event                         |
+| `doAction(array $data)`             | Execute the action, must return true on success                  |
+| `hasRequiredCondition(array $data)` | Check if the event data meet the action condition                |
+
+Your automatic action is identified in Kanboard by using the absolute class name with the name space included.
+
+Adding new events
+-----------------
+
+The list of application events is available in the class `Kanboard\Core\Event\EventManager::getAll()`.
+However, if your plugin fires new events, you can register these events like that:
+
+```php
+$this->actionManager->getAction('\Kanboard\Plugin\MyPlugin\MyActionName')->addEvent('my.event', 'My event description');
+```
+
+You can extend the list of compatible events of existing actions by using the same method.
+
+Registering the action
+----------------------
+
+You have to call the method `register()` from the class `Kanboard\Core\Action\ActionManager`:
+
+```php
+<?php
+
+namespace Kanboard\Plugin\AutomaticAction;
+
+use Kanboard\Core\Plugin\Base;
+use Kanboard\Plugin\AutomaticAction\Action\TaskRename;
+
+class Plugin extends Base
+{
+    public function initialize()
+    {
+        $this->actionManager->register(new TaskRename($this->container));
+    }
+}
+```
+
+Example
+-------
+
+- [Automatic Action example](https://github.com/kanboard/plugin-example-automatic-action)
diff --git a/doc/plugins.markdown b/doc/plugins.markdown
index 809ddd72..0b7316a9 100644
--- a/doc/plugins.markdown
+++ b/doc/plugins.markdown
@@ -14,6 +14,7 @@ Plugin creators should specify explicitly the compatible versions of Kanboard. I
 - [Custom routes](plugin-routes.markdown)
 - [Add mail transports](plugin-mail-transports.markdown)
 - [Add notification types](plugin-notifications.markdown)
+- [Add automatic actions](plugin-automatic-actions.markdown)
 - [Attach metadata to users, tasks and projects](plugin-metadata.markdown)
 - [Authentication architecture](plugin-authentication-architecture.markdown)
 - [Authentication plugin registration](plugin-authentication.markdown)
-- 
cgit v1.2.3