Vikunja Tasks
The Vikunja tasks of the project you have open, in a panel of their own in the activity bar.
This is an unofficial extension, not made or endorsed by the Vikunja project. The icons are based on the Vikunja logo.
What it does
After signing in, the panel lists the open tasks of the project that goes with the folder you opened, grouped by state. The project's name at the top of the panel is also its selector. Grouping, order and automatic refresh are in the view's "…" menu, next to the new-task and refresh buttons.
Clicking a task unfolds it in place. It shows the description, or only the parts of it that matter in the task's state, and from there you can change the state, edit the task (title, priority, due date, assignees, description), send it back with a reason, finish it, copy its code or open it on the web. New task opens a form at the top of the list. The search box filters by code, title or text, and Only mine keeps the tasks assigned to you.
Below the list come the tasks finished in the chosen period, and any of them can be reopened. The status bar shows how many tasks are open; clicking it opens the panel.
While the panel is visible it reloads every 10 minutes. A hidden panel makes no calls and catches up when it is shown.
Signing in
- Open the Vikunja panel in the VS Code activity bar.
- Enter your server's final HTTPS address and sign in. If your account uses two-factor authentication, enter the code when prompted.
- Open Vikunja in another window of the same VS Code profile. Both windows share the session. Signing out in either window signs you out of both.
With Vikunja 2, the extension renews your session while you use it, until the server expires or revokes the session. If you signed in with a password before updating to 0.2.5, sign in again once to enable renewal.
Under the form there is a second way in, with an API token created in Vikunja under Settings > API tokens. Tick every permission when you create it. A token without the "other" group still works, but the panel cannot tell who is signed in, so it drops the "Only mine" filter and leaves your name out of its comments. A token without "Projects › projectusers" works too, without the list of people to assign tasks to. The rest is needed: Projects, Tasks, Labels, Task labels and Task comments, plus Project views and Project view tasks when states come from a Kanban view.
Which project
The first of these that gives a project wins:
- The project chosen in the panel's selector. It is remembered for the workspace, or for every empty window when no folder is open.
- The
vikunja.projects setting, which maps a folder name to a project id.
- The project whose title matches a folder name, ignoring case. Each open folder is tried by the folder right under
Projects (so ~/Projects/Hub UI/hub-ui reads as Hub UI) and then by its own name.
States
By default each state is a Vikunja label. The defaults are the ones I use (En revisión, Listo, falta publicar, En progreso, Sin arrancar); any other set goes in vikunja.states:
"vikunja.states": [
{ "label": "Blocked", "color": "charts.red" },
{ "label": "Review", "color": "charts.green", "returnTo": "Doing", "sections": ["How to test"] },
{ "label": "Doing", "color": "charts.yellow" },
{ "label": "To do" }
]
The order of the list is the order of the groups, and it also settles which state a task is in when it carries two of these labels: the first one listed wins. A task with none of them lands in the last state. name changes what the panel shows (the label is used otherwise), color takes a theme color id, and returnTo names the label that Send back moves a task to; only states with returnTo offer that action. sections lists description headings: a task in that state shows only those parts of its description, with the whole text one click away. To move tasks into a state, its label has to exist in Vikunja; the panel looks again if it was created on the web meanwhile.
With "vikunja.stateSource": "kanban" the states are the buckets of the project's first Kanban view instead, in board order, and moving a task moves it between buckets. A vikunja.states entry whose label matches a bucket title still lends that bucket its name, color, sections and returnTo.
Tasks carrying one of the vikunja.closedLabels (by default Cancelada and Descartada) are left out, since they are closed without being marked as done.
Editing a description
The panel edits descriptions as plain text: blank lines split paragraphs and lines starting with - make a list. A description written in the web editor loses its bold, links and other formatting once it is changed here, and the form says so. When only the title, priority, date or assignees change, the description is not sent at all and keeps its formatting.
Settings
| Setting |
Default |
What it sets |
vikunja.url |
empty |
Server pre-filled on the sign-in form |
vikunja.projects |
{} |
Folder name to project id, for folders whose name does not match a project |
vikunja.stateSource |
labels |
States from labels, or from the buckets of the Kanban view |
vikunja.states |
four labels |
The states, as described above |
vikunja.closedLabels |
Cancelada, Descartada |
Labels that hide a task |
vikunja.groupByState |
true |
Group by state, or one flat list |
vikunja.sort |
priority-desc |
Order inside each group |
vikunja.refreshMinutes |
10 |
Minutes between reloads; 0 reloads only by hand |
vikunja.doneWindowHours |
24 |
How far back the list of finished tasks reaches |
vikunja.commentOnDone |
true |
Leave a comment with your name and the date on a finished task |
vikunja.statusBar |
true |
Count of open tasks in the status bar |
The "…" menu and the period selector under the finished tasks write these same settings, so both places stay in step.
Building and testing
npm install
npm test # the model, without VS Code or a server
npm run package # vikunja-tasks-<version>.vsix
code --install-extension vikunja-tasks-0.2.4.vsix
npm run test:integration runs the extension inside VS Code against a throwaway Vikunja and writes to it: it signs in, moves, edits, creates, finishes and reopens tasks. Start that server with Docker first; the exact command is at the top of test/integration/run.ts. Set VSCODE_EXECUTABLE to the Code binary of a VS Code build to reuse it instead of downloading one.