vscode-kanban

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

ext install vscode-kanban

Or search for things like

vscode-kanban

How to use [↑]

How to execute [↑]

Press

F1

| Name | Description | command | | ---- | --------- | --------- | |

Kanban: Open Board ...

extension.kanban.openBoard

Settings [↑]

Open (or create) your

settings.json

.vscode

File >> Preferences >> Settings

Add a

kanban

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

| Name | Description | | ---- | --------- | |

canExecute

onExecute()

.vscode/vscode-kanban.js

(false)

cleanupExports

(true)

columns

exportOnSave

(false)

exportPath

.vscode

.vscode

globals

maxExportNameLength

48

noScmUser

(false)

noSystemUser

(false)

noTimeTrackingIfIdle

(false)

openOnStartup

(false)

simpleIDs

(true)

trackTime

(false)

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

Example graph:

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 [↑]

| Name | Description | Example | | ---- | --------- | --------- | |

assigned_to

assigned_to == "Marcel" or assigned_to == "Tanja"

cat

category

cat == "My Category"

category

category == "My Category"

description

description == "My description"

details

details == "My details"

id

id == "20180628102654_516121916_3f99e5abbe05420e1e5114d235ded3a2"

is_bug

(true)

Bug / issue

not is_bug

is_emerg

is_emergency

is_emerg or is_bug

is_emergency

(true)

Emergency

is_emergency or is_bug

is_issue

is_bug

is_bug or is_issue

is_note

(true)

Note / task

not is_note

is_task

is_note

not is_task

prio

priority

prio > 10

priority

priority > 10

no

(false)

no == false

now

now > 305413740

tag

tag == "by MK"

time

time > 305413740

title

title == "My card title"

type

type == "bug" or type == "emergency"

utc

utc > 305413740

yes

(true)

yes == true

Functions [↑]

| Name | Description | Example | | ---- | --------- | --------- | |

all(val, ...args)

all(assigned_to, "kloubert", "Marcel")

any(val, ...args)

any(assigned_to, "Tanja", "Marcel")

concat(...args)

concat(5, "9.1", 979) == "59.1979"

contains(val, searchFor: string)

contains(assigned_to, "Marcel")

debug(val, result? = true)

debug( concat(title, ": ", id) )

float(val)

float("5.979") == 5.979

int(val)

integer()

int("5.979") == 5

integer(val)

integer("5.979") == 5

is_after(date, alsoSame?: bool = false)

(true)

is_after("1979-09-05")

is_assigned_to(val)

(true)

is_assigned_to("Marcel Kloubert")

is_before(date, alsoSame?: bool = false)

(true)

is_before("2019-09-05")

is_cat(name: string)

is_category()

is_cat("My category")

is_category(name: string)

(true)

is_category("My category")

is_empty(val)

is_empty(assigned_to)

is_nan(val, asInt?: bool = false)

is_nan(prio)

is_nil(val)

(null)

(undefined)

is_nil(category)

is_older(days: number, alsoSameDay?: bool = false)

(true)

is_older(30)

is_younger(days: number, alsoSameDay?: bool = false)

(true)

is_younger(30)

norm(val)

normalize()

norm(" Marcel Kloubert ") == "marcel kloubert"

normalize(val)

normalize(" Marcel Kloubert ") == "marcel kloubert"

number(val)

float()

number("5.979") == 5.979

regex(val, pattern: string, flags?: string)

(true)

regex(assigned_to, "^(marcel\|tanja)", "i")

str(val)

str(59.79) == "59.79"

str_invoke(val, methods: string, ...args)

str_invoke(assigned_to, "trim,toLowerCase") == "marcel" or str_invoke(assigned_to, "indexOf", "Marcel") > -1

unix(val, isUTC?: bool = true)

time > unix("1979-09-05 23:09:00")

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

.vscode

// 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

.vscode/settings.json

(true)

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

This will run a simple workflow, which writes all required data to the

tag

.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": ""
        }
    }
}

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

.vscode/settings.json

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

You also can define an absolute path, like

D:/toggl/api-token.txt

/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": "",

        "project": 123
    }
}
}

Custom time tracking [↑]

For handling 'track time' events, you can create or edit a Node.js JavaScript file, called

vscode-kanban.js

.vscode

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

.vscode

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

Support and contribute [↑]

If you like the extension, you can support the project by sending a donation via PayPal to me.

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.