vscode-kanban

:warning: This version of the extension is deprecated and will be refactored: Read this for more information.

Kanban board for Visual Studio Code.

Table of contents

1. Install
2. How to use
   • How to execute
   • Settings
   • Markdown support
   • Diagrams and charts
   • Filter
     • Constants
     • Functions
   • Handle events
   • Time tracking
     • Simple time tracking
     • Toggl
     • Custom time tracking
3. Customization
   • Columns
   • CSS
4. Logs
5. Support and contribute
   • Contributors
6. Related projects
   • vscode-helpers

Install [↑]

Launch VS Code Quick Open (Ctrl + P), paste the following command, and press enter:

ext install vscode-kanban

Or search for things like vscode-kanban in your editor.

How to use [↑]

How to execute [↑]

Press F1 and enter one of the following commands:

Settings [↑]

Open (or create) your settings.json in your .vscode subfolder of your workspace or edit the global settings (File >> Preferences >> Settings).

Add a kanban section:

{
    "kanban": {
        "openOnStartup": true
    }
}

Markdown support [↑]

Card descriptions can be formatted with Markdown, which is parsed by Showndown library.

The extension uses the following settings:

{
    "completeHTMLDocument": false,
    "encodeEmails": true,
    "ghCodeBlocks": true,
    "ghCompatibleHeaderId": true,
    "headerLevelStart": 3,
    "openLinksInNewWindow": true,
    "simpleLineBreaks": true,
    "simplifiedAutoLink": true,
    "strikethrough": true,
    "tables": true,
    "tasklists": true
}

Code blocks are parsed by highlight.js and all provided languages are included and supported.

Diagrams and charts [↑]

Card descriptions can also include diagrams and charts, using a language parsed and rendered by mermaid.

Those diagram / chart descriptions has to be put into a Markdown code block, which uses mermaid as language:

Example graph:

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

Filter [↑]

Cards can be filtered by using a powerful language, provided by filtrex library.

Constants [↑]

Functions [↑]

For more functions, s. Expressions.

If a filter expression is invalid or its execution fails, a log entry will be written.

Handle events [↑]

For handling events, you can create a Node.js JavaScript file, called vscode-kanban.js, inside your .vscode subfolder of your workspace and start with the following skeleton (s. EventScriptModule interface):

// all 'args' parameters are based on
// 'EventScriptFunctionArguments' interface
// 
// s. https://mkloubert.github.io/vscode-kanban/interfaces/_workspaces_.eventscriptfunctionarguments.html

// use any Node.js 7 API, s. https://nodejs.org/
const fs = require('fs');
// use VSCode API, s. https://code.visualstudio.com/docs/extensionAPI/vscode-api
const vscode = require('vscode');

// [OPTIONAL]
// 
// Is raised after a CARD has been CREATED.
exports.onCardCreated = async (args) => {
    // args.data => s. https://mkloubert.github.io/vscode-kanban/interfaces/_boards_.cardcreatedeventdata.html

    // access a module of that extension
    // s. https://github.com/mkloubert/vscode-kanban/blob/master/package.json
    const FSExtra = args.require('fs-extra');

    // write own data to
    // 'tag' property of a card (args.tag)
    // 
    // also works in:
    // - onCardMoved()
    // - onCardUpdated()
    await args.setTag( 'Any JSON serializable data.' );    
};

// [OPTIONAL]
// 
// Is raised after a CARD has been DELETED.
exports.onCardDeleted = async (args) => {
    // args.data => s. https://mkloubert.github.io/vscode-kanban/interfaces/_boards_.carddeletedeventdata.html
};

// [OPTIONAL]
// 
// Is raised after a CARD has been MOVED.
exports.onCardMoved = async (args) => {
    // args.data => s. https://mkloubert.github.io/vscode-kanban/interfaces/_boards_.cardmovedeventdata.html
};

// [OPTIONAL]
// 
// Is raised after a CARD has been UPDATED.
exports.onCardUpdated = async (args) => {
    // args.data => s. https://mkloubert.github.io/vscode-kanban/interfaces/_boards_.cardupdatedeventdata.html
};

// [OPTIONAL]
// 
// Is raised after a column has been cleared.
exports.onColumnCleared = async (args) => {
    // args.data => s. https://mkloubert.github.io/vscode-kanban/interfaces/_boards_.columnclearedeventdata.html
};

// [OPTIONAL]
// 
// Is raised when an user clicks on a card's 'Execute' button.
// This requires global extension / workspace setting 'canExecute' to be set to (true).
exports.onExecute = async (args) => {
    // args => https://mkloubert.github.io/vscode-kanban/interfaces/_workspaces_.eventscriptfunctionarguments.html
    // args.data => s. https://mkloubert.github.io/vscode-kanban/interfaces/_boards_.executecardeventarguments.html
};

// [OPTIONAL]
// 
// Is raised when an user clicks on a card's 'Track Time' button.
// This requires global extension / workspace setting 'canTrackTime' to be set to (true).
exports.onTrackTime = async (args) => {
    // args => https://mkloubert.github.io/vscode-kanban/interfaces/_workspaces_.eventscriptfunctionarguments.html
    // args.data => s. https://mkloubert.github.io/vscode-kanban/interfaces/_boards_.tracktimeeventarguments.html
};


// [OPTIONAL]
// 
// Generic fallback function, if a function is not defined for an event.
exports.onEvent = async (args) => {
    // args.name => name of the event
    // args.data => object with event data  
};

Time tracking [↑]

Simple time tracking [↑]

Set the value of trackTime inside your .vscode/settings.json to (true):

{
    "kanban": {
        "trackTime": true
    }
}

This will run a simple workflow, which writes all required data to the tag property of the underlying card (s. .vscode/vscode-kanban.json).

Toggl [↑]

To use the build-in Toggl integration, you have to setup your personal API token, which can you find in your profile settings:

{
    "kanban": {
        "trackTime": {
            "type": "toggl",
            "token": "<YOUR-API-TOKEN>"
        }
    }
}

If you do not want (or if you not able) to save the token in the settings, you can define the path to a text file, which contains it.

For example, create a text file inside your home directory, like toggl.txt, and write the token there. After that, you must define the path of the text file in the settings (.vscode/settings.json):

{
    "kanban": {
        "trackTime": {
            "type": "toggl",
            "token": "toggl.txt"
        }
    }
}

You also can define an absolute path, like D:/toggl/api-token.txt or /home/mkloubert/toggl-api-token.txt.

For the case, your board belongs to a specific Toggl project and you know its ID, you can define it explicitly:

{
    "kanban": {
        "trackTime": {
            "type": "toggl",
            "token": "<API-TOKEN>",

            "project": 123
        }
    }
}

Custom time tracking [↑]

For handling 'track time' events, you can create or edit a Node.js JavaScript file, called vscode-kanban.js, inside your .vscode subfolder of your workspace and add the following function:

exports.onTrackTime = async (args) => {
    // args => https://mkloubert.github.io/vscode-kanban/interfaces/_workspaces_.eventscriptfunctionarguments.html
    // args.data => s. https://mkloubert.github.io/vscode-kanban/interfaces/_boards_.tracktimeeventarguments.html

    // use any Node.js 7 API, s. https://nodejs.org/
    const fs = require('fs');

    // use VSCode API, s. https://code.visualstudio.com/docs/extensionAPI/vscode-api
    const vscode = require('vscode');

    // access a module of that extension
    // s. https://github.com/mkloubert/vscode-kanban/blob/master/package.json
    const moment = args.require('moment');

    // options from the settings, s. below
    const OPTS = args.options;


    // start implement your workflow here
};

You also have to update the extension settings:

{
    "kanban": {
        "trackTime": {
            "type": "script",
            "options": {
                "MK": 239.79,
                "TM": "5979"
            }
        }
    }
}

Customization [↑]

Columns [↑]

An example of setting up custom column names:

{
    "kanban": {
        "columns": {
            "done": "Finished",
            "inProgress": "Work",
            "testing": "Currently Testing",
            "todo": "Ideas and TODOs"
        }
    }
}

CSS [↑]

If you want to style your board, you can create a file, called vscode-kanban.css, inside your .vscode sub folder of the underlying workspace or your home directory.

Have a look at the files board.css and style.css to get an idea of the CSS classes, that are used.

Logs [↑]

Log files are stored inside the .vscode-kanban/.logs subfolder of the user's home directory, separated by day.

Support and contribute [↑]

If you like the extension, you can support me at https://marcel.coffee

To contribute, you can open an issue and/or fork this repository.

To work with the code:

• clone this repository
• create and change to a new branch, like git checkout -b my_new_feature
• run npm install from your project folder
• open that project folder in Visual Studio Code
• now you can edit and debug there
• commit your changes to your new branch and sync it with your forked GitHub repo
• make a pull request

The complete API documentation can be found here.

Contributors [↑]

• Hans De Mulder
• Philippe Miossec
• Alvaro F. García

Related projects [↑]

vscode-helpers [↑]

vscode-helpers is a NPM module, which you can use in your own VSCode extension and contains a lot of helpful classes and functions.