Plugin Hooks

Add new API methods

Kanboard uses this library JSON-RPC to handle API calls.

To add a new method, you can do something like this from your plugin:

$this->api->getProcedureHandler()->withCallback('my_method', function() {
    return 'foobar';
});

$this->container['api'] or $this->api expose an instance of the object JsonRPC\Server.

Read the library documentation for more information.

Add new console commands

Kanboard uses the library Symfony Console to handle local command lines.

Kanboard exposes an instance of the object Symfony\Component\Console\Application via $this->cli. You can add new commands from your plugin:

$this->cli->add(new MyCommand());

Read the library documentation for more information.

Add new task filters

Since the task lexer is a factory that returns a new instance each time, you have to extend the taskLexer container with the method extend() of Pimple.

Here is an example:

public function initialize()
{
    $this->container->extend('taskLexer', function($taskLexer, $c) {
        $taskLexer->withFilter(TaskBoardDateFilter::getInstance($c)->setDateParser($c['dateParser']));
        return $taskLexer;
    });
}

For the filter class implementation, there are several examples in the source code under the namespace Kanboard\Filter.

Application Hooks

Hooks can extend, replace, filter data or change the default behavior. Each hook is identified with a unique name, example: controller:calendar:user:events

Listen on hook events

In your initialize() method you need to call the method on() of the class Kanboard\Core\Plugin\Hook:

$this->hook->on('hook_name', $callable);

The first argument is the name of the hook and the second is a PHP callable.

Hooks executed only once

Some hooks can have only one listener: model:subtask-time-tracking:calculate:time-spent

  • Override time spent calculation when sub-task timer is stopped
  • Arguments:
    • $user_id (integer)
    • $start (DateTime)
    • $end (DateTime)

Merge hooks

“Merge hooks” act in the same way as the function array_merge. The hook callback must return an array. This array will be merged with the default one.

Example to add events in the user calendar:

class Plugin extends Base
{
    public function initialize()
    {
        $container = $this->container;

        $this->hook->on('controller:calendar:user:events', function($user_id, $start, $end) use ($container) {
            $model = new SubtaskForecast($container);
            return $model->getCalendarEvents($user_id, $end); // Return new events
        });
    }
}

Example to override default values for task forms:

class Plugin extends Base
{
    public function initialize()
    {
        $this->hook->on('controller:task:form:default', function (array $default_values) {
            return empty($default_values['score']) ? array('score' => 4) : array();
        });
    }
}

List of merging hooks:

controller:task:form:default

  • Override default values for task forms
  • Arguments:
    • $default_values: actual default values (array)

controller:calendar:project:events

  • Add more events to the project calendar
  • Arguments:
    • $project_id (integer)
    • $start Calendar start date (string, ISO-8601 format)
    • $end Calendar end date (string, ISO-8601 format)

controller:calendar:user:events

  • Add more events to the user calendar
  • Arguments:
    • $user_id (integer)
    • $start Calendar start date (string, ISO-8601 format)
    • $end Calendar end date (string, ISO-8601 format)

Asset Hooks

Asset hooks can be used to add a new stylesheet easily or a new JavaScript file in the layout. You can use this feature to create a theme and override all Kanboard default styles.

Example to add a new stylesheet:

<?php

namespace Kanboard\Plugin\Css;

use Kanboard\Core\Plugin\Base;

class Plugin extends Base
{
    public function initialize()
    {
        $this->hook->on('template:layout:css', array('template' => 'plugins/Css/skin.css'));
    }
}

List of asset Hooks:

  • template:layout:css
  • template:layout:js

Reference hooks

Reference hooks are passing a variable by reference.

Example:

$this->hook->on('formatter:board:query', function (\PicoDb\Table &query) {
    $query->eq('color_id', 'red');
});

The code above will show only tasks in red on the board.

List of reference hooks:

Hook Description
formatter:board:query Alter database query before rendering board
pagination:dashboard:pro ject:query Alter database query for projects pagination on the dashboard
pagination:dashboard:tas k:query Alter database query for tasks pagination on the dashboard
pagination:dashboard:sub task:query Alter database query for subtasks pagination on the dashboard
model:task:creation:prep are Alter form values before to save a task
model:task:creation:afte rsave Retrieve Task ID after creating a task
model:task:modification: prepare Alter form values before to edit a task
model:color:get-list Alter default_colors values
model:subtask:modificati on:prepare Alter form values before to save a subtask
model:subtask:creation:p repare Alter form values before to edit a subtask
model:subtask:count:quer y Alter database query for subtask count

Template Hooks

Template hooks allow additional content in existing templates.

Example to add new content in the dashboard sidebar:

$this->template->hook->attach('template:dashboard:sidebar', 'myplugin:dashboard/sidebar');

Example to attach a template with local variables:

$this->template->hook->attach('template:dashboard:sidebar', 'myplugin:dashboard/sidebar', array(
    'variable' => 'foobar',
));

Example to attach a template with a callable:

$this->template->hook->attach('template:dashboard:sidebar', 'myplugin:dashboard/sidebar', function($hook_param1, $hook_param2) {
    return array('new_template_variable' => 'foobar'); // Inject a new variable into the plugin template
});

This call is usually defined in the initialize() method. The first argument is the name of the hook and the second argument is the template name.

Template names prefixed with the plugin name and colon indicate the location of the template.

Example with myplugin:dashboard/sidebar:

  • myplugin is the name of your plugin (lowercase)
  • dashboard/sidebar is the template name
  • On the filesystem, the plugin will be located here: plugins\Myplugin\Template\dashboard\sidebar.php
  • Templates are written in pure PHP (don’t forget to escape data)

Template names without prefix are core templates.

List of template hooks:

Hook Description
template:analytic:sidebar Sidebar on analytic pages
template:app:filters-helper:before Filter helper dropdown (top)
template:app:filters-helper:after Filter helper dropdown (bottom)
template:auth:login-form:before Login page (top)
template:auth:login-form:after Login page (bottom)
template:board:private:task:before-title Task in private board: before title
template:board:private:task:after-title Task in private board: after title
template:board:public:task:before-title Task in public board: before title
template:board:public:task:after-title Task in public board: after title
template:board:task:footer Task in board: footer
template:board:task:icons Task in board: tooltip icon
template:board:table:column:before-header-row Row before board column header
template:board:table:column:after-header-row Row after board column header
template:board:column:dropdown Dropdown menu in board columns
template:board:column:header Board column header
template:board:tooltip:subtasks:header:before-assignee Header of Subtask table on tootip before Assignee
template:board:tooltip:subtasks:rows Column on row of Subtask table on tooltip
template:config:sidebar Sidebar on settings page
template:config:application Application settings form
template:config:board Board settings form
template:config:email Email settings page
template:config:integrations Integration page in global settings
template:dashboard:show Main page of the dashboard
template:dashboard:page-header:menu Dashboard submenu
template:dashboard:task:footer Task in dashboard: footer
template:header:dropdown Page header dropdown menu (user avatar icon)
template:header:creation-dropdown Page header dropdown menu (plus icon)
template:layout:head Page layout <head/> tag
template:layout:top Page layout top header
template:layout:bottom Page layout footer
template:project:dropdown “Actions” menu on left in different project views
template:project:header:before Project filters (before)
template:project:header:after Project filters (after)
template:project:integrations Integration page in projects settings
template:project:sidebar Sidebar in project settings
template:project-user:sidebar Sidebar on project user overview page
template:project-list:menu:before Project list: before menu entries
template:project-list:menu:after Project list: after menu entries
template:project-overview:before-description Project overview: before description
template:project-header:view-switcher Project view switcher
template:search:task:footer Task in results: footer
template:task:layout:top Task layout top (after page header)
template:task:details:top Task summary top
template:task:details:bottom Task summary bottom
template:task:details:first-column Task summary first column
template:task:details:second-column Task summary second column
template:task:details:third-column Task summary third column
template:task:details:fourth-column Task summary fourth column
template:task:dropdown Task dropdown menu in listing pages
template:task:sidebar:actions Sidebar on task page (section actions)
template:task:sidebar:information Sidebar on task page (section information)
template:task:form:first-column 1st column in task form
template:task:form:second-column 2nd column in task form
template:task:form:third-column 3nd column in task form
template:task:show:top Show task page: top
template:task:show:bottom Show task page: bottom
template:task:show:before-description Show task page: before description
template:task:show:before-tasklinks Show task page: before tasklinks
template:task:show:before-subtasks Show task page: before subtasks
template:task:show:before-timetracking Show task page: before timetracking
template:task:show:before-attachments Show task page: before attachments
template:task:show:before-comments Show task page: before comments
template:subtask:form:create Create Subtask form
template:subtask:form:edit Edit Subtask form
template:subtask:table:header:before-timetracking Subtask table header before Time Tracking
template:subtask:table:rows Column on row of subtasks table
template:user:authentication:form “Edit authentication” form in user profile
template:user:create-remote:form “Create remote user” form
template:user:external “External authentication” page in user profile
template:user:integrations Integration page in user profile
template:user:sidebar:actions Sidebar in user profile (section actions)
template:user:sidebar:information Sidebar in user profile (section information)
template:user:show:profile:info User profile information

More template hooks can be added if necessary, just ask on the issue tracker.