diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api-action-procedures.markdown | 42 | ||||
| -rw-r--r-- | doc/automatic-actions.markdown | 66 | ||||
| -rw-r--r-- | doc/plugin-automatic-actions.markdown | 60 | ||||
| -rw-r--r-- | doc/plugin-events.markdown | 27 | ||||
| -rw-r--r-- | doc/plugin-registration.markdown | 51 | ||||
| -rw-r--r-- | doc/plugins.markdown | 2 |
6 files changed, 130 insertions, 118 deletions
diff --git a/doc/api-action-procedures.markdown b/doc/api-action-procedures.markdown index 5dd88f4a..67bd85de 100644 --- a/doc/api-action-procedures.markdown +++ b/doc/api-action-procedures.markdown @@ -25,24 +25,24 @@ Response example: "jsonrpc": "2.0", "id": 1217735483, "result": { - "TaskLogMoveAnotherColumn": "Add a comment logging moving the task between columns", - "TaskAssignColorUser": "Assign a color to a specific user", - "TaskAssignColorColumn": "Assign a color when the task is moved to a specific column", - "TaskAssignCategoryColor": "Assign automatically a category based on a color", - "TaskAssignColorCategory": "Assign automatically a color based on a category", - "TaskAssignSpecificUser": "Assign the task to a specific user", - "TaskAssignCurrentUser": "Assign the task to the person who does the action", - "TaskUpdateStartDate": "Automatically update the start date", - "TaskAssignUser": "Change the assignee based on an external username", - "TaskAssignCategoryLabel": "Change the category based on an external label", - "TaskClose": "Close a task", - "CommentCreation": "Create a comment from an external provider", - "TaskCreation": "Create a task from an external provider", - "TaskDuplicateAnotherProject": "Duplicate the task to another project", - "TaskMoveColumnAssigned": "Move the task to another column when assigned to a user", - "TaskMoveColumnUnAssigned": "Move the task to another column when assignee is cleared", - "TaskMoveAnotherProject": "Move the task to another project", - "TaskOpen": "Open a task" + "\Kanboard\Action\TaskLogMoveAnotherColumn": "Add a comment logging moving the task between columns", + "\Kanboard\Action\TaskAssignColorUser": "Assign a color to a specific user", + "\Kanboard\Action\TaskAssignColorColumn": "Assign a color when the task is moved to a specific column", + "\Kanboard\Action\TaskAssignCategoryColor": "Assign automatically a category based on a color", + "\Kanboard\Action\TaskAssignColorCategory": "Assign automatically a color based on a category", + "\Kanboard\Action\TaskAssignSpecificUser": "Assign the task to a specific user", + "\Kanboard\Action\TaskAssignCurrentUser": "Assign the task to the person who does the action", + "\Kanboard\Action\TaskUpdateStartDate": "Automatically update the start date", + "\Kanboard\Action\TaskAssignUser": "Change the assignee based on an external username", + "\Kanboard\Action\TaskAssignCategoryLabel": "Change the category based on an external label", + "\Kanboard\Action\TaskClose": "Close a task", + "\Kanboard\Action\CommentCreation": "Create a comment from an external provider", + "\Kanboard\Action\TaskCreation": "Create a task from an external provider", + "\Kanboard\Action\TaskDuplicateAnotherProject": "Duplicate the task to another project", + "\Kanboard\Action\TaskMoveColumnAssigned": "Move the task to another column when assigned to a user", + "\Kanboard\Action\TaskMoveColumnUnAssigned": "Move the task to another column when assignee is cleared", + "\Kanboard\Action\TaskMoveAnotherProject": "Move the task to another project", + "\Kanboard\Action\TaskOpen": "Open a task" } } ``` @@ -109,7 +109,7 @@ Request example: "method": "getCompatibleActionEvents", "id": 899370297, "params": [ - "TaskClose" + "\Kanboard\Action\TaskClose" ] } ``` @@ -163,7 +163,7 @@ Response example: "id" : "13", "project_id" : "2", "event_name" : "task.move.column", - "action_name" : "TaskAssignSpecificUser", + "action_name" : "\Kanboard\Action\TaskAssignSpecificUser", "params" : { "column_id" : "5", "user_id" : "1" @@ -194,7 +194,7 @@ Request example: "params": { "project_id" : "2", "event_name" : "task.move.column", - "action_name" : "TaskAssignSpecificUser", + "action_name" : "\Kanboard\Action\TaskAssignSpecificUser", "params" : { "column_id" : "3", "user_id" : "2" diff --git a/doc/automatic-actions.markdown b/doc/automatic-actions.markdown index 69352d12..db56ccc0 100644 --- a/doc/automatic-actions.markdown +++ b/doc/automatic-actions.markdown @@ -26,59 +26,33 @@ Add a new action  -List of available events ------------------------- - -- Move a task to another column -- Move a task to another position in the same column -- Task modification -- Task creation -- Reopen a task -- Closing a task -- Task creation or modification -- Task assignee change -- Task link created or updated -- Github commit received -- Github issue opened -- Github issue closed -- Github issue reopened -- Github issue assignee change -- Github issue label change -- Github issue comment created -- Gitlab issue opened -- Gitlab issue closed -- Gitlab commit received -- Bitbucket commit received -- Bitbucket issue opened -- Bitbucket issue closed -- Bitbucket issue reopened -- Bitbucket issue assignee change -- Bitbucket issue comment created - List of available actions ------------------------- -- Close the task -- Open a task -- Assign the task to a specific user +- Create a comment from an external provider +- Add a comment log when moving the task between columns +- Assign automatically a category based on a color +- Change the category based on an external label +- Assign automatically a category based on a link +- Assign automatically a color based on a category +- Assign a color when the task is moved to a specific column +- Change task color when using a specific task link +- Assign a color to a specific user - Assign the task to the person who does the action +- Assign the task to the person who does the action when the column is changed +- Assign the task to a specific user +- Change the assignee based on an external username +- Close the task +- Close a task in a specific column +- Create a task from an external provider - Duplicate the task to another project +- Send a task by email to someone - Move the task to another project - Move the task to another column when assigned to a user +- Move the task to another column when the category is changed - Move the task to another column when assignee is cleared -- Assign color when the task is moved to a specific column -- Assign color to a specific user -- Assign automatically a color based on a category -- Assign automatically a category based on a color -- Create a comment from an external provider -- Create a task from an external provider -- Add a comment log when moving the task between columns -- Change the assignee based on an external username -- Change the category based on an external label +- Open a task - Automatically update the start date -- Move the task to another column when the category is changed -- Send a task by email to someone -- Change task color when using a specific task link Examples -------- @@ -87,7 +61,7 @@ Here are some examples used in real life: ### When I move a task to the column "Done", automatically close this task -- Choose action: **Close the task** +- Choose action: **Close a task in a specific column** - Choose the event: **Move a task to another column** - Define action parameter: **Column = Done** (this is the destination column) @@ -99,7 +73,7 @@ Here are some examples used in real life: ### When I move a task to the column "Work in progress", assign this task to the current user -- Choose action: **Assign the task to the person who does the action** +- Choose action: **Assign the task to the person who does the action when the column is changed** - Choose the event: **Move a task to another column** - Define action parameter: **Column = Work in progress** 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/plugin-events.markdown b/doc/plugin-events.markdown new file mode 100644 index 00000000..f4db8ff3 --- /dev/null +++ b/doc/plugin-events.markdown @@ -0,0 +1,27 @@ +Using Events +============ + +Kanboard use internally the [Symfony EventDispatcher component](https://symfony.com/doc/2.3/components/event_dispatcher/index.html) to manage internal events. + +Event Listening +--------------- + +```php +$this->on('app.bootstrap', function($container) { + // Do something +}); +``` + +- The first argument is the event name (string) +- The second argument is a PHP callable function (closure or class method) + +Adding a new event +------------------ + +To add a new event, you have to call the method `register()` of the class `Kanboard\Core\Event\EventManager`: + +```php +$this->eventManager->register('my.event.name', 'My new event description'); +``` + +These events can be used by other components of Kanboard like automatic actions. diff --git a/doc/plugin-registration.markdown b/doc/plugin-registration.markdown index 746fa200..d15f98e1 100644 --- a/doc/plugin-registration.markdown +++ b/doc/plugin-registration.markdown @@ -124,54 +124,3 @@ $this->container['hourlyRate']->getAll(); ``` Keys of the containers are unique across the application. If you override an existing class, you will change the default behavior. - -Event Listening ---------------- - -Kanboard use internal events and your plugin can listen and perform actions on these events. - -```php -$this->on('app.bootstrap', function($container) { - // Do something -}); -``` - -- 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 `Kanboard\Model\Action`, here an example: - -```php -<?php - -namespace Kanboard\Plugin\AutomaticAction; - -use Kanboard\Core\Plugin\Base; - -class Plugin extends Base -{ - public function initialize() - { - $this->action->extendActions( - '\Kanboard\Plugin\AutomaticAction\Action\DoSomething', // Use absolute namespace - t('Do something 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 inherit from the class `Kanboard\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). diff --git a/doc/plugins.markdown b/doc/plugins.markdown index 809ddd72..791fe3bd 100644 --- a/doc/plugins.markdown +++ b/doc/plugins.markdown @@ -9,11 +9,13 @@ Plugin creators should specify explicitly the compatible versions of Kanboard. I - [Creating your plugin](plugin-registration.markdown) - [Using plugin hooks](plugin-hooks.markdown) +- [Events](plugin-events.markdown) - [Override default application behaviors](plugin-overrides.markdown) - [Add schema migrations for plugins](plugin-schema-migrations.markdown) - [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) |