diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/closing-tasks.markdown | 6 | ||||
| -rw-r--r-- | doc/fr/analytics.markdown | 70 | ||||
| -rw-r--r-- | doc/fr/automatic-actions.markdown | 137 | ||||
| -rw-r--r-- | doc/fr/budget.markdown | 34 | ||||
| -rw-r--r-- | doc/fr/calendar.markdown | 20 | ||||
| -rw-r--r-- | doc/fr/creating-projects.markdown | 32 | ||||
| -rw-r--r-- | doc/fr/editing-projects.markdown | 16 | ||||
| -rw-r--r-- | doc/fr/gantt-chart-projects.markdown | 17 | ||||
| -rw-r--r-- | doc/fr/gantt-chart-tasks.markdown | 20 | ||||
| -rw-r--r-- | doc/fr/project-permissions.markdown | 49 | ||||
| -rw-r--r-- | doc/fr/sharing-projects.markdown | 37 | ||||
| -rw-r--r-- | doc/fr/swimlanes.markdown | 28 | ||||
| -rw-r--r-- | doc/index.markdown | 3 | ||||
| -rw-r--r-- | doc/plugins.markdown | 263 | ||||
| -rw-r--r-- | doc/screenshots.markdown | 2 | ||||
| -rw-r--r-- | doc/subtasks.markdown | 2 |
16 files changed, 730 insertions, 6 deletions
diff --git a/doc/closing-tasks.markdown b/doc/closing-tasks.markdown index 235387a9..018acace 100644 --- a/doc/closing-tasks.markdown +++ b/doc/closing-tasks.markdown @@ -1,11 +1,11 @@ Closing tasks ============= -When a task is closed, they are hidden from the board. +When a task is closed, it is hidden from the board. However, you can always access to the list of closed tasks by using the query **status:closed** in any search form or simply choose **Closed tasks** from the filter dropdown. -There are two different way to close a task, from the task dropdown menu on the board: +There are two different ways to close a task, from the task dropdown menu on the board:  @@ -13,4 +13,4 @@ Or from the task sidebar menu in the task detail view:  -Note: When you close a task, all subtasks not completed will be changed to the status "Done".
\ No newline at end of file +Note: When you close a task, all subtasks not completed will be changed to the status "Done". diff --git a/doc/fr/analytics.markdown b/doc/fr/analytics.markdown new file mode 100644 index 00000000..951ade04 --- /dev/null +++ b/doc/fr/analytics.markdown @@ -0,0 +1,70 @@ +Analytique +========= + +Chaque projet dispose d'une section analytique. En fonction de la façon dont vous utilisez Kanboard, vous pourrez voir les rapports suivants : + +Répartition des utilisateurs +---------------- + + + +Ce graphique circulaire affiche le nombre de tâches assignées par utilisateur. + +Distribution des tâches +----------------- + + + +Ce graphique circulaire donne une vue d'ensemble du nombre de tâches ouvertes par colonne. + +Diagramme de flux cumulé +----------------------- + + + +- Ce graphique affiche le nombre de tâches de façon cumulée pour chaque colonne en fonction du temps passé. +- Chaque jour, le nombre total de tâches est enregistré pour chaque colonne. +- Si vous souhaitez exclure les tâches terminées, modifiez les [paramètres du projet global](project-configuration.markdown). + +Remarque : il faut au moins deux jours de données pour que le graphique apparaisse. + +Graphique d'avancement +-------------- + + + +Un [graphique d'avancement](http://en.wikipedia.org/wiki/Burn_down_chart) est disponible pour chaque projet. + +- Il s'agit de la représentation graphique du travail qui reste à faire en fonction du temps restant. +- Kanboard utilise la complexité des estimations d'achèvement pour créer le graphique. +- Chaque jour, la somme des estimations pour chaque colonne est calculée. + +Temps moyen passé pour chaque colonne +----------------------------------- + + + +Ce graphique affiche le temps moyen passé pour chaque colonne pour les 1000 dernière tâches. + +- Kanboard utilise les transitions entre tâches pour calculer les données. +- Le temps passé est calculé jusqu'à la fin de la tâche. + +Temps moyen de Lead et Cycle +--------------------------- + + + +Ce graphique affiche le temps moyen de lead et cycle pour les 1000 dernières tâches au cours du temps. + +- Le *lead time* est le temps passé entre la création de la tâche et sa date d'achèvement. +- Le *cycle time* est le temps passé entre la date de début spécifiée et la date d'achèvement de la tâche. +- Si la tâche n'est pas close, la date courante est utilisée à la place de la date d'achèvement. + +Ces métriques sont calculées et enregistrées chaque jour pour l'ensemble du projet. + +N'oubliez pas de lancer chaque jour le calcul statistique +------------------------------------------------------- + +Pour générer des données analytique précises, vous devriez lancer chaque jour le cronjob **statistiques quotidiennes du projet**. + +[Consultez la documentation sur la ligne de commande avec Kanboard](cli.markdown) diff --git a/doc/fr/automatic-actions.markdown b/doc/fr/automatic-actions.markdown new file mode 100644 index 00000000..844354a5 --- /dev/null +++ b/doc/fr/automatic-actions.markdown @@ -0,0 +1,137 @@ +Actions automatiques +================= + +Pour réduire au minimum l'interaction avec les utilisateurs, Kanboard dispose d'actions automatiques. + +Chaque action automatique est définie ainsi : + +- Un événement à suivre +- Une action associée à cet évènement +- Éventuellement quelques paramètres à définir + +Chaque projet a une série d'actions automatisées qui lui sont propres, le panneau de configuration est situé sur la page qui liste les projets, il vous suffit de cliquer sur le lien **Actions automatiques**. + +Ajouter une nouvelle action +---------------- + +### Choisir une action + + + +### Choisir un évènement + + + +### Définir les paramètres d'une action + + + +Liste des évènements disponibles +------------------------ + +- Déplacement d'une tâche vers une autre colonne +- Déplacement d'une tâche à un autre emplacement de la même colonne +- Modification d'une tâche +- Création d'une tâche +- Réouverture d'une tâche +- Fermeture d'une tâche +- Création ou modification d'une tâche +- Changement d'assigné à une tâche +- Création ou mise à jour du lien vers une tâche +- Réception d'un *commit* de Github +- Ouverture d'une *issue* de Github +- Fermeture d'une *issue* de Github +- Réouverture d'une *issue* de Github +- Modification de l'assigné à une *issue* de Github +- Modification de l'étiquette d'une *issue* de Github +- Création d'un commentaire d'une *issue* de Github +- Ouverture d'une *issue* de Gitlab +- Fermeture d'une *issue* de Gitlab +- Réception d'un *commit* de Gitlab +- Réception d'un *commit* de Bitbucket +- Ouverture d'une *issue* de Bitbucket +- Fermeture d'une *issue* de Bitbucket +- Réouverture d'une *issue* de Bitbucket +- Modification de l'assigné à une *issue* de Bitbucket issue assignee change +- Création d'un commentaire d'une *issue* de Bitbucket + +Liste des actions disponibles +------------------------- + +- Fermer une tâche +- Ouvrir une tâche +- Assigner la tâche à un utilisateur particulier +- Assigner la tâche à la personne qui fait l'action +- Cloner la tâche depuis un autre projet +- Déplacer la tâche vers un autre projet +- Déplacer la tâche vers une autre colonne quand elle est assignée à un utilisateur +- Déplacer la tâche vers une autre colonne quand quand l'assigné est supprimé +- Assigner une couleur quand la tâche est déplacée vers une colonne particulière +- Assigner une couleur à un utilisateur particulier +- Assigner automatiquement une couleur selon la catégorie +- Assigner automatiquement une catégorie en fonction d'une couleur +- Créer un commentaire depuis un fournisseur externe +- Créer une tâche depuis un fournisseur externe +- Ajouter un journal de commentaires quand on change une tâche de colonne +- Modifier l'assigné en fonction d'un nom d'utilisateur externe +- Modifier la catégorie en fonction d'une étiquette externe +- Mettre à jour automatiquement la date de début +- Déplacer la tâche vers une autre colonne quand la catégorie a changé +- Envoyer une tâche par mail à quelqu'un +- Modifier la couleur de la tâche quand on utilise un lien particulier pour cette tâche + +Exemples +-------- +Voici quelques exemples d'utilisation dans la vraie vie : + +### Quand je déplace une tâche vers la colonne "Terminer", fermer automatiquement cette tâche + +- Choisir l'action : **Fermer la tâche** +- Choisir l'évènement : **Déplacement d'une tâche vers une autre colonne** +- Définir le paramètre de l'action : **Colonne = Terminé** (c'est la colonne de destination) + +### Quand je déplace une tâche vers la colonne "À valider", assigner cette tâche à un utilisateur particulier + +- Choisir l'action : **Assigner la tâche à un utilisateur particulier** +- Choisir l'évènement : **Déplacer une tâche vers une nouvelle colonne** +- Définir les paramètres de l'action :**Colonne = À valider** et **Utilisateur = Adrien** (Adrien est par exemple un testeur) + +### Quand je déplace une tâche vers la colonne "Travail en cours", assigner cette tâche à l'utilisateur courant + +- Choisir l'action : **Assigner la tâche à la personne qui fait cette action** +- Choisir l'évènement : **Déplacer une tâche vers une autre colonne** +- Définir le paramètre de l'action : **Colonne = Travail en cours** + +### Quand une tâche est terminée, dupliquer cette tâche vers un autre projet + +Supposons que nous ayons deux projets : "Commande du client" et "Production". Une fois validée la commande, la basculer vers le projet "Production". + +- Choisir l'action : **Dupliquer la tâche vers un autre projet** +- Choisir l'évènement : **Fermer une tâche** +- Définir les paramètres de l'action : **Colonne = Validé** et **Projet = Production** + +### Quand une tâche est déplacée vers la toute dernière colonne, déplacer la même tâche exactement vers un autre projet + +Supposons que nous ayons deux projets : "Idées" et "Développement". Une fois validée l'idée, la basculer vers le projet "Développement". + +- Choisir l'action : **Déplacer la tâche vers un autre projet** +- Choisir l'évènement : **Déplacer une tâche vers une autre colonne** +- Définir les paramètres de l'action : **Colonne = Validé** et **Projet = Développement** + +### Je veux assigner automatiquement une couleur à l'utilisateur Adrien + +- Choisir l'action : **Assigner une couleur à un utilisateur particulier** +- Choisir l'évènement : **Modification de l'assigné à une tâche** +- Définir les paramètres de l'action :**Couleur = Vert** et **Assigné = Adrien** + +### Je veux assigner automatiquement une couleur à la catégorie "Demande de fonctionnalité" + +- Choisir l'action : **Assigner automatiquement une couleur à une catégorie particulière** +- Choisir l'évènement : **Création ou modification d'une tâche** +- Définir les paramètres de l'action : **Couleur = Bleu** et **Catégorie = Demande de fonctionnalité** + +### Je veux régler automatiquement la date de début quand la tâche est déplacée dans la colonne "Travail en cours" + +- Choisir l'action : **Mettre à jour automatiquement la date de début** +- Choisir l'évènement : **Déplacer une tâche vers une autre colonne** +- Définir les paramètres de l'action : **Colonne= Travail en cours** diff --git a/doc/fr/budget.markdown b/doc/fr/budget.markdown new file mode 100644 index 00000000..3eac20d5 --- /dev/null +++ b/doc/fr/budget.markdown @@ -0,0 +1,34 @@ +Gestion du budget +================= + +La gestion du budget repose sur le suivi du temps d'une sous-tâche, l'emploi du temps de l'utilisateur et le taux horaire de l'utilisateur. + +Cette section est accessible depuis la page de paramètres du projet : **Project > Budget**. Il existe également un raccourci depuis le menu déroulant sur le tableau. + +Lignes budgétaires +------------ + + + +Les lignes budgétaires sont utilisées pour définir le budget du projet. +Celui-ci peut être ajusté en ajoutant une nouvelle entrée avec une date effective. + +Détail des coûts +-------------- + + + +Selon le tableau qui donne le suivi temporel de la sous-tâche et les informations sur l'utilisateur vous pouvez voir le coût de chaque sous-tâche. + +Le temps passé est arrondi au quart d'heure le plus proche. + +Graphique du budget +------------ + + + +Finalement, en combinant toutes les informations nous pouvons générer un graphique : + +- Les dépenses représentent le coût utilisateur +- Les lignes budgétaires sont le budget prévisionnel +- Le restant est le budget qui reste après un délai donné diff --git a/doc/fr/calendar.markdown b/doc/fr/calendar.markdown new file mode 100644 index 00000000..94610efb --- /dev/null +++ b/doc/fr/calendar.markdown @@ -0,0 +1,20 @@ +Calendriers +======== + +il existe deux visualisations différentes des calendriers : + +- La vue du projet avec des filtres (disponibles depuis le tableau) +- La vue utilisateur (disponible depuis le tableau de bord de l'utilisateur) + +Pour l'instant le calendrier permet d'afficher les informations suivantes : + +- Les tâches avec une date d'échéance, affichée en haut. **La date d'échéance peut être modifiée en déplaçant la tâche vers un autre jour**. +- les tâches basées sur la date de création ou la date de début. **Ces évènements ne peuvent pas être modifiés avec le calendrier**. +- Le suivi dans le temps de sous-tâches, tous les segments temporels sont affichés dans le calendrier. +- Les estimations pour les sous-tâches, les prévisions et le travail restant + + + +La configuration du calendrier peut être modifiée dans la page des paramètres. + +Remarque : la date d'échéance n'inclut pas d'information temporelle. diff --git a/doc/fr/creating-projects.markdown b/doc/fr/creating-projects.markdown new file mode 100644 index 00000000..d492ac62 --- /dev/null +++ b/doc/fr/creating-projects.markdown @@ -0,0 +1,32 @@ +Créer des projets +================= + +Kanboard peut gérer de multiples projets. Voici deux sortes de projets : + +- Les projets multi-utilisateurs (pour le travail collaboratif, en équipe) +- Les projets privés, réservés à un seul utilisateur + +Créer des projets multi-utilisateurs +------------------------------------- + +- Seuls les administrateurs et administrateurs de projets peuvent créer ce type de projets +- La gestion des utilisateurs est disponible + +Depuis le tableau principal, cliquez sur le lien **Nouveau projet** : + + + +C'est vraiment très simple, il vous suffit de trouver un nom pour votre projet ! + +Créer un projet privé +-------------------------- + +- Tout le monde peut créer un projet privé +- Il n'y a **pas** de gestion des utilisateurs +- Seuls le propriétaire et les administrateurs peuvent accéder au projet + +Depuis le tableau principal, cliquez sur le lien **Nouveau projet privé**. + + + +Remarque : les noms de projets doivent être uniques dans toute l'application. diff --git a/doc/fr/editing-projects.markdown b/doc/fr/editing-projects.markdown new file mode 100644 index 00000000..67f8a0db --- /dev/null +++ b/doc/fr/editing-projects.markdown @@ -0,0 +1,16 @@ +Modifier des projets +================ + +Les projets peuvent être renommés et désactivés à tout moment. + +Pour renommer un projet, il suffit de cliquer sur le lien « Modifier un projet » sur la gauche. + + + +- Les dates de début et de fin sont utilisées pour créer le diagramme de Gantt du projet +- La description est visible en infobulle sur le tableau et sur la page qui liste les projets +- Les administrateurs et administrateurs de projets peuvent convertir un projet privé en projet multi-utilisateur en décochant la case « Projet privé ». +- Vous pouvez également convertir un projet multi-utilisateur en projet privé. + +Remarque : quand vous rendez un projet privé, tous les utilisateurs existants auront accès au projet. Ajustez la liste des utilisateurs selon vos besoins. + diff --git a/doc/fr/gantt-chart-projects.markdown b/doc/fr/gantt-chart-projects.markdown new file mode 100644 index 00000000..f2ac40ac --- /dev/null +++ b/doc/fr/gantt-chart-projects.markdown @@ -0,0 +1,17 @@ +Diagramme de Gantt pour tous les projets +============================ + +Le but de ce diagramme de Gantt est d'afficher une vue d'ensemble de tous les projets basée sur les dates de début et de fin. + +- Ce diagramme de Gantt est disponible dans la section de gestion du projet +- Seuls les administrateurs et administrateurs de projet peuvent accéder à cette section +- Les administrateurs de projet ne verront que les projets dans lesquels il y a des membres +- Les objets privés ne sont pas affichés dans ce graphique + + + +- La **date de début** et la **date de fin** des projets est utilisée pour construire le graphique +- Les barres horizontales peuvent être redimensionnées et déplacées latéralement avec votre souris +- Il n'y a pas de glisser-déposer vertical +- Les barres de projet sont affichées en noir quand il n'y a ni date de début ni date de fin définies +- L'infobulle affiche la liste des gestionnaires de projets et les membres ordinaires diff --git a/doc/fr/gantt-chart-tasks.markdown b/doc/fr/gantt-chart-tasks.markdown new file mode 100644 index 00000000..73053ed2 --- /dev/null +++ b/doc/fr/gantt-chart-tasks.markdown @@ -0,0 +1,20 @@ +Diagramme de Gantt pour les tâches +====================== + +Le but de ce diagramme de Gantt est de montrer une vue d'ensemble du temps utilisé en fonction de l'ensemble des tâches d'un projet donné. + +- Le diagramme de Gantt est disponible depuis le « sélecteur de vue » +- Seuls les gestionnaires de projet peuvent accéder à cette section + + + +- La **date de début** et la **date de fin** des tâches sont utilisées pour créer le graphique +- Les tâches peuvent être redimensionnées et déplacées horizontalement avec votre souris +- Il n'y a pas de glisser-déposer vertical +- La barre est de la même couleur que la tâche +- Chaque barre affiche un niveau de progression en pourcentage, qui est calculé en utilisant la position de la colonne dans le tableau +- Pour correspondre au modèle du Kanban, les tâches peuvent être ordonnées suivant leur position dans le tableau ou suivant les dates de début +- Les nouvelles tâches crées avec cette vue seront affichées sur le tableau en position 1 de la première colonne +- Les tâches sont affichées en noir quand il n'existe ni date de début ni date d'échéance définies + + diff --git a/doc/fr/project-permissions.markdown b/doc/fr/project-permissions.markdown new file mode 100644 index 00000000..9e21e1ad --- /dev/null +++ b/doc/fr/project-permissions.markdown @@ -0,0 +1,49 @@ +Permissions des projets +=================== + +Deux sortes d'utilisateurs sont en charge d'un projet : les **gestionnaires de projet** et les **membres du projet**. + +- Les gestionnaires de projet peuvent gérer la configuration du projet et accéder aux rapports. +- Les membres du projet ne peuvent effectuer que des opérations de base (créer ou déplacer des tâches). + +Quand vous créez un nouveau projet, le statut de gestionnaire de projet vous est automatiquement attribué. + +Les administrateurs de Kanboard peuvent accéder à tout mais ils ne sont pas nécessairement gestionnaires de projet ni membres du projet. **Ces permissions sont définies au niveau du projet**. + +Permissions selon chaque rôle +------------------------- + +### Membres du projet + +- Utiliser le tableau (créer, déplacer et modifier les tâches) +- Supprimer seulement les tâches créées par eux-mêmes + +### Gestionnaires du projet + +- Utiliser le tableau +- Configurer le projet +- Partager, renommer, dupliquer et désactiver le projet +- Gérer les swimlanes, les catégories, colonnes et utilisateurs +- Modifier les actions automatisées +- Exporter en CSV +- Supprimer les tâches de n'importe quel membre du projet +- Accéder à la section analytique + +Ils ne **peuvent pas supprimer un projet**. + +Gérer les utilisateurs et les permissions +---------------------------- + +Pour définir les rôles dans un projet, allez sur la page de **configuration de projet** puis cliquez sur **Gestion des utilisateurs**. + +### Gestion des utilisateurs + + + +C'est l'endroit où vous pouvez choisir de nouveaux membres, modifier leur rôle ou interrompre l'accès d'un utilisateur. + +### Permission générale + +Si vous choisissez d'autoriser tout le monde (tous les utilisateurs de Kanboard), le projet est considéré comme public. + +Cela signifie qu'il n'y a plus de rôle de gestionnaire de projet. Les permissions par utilisateur ne peuvent pas s'appliquer. diff --git a/doc/fr/sharing-projects.markdown b/doc/fr/sharing-projects.markdown new file mode 100644 index 00000000..0d2df7aa --- /dev/null +++ b/doc/fr/sharing-projects.markdown @@ -0,0 +1,37 @@ +Partager des tableaux et des tâches +======================== + +Par défaut, les tableaux sont privés, mais il est possible de rendre un tableau public. + +Un tableau public ne **peut pas être modifié, il est en lecture seule**. +Son accès est protégé par un jeton aléatoire, seules les personnes qui ont la bonne URL peuvent voir le tableau. + +Les tableaux publics sont automatiquement réactualisés toutes les minutes. +Les détails des tâches sont disponibles en lecture seule. + +Exemples d'utilisation : + +- Partager son tableau avec quelqu'un qui ne fait pas partie de votre organisation / entreprise / groupe +- Afficher le tableau sur un grand écran dans votre bureau + +Activer l'accès public +------------------- + +Choisissez votre projet, puis cliquez sur « Accès public » et enfin sur le bouton « Activer l'accès public ». + + + +Lorsque l'accès public est activé, plusieurs liens sont créés : + +- Affichage du tableau public +- Lien de souscription au fil RSS +- Lien d'abonnement à iCalendar + + + +Vous pouvez désactiver l'accès public à tout moment. + +À chaque fois que vous activez ou désactivez l'accès public, un nouveau jeton aléatoire est créé. +**Les liens précédents ne fonctionneront pas**. + + diff --git a/doc/fr/swimlanes.markdown b/doc/fr/swimlanes.markdown new file mode 100644 index 00000000..48772117 --- /dev/null +++ b/doc/fr/swimlanes.markdown @@ -0,0 +1,28 @@ +Swimlanes +========= + +Les *swimlanes* sont des séparations horizontales de votre tableau (pensez à des « couloirs » ou « lignes d'eau » dans une piscine). +Par exemple, cela peut servir à séparer les sorties des différentes versions d'un logiciel, à diviser vos tâches selon différents produits, équipes ou tout autre critère de votre choix. + +Tableau avec des swimlanes +-------------------- + + + +Gestion des swimlanes +------------------ + +- Tous les projets ont une swimlane par défaut. +- S'il existe plus d'une swimlane, le tableau les affichera toutes. +- Vous pouvez glisser-déposer les tâches d'une swimlane à l'autre. + +Pour configurer les swimlanes allez sur la page de **Configuration du projet** et choisissez la section **Swimlanes**. + + + +À partir de cet endroit, vous pouvez ajouter une nouvelle swimlane ou renommer celle qui existe par défaut. +Vous pouvez aussi désactiver et modifier la position des diverses swimlanes. + +- La swimlane par défaut est toujours en haut de tableau mais vous pouvez la cacher. +- Les swimlanes inactives ne sont pas affichées dans le tableau. +- **Supprimer une swimlane ne supprime pas les tâches qui lui sont assignées**, ces tâches seront transférées à la swimlane par défaut. diff --git a/doc/index.markdown b/doc/index.markdown index bc3cc23c..96069250 100644 --- a/doc/index.markdown +++ b/doc/index.markdown @@ -78,6 +78,7 @@ Using Kanboard - [RSS/Atom subscriptions](rss.markdown) - [Json-RPC API](api-json-rpc.markdown) - [Webhooks](webhooks.markdown) +- [Plugins](plugins.markdown) ### More @@ -104,6 +105,7 @@ Technical details - [Installation on Heroku](heroku.markdown) - [Example with Nginx + HTTPS + SPDY + PHP-FPM](nginx-ssl-php-fpm.markdown) - [Run Kanboard with Docker](docker.markdown) +- [Run Kanboard with Vagrant](vagrant.markdown) ### Configuration @@ -133,7 +135,6 @@ Technical details - [Coding standards](coding-standards.markdown) - [Running tests](tests.markdown) - [Build assets](assets.markdown) -- [Run Kanboard with Vagrant](vagrant.markdown) The documentation is written in [Markdown](http://en.wikipedia.org/wiki/Markdown). If you want to improve the documentation, just send a pull-request. diff --git a/doc/plugins.markdown b/doc/plugins.markdown new file mode 100644 index 00000000..7f32cf0a --- /dev/null +++ b/doc/plugins.markdown @@ -0,0 +1,263 @@ +Plugin Development +================== + +Note: The plugin API is considered alpha at the moment. + +Plugins are useful to extend the core functionalities of Kanboard, adding features, creating themes or changing the default behavior. + +Plugin creators should specify explicitly the compatible versions of Kanboard. Internal code of Kanboard may change over the time and your plugin must be tested with new versions. + +Directory structure +------------------- + +Plugins are stored in the `plugins` subdirectory. An example of a plugin directory structure: + +```bash +plugins +└── Budget <= Plugin name + ├── Asset <= Javascript/CSS files + ├── Controller + ├── LICENSE <= Plugin license + ├── Locale + │ ├── fr_FR + │ ├── it_IT + │ ├── ja_JP + │ └── zh_CN + ├── Model + ├── Plugin.php <= Plugin registration file + ├── README.md + ├── Schema <= Database migrations + ├── Template + └── Test <= Unit tests +``` + +Only the registration file `Plugin.php` is required. Other folders are optionals. + +The first letter of the plugin name must be capitalized. + +Plugin registration file +------------------------ + +Kanboard will scan the directory `plugins` and load automatically everything under this directory. The file `Plugin.php` is used to load and register the plugin. + +Example of `Plugin.php` file (`plugins/Foobar/Plugin.php`): + +```php +<?php + +namespace Plugin\Foobar; + +use Core\PluginBase; + +class Plugin extends PluginBase +{ + public function initialize() + { + $this->template->hook->attach('layout:head', 'theme:layout/head'); + } +} +``` + +This file should contains a class `Plugin` defined under the namespace `Plugin\Yourplugin` and extends `Core\PluginBase`. + +The only required method is `initialize()`. This method is called for each request when the plugin is loaded. + +Plugin methods +-------------- + +Available methods from `PluginBase`: + +- `initialize()`: Executed when the plugin is loaded +- `getClasses()`: Return all classes that should be stored in the dependency injection container +- `on($event, $callback)`: Listen on internal events + +Your plugin registration class also inherit from `Core\Base`, that means you can access to all classes and methods of Kanboard easily. + +This example will fetch the user #123: + +```php +$this->user->getById(123); +``` + +Template hooks +-------------- + +Template hooks allow to add new content in existing templates. + +Example to add new content in the dashboard sidebar: + +```php +$this->template->hook->attach('dashboard:sidebar', 'myplugin:dashboard/sidebar'); +``` + +This call is usually defined in the `initialize()` method. +The first argument is 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 name without prefix are core templates. + +List of template hooks: + +- `dashboard:sidebar` +- `config:sidebar` +- `export:sidebar` +- `layout:head` +- `layout:top` +- `layout:bottom` +- `project:dropdown` +- `project-user:sidebar` +- `task:sidebar:information` +- `task:sidebar:actions` +- `user:sidebar:information` +- `user:sidebar:actions` + +Other template hooks can be added if necessary, just ask on the issue tracker. + +Template overrides +------------------ + +Any templates defined in the core can be overrided. By example, you can redefine the default layout or change email notifications. + +Example of template override: + +```php +$this->template->setTemplateOverride('header', 'theme:layout/header'); +``` + +The first argument is the original template name and the second argument the template to use as replacement. + +Listen on events +---------------- + +Kanboard use internal events and your plugin can listen and perform actions on these events. + +```php +$this->on('session.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 ACL +---------- + +Kanboard use a custom access list for privilege separations. Your extension can add new rules: + +```php +$this->acl->extend('project_manager_acl', array('mycontroller' => '*')); +``` + +- The first argument is the ACL name +- The second argument are the new rules + + Syntax to include only some actions: `array('controller' => array('action1', 'action2'))` + + Syntax to include all actions of a controller: `array('controller' => '*')` + + Everything is lowercase + +List of ACL: + +- `public_acl`: Public access without authentication +- `project_member_acl`: Project member access +- `project_manager_acl`: Project manager access +- `project_admin_acl`: Project Admins +- `admin_acl`: Administrators + +Plugin Translations +------------------- + +Plugin can be translated in the same way the rest of the application. You must load the translations yourself when the session is created: + +```php +$this->on('session.bootstrap', function($container) { + Translator::load($container['config']->getCurrentLanguage(), __DIR__.'/Locale'); +}); +``` + +The translations must be stored in `plugins/Myplugin/Locale/xx_XX/translations.php`. + +Dependency Injection Container +------------------------------ + +Kanboard use Pimple, a simple PHP Dependency Injection Container. However, Kanboard can register any class in the container easily. + +Those classes are available everywhere in the application and only one instance is created. + +Here an example to register your own models in the container: + +```php +public function getClasses() +{ + return array( + 'Plugin\Budget\Model' => array( + 'HourlyRate', + 'Budget', + ) + ); +} +``` + +Now, if you use a class that extends from `Core\Base`, you can access directly to those class instance: + +```php +$this->hourlyRate->remove(123); +$this->budget->getDailyBudgetBreakdown(456); + +// It's the same thing as using the container: +$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. + +Schema migrations +----------------- + +Kanboard execute database migrations automatically for you. Migrations must be stored in a folder **Schema** and the filename must be the same as the database driver: + +```bash +Schema +├── Mysql.php +├── Postgres.php +└── Sqlite.php +``` + +Each file contains all migrations, here an example for Sqlite: + +```php +<?php + +namespace Plugin\Something\Schema; + +const VERSION = 1; + +function version_1($pdo) +{ + $pdo->exec('CREATE TABLE IF NOT EXISTS something ( + "id" INTEGER PRIMARY KEY, + "project_id" INTEGER NOT NULL, + "something" TEXT, + FOREIGN KEY(project_id) REFERENCES projects(id) ON DELETE CASCADE + )'); +} +``` + +- The constant `VERSION` is the last version of your schema +- Each function is a migration `version_1()`, `version_2()`, etc... +- A `PDO` instance is passed as first argument +- Everything is executed inside a transaction, if something doesn't work a rollback is performed and the error is displayed to the user + +Kanboard will compare the version defined in your schema and the version stored in the database. If the versions are different, Kanboard will execute one by one each migration until to reach the last version. + +Examples of plugins +------------------- + +- Budget planning: https://github.com/kanboard/plugin-budget +- Theme plugin sample: https://github.com/kanboard/plugin-example-theme diff --git a/doc/screenshots.markdown b/doc/screenshots.markdown index 419de412..95972405 100644 --- a/doc/screenshots.markdown +++ b/doc/screenshots.markdown @@ -22,4 +22,4 @@ On Mac OS X, you can use those shortcuts to take screenshots: There are also several third-party applications that can be used to take screenshots with annotations and shapes. -**Note: This feature doesn't works with all browsers.** It doesn't work with Safari due to this bug: https://bugs.webkit.org/show_bug.cgi?id=49141 +**Note: This feature doesn't work with all browsers.** It doesn't work with Safari due to this bug: https://bugs.webkit.org/show_bug.cgi?id=49141 diff --git a/doc/subtasks.markdown b/doc/subtasks.markdown index 3c9e8350..e1acd98c 100644 --- a/doc/subtasks.markdown +++ b/doc/subtasks.markdown @@ -40,5 +40,5 @@ Subtask timer - Each time a subtask is in progress, the timer is also started. The timer can be started and stopped at any time. - The timer records the time spent on the subtask automatically. You can also change manually the value of the time spent field when you edit a subtask. - The time calculated is rounded to the nearest quarter. This information is recorded in a separate table. -- The task time spent is updated automatically according to the sum of all subtasks time spent. +- The task time spent and time estimated are updated automatically according to the sum of all subtasks. |