Allow to extend automatic actions from plugins

app/Action/Base.php

@@ -126,6 +126,17 @@ abstract class Base extends \Core\Base
         return get_called_class();
     }
 
+    /**
+     * Get project id
+     *
+     * @access public
+     * @return integer
+     */
+    public function getProjectId()
+    {
+        return $this->project_id;
+    }
+
     /**
      * Set an user defined parameter
      *

app/Model/Action.php

@@ -30,6 +30,28 @@ class Action extends Base
      */
     const TABLE_PARAMS = 'action_has_params';
 
+    /**
+     * Extended actions
+     *
+     * @access private
+     * @var array
+     */
+    private $actions = array();
+
+    /**
+     * Extend the list of default actions
+     *
+     * @access public
+     * @param  string  $className
+     * @param  string  $description
+     * @return Action
+     */
+    public function extendActions($className, $description)
+    {
+        $this->actions[$className] = $description;
+        return $this;
+    }
+
     /**
      * Return the name and description of available actions
      *
@@ -62,6 +84,8 @@ class Action extends Base
             'TaskAssignColorLink' => t('Change task color when using a specific task link'),
         );
 
+        $values = array_merge($values, $this->actions);
+
         asort($values);
 
         return $values;
@@ -296,7 +320,7 @@ class Action extends Base
      */
     public function load($name, $project_id, $event)
     {
-        $className = '\Action\\'.$name;
+        $className = $name{0} !== '\\' ? '\Action\\'.$name : $name;
         return new $className($this->container, $project_id, $event);
     }
 

doc/plugins.markdown

@@ -251,10 +251,47 @@ $this->on('session.bootstrap', function($container) {
 - The first argument is the event name
 - The second argument is a PHP callable function (closure or class method)
 
+Extend Automatic Actions
+------------------------
+
+To define a new automatic action with a plugin, you just need to call the method `extendActions()` from the class `Model\Action`, here an example:
+
+```php
+<?php
+
+namespace Plugin\AutomaticAction;
+
+use Core\Plugin\Base;
+
+class Plugin extends Base
+{
+    public function initialize()
+    {
+        $this->action->extendActions(
+            '\Plugin\AutomaticAction\Action\SendSlackMessage', // Use absolute namespace
+            t('Send a message to Slack when the task color change')
+        );
+    }
+}
+```
+
+- The first argument of the method `extendActions()` is the action class with the complete namespace path. **The namespace path must starts with a backslash** otherwise Kanboard will not be able to load your class.
+- The second argument is the description of your automatic action.
+
+The automatic action class must inherits from the class `Action\Base` and implements all abstract methods:
+
+- `getCompatibleEvents()`
+- `getActionRequiredParameters()`
+- `getEventRequiredParameters()`
+- `doAction(array $data)`
+- `hasRequiredCondition(array $data)`
+
+For more details you should take a look to existing automatic actions or this [plugin example](https://github.com/kanboard/plugin-example-automatic-action).
+
 Extend ACL
 ----------
 
-Kanboard use a custom access list for privilege separations. Your extension can add new rules:
+Kanboard use an access list for privilege separations. Your extension can add new rules:
 
 ```php
 $this->acl->extend('project_manager_acl', array('mycontroller' => '*'));
@@ -365,5 +402,6 @@ Examples of plugins
 - [Budget planning](https://github.com/kanboard/plugin-budget)
 - [User timetable](https://github.com/kanboard/plugin-timetable)
 - [Subtask Forecast](https://github.com/kanboard/plugin-subtask-forecast)
-- [Theme plugin sample](https://github.com/kanboard/plugin-example-theme)
-- [CSS plugin sample](https://github.com/kanboard/plugin-example-css)
+- [Automatic Action example](https://github.com/kanboard/plugin-example-automatic-action)
+- [Theme plugin example](https://github.com/kanboard/plugin-example-theme)
+- [CSS plugin example](https://github.com/kanboard/plugin-example-css)

tests/units/Model/ActionTest.php

@@ -27,6 +27,17 @@ class ActionTest extends Base
         $this->assertEquals('TaskLogMoveAnotherColumn', key($actions));
     }
 
+    public function testExtendActions()
+    {
+        $a = new Action($this->container);
+        $a->extendActions('MyClass', 'Description');
+
+        $actions = $a->getAvailableActions();
+        $this->assertNotEmpty($actions);
+        $this->assertContains('Description', $actions);
+        $this->assertArrayHasKey('MyClass', $actions);
+    }
+
     public function testGetEvents()
     {
         $a = new Action($this->container);