Kanban Board Project

Hi all!

I'm Balint Magyar from Hungary and this summer I'll be working with Joplin on the kanban board plugin!

This proposal draws from the discussion in this GitHub issue and this forum thread, especially uxamanda 's designs and ideas. Big thanks!

Summary

This will be a plugin for Joplin, which allows notes in a notebook to be organized in a kanban board. The board itself is a special type of note, which, when opened will show the kanban interface in a new panel. On the board each item is a note and each column is a tag or some other property of the notes. Dragging notes between columns updates their properties automatically. On mobile and on clients which don't have the plugin installed, the board note simply shows as a static markdown table, so that tasks can still be viewed.

Please, let me know what you all think! These details are not set in stone, I'm open to any feedback from the community.

Project details

A board is essentially just a note, which contains the board settings, delimited like so:
```kanban ... ```
This code block will automatically be wrapped in a details tag, so it's hidden in the rendered output by default.

Creating boards

One way to create a new board is to create a new empty note, then type in the configuration manually. Of course, templates can be used as well, since these are still regular notes. But an easier, more user-friendly approach is also provided: two editor commands and corresponding items in the Tools menu. Each one creates a new note, pre-filled with a basic configuration; one using tags, the other notebooks.

Both of these skeleton-configurations would contain only two columns: "To Do", with backlog: true and "Done", with completed: true . Further customization could either be done by editing the YAML config, or the config buttons described in a later section.

Using the board

The board itself is rendered in a webview panel, to the right of the editor. This panel will open whenever a note with kanban settings is opened, and can be closed with an "X" button at the top of the panel, or by selecting a note which is neither a board, nor part of the currently opened board.

Here is a rough sketch of the proposed UI:

In each column a list of notes is shown. Each item in these lists displays the linked note's name and some extra information. For example, if the note contains a checklist, the number of checked boxes can be shown here. When clicking on an item, the corresponding note will open in the note editor, where it can be edited as usual. The board will remain open, because it detects that the opened note is part of the current kanban board.

This GIF demonstrates clicking and dragging notes on the board:

The rules for updating tags/notebooks

When dragging notes between columns, their properties are updated so that they only match the filters defined by the new column, according to the following rules:

  • When dropped into a column with tag: 'wip' from a column with tag: 'todo' , the note's todo tag is removed and wip is added.
  • When dropped into a column with notebookPath: 'Researching' , the note will be moved into the Researching notebook.
  • When dropped into a column with completed: true , the todo will be marked done.
  • Conversely, if a todo is taken from a column with completed: true , it will be marked not done
  • If a non-todo type note is dragged into a column with completed: true , completedTag or completedNotebook will be applied to it, if either is defined on the column. If not, it will be converted to a todo and marked done.
  • When dropped into a column with backlog: true , the behavior depends on whether tags or paths were used:
    • if notebookPath was used in the old column, the note dropped into backlog will be moved into the rootNotebookPath . If that's "/" , then it's moved to the settings note's notebook.
    • if tags were used, all tags, which are mentioned in other columns' settings, will be removed from the dropped note.

Optionally, buttons can be shown at the bottom of each column, which allow for new notes to be created which are automatically assigned the necessary tags/subnotebook. The newly created note is opened in the note editor, the same way as existing ones.

Configuration using the GUI

The different sections of the settings can be configured in different interfaces:

  • The board title is the same as the title of the settings note, but it can also be changed by double clicking it in the board view.
  • Filters can be edited in a popup-dialog, opened by clicking the settings icon next to the board title.
    main(2)
  • New columns can be added by clicking the plus button next to the board title. The new columns editor popup is opened immediately.
  • Column settings are edited in a popup-dialog, opened by double clicking the column header or via a right-click context menu. Here their name, color and filter criteria can all be configured. There is also a pair of left and right arrow buttons, which allow changing the order of columns.
    column(1)
    The buttons for moving the column are the simplest, but not the best solution. See extra goals for a drag and drop method.

Text configuration

Configuration format The configuration itself is defined in YAML and has the following format:
# Only notes which pass these filters will be shown on the board
filters:
  tag: 'Task'
  # Same, just allows multiple tags
  tags: 
    - 'Tasks'
  # For Todo type notes
  completed: false
  # Notebook whose notes should be used (recursive)
  rootNotebookPath: 'notebook/nested notebook'
columns: 
    # Backlog columns contain all notes which passed the filters,
    # but don't fit into any other column. 
  - backlog: true
    name: Backlog
	# Color of the column header. Can be any CSS color.
	# If not specified a predefined color scheme is used
	color: '#232323' 
  - tag: 'researching'
    name: Researching
  - tag: 'writing'
    name: Writing
  - tag: 'ready'
    name: Ready for review
	# Marks todos dropped here as done
  - completed: true
    # These only apply to notes dropped here, not todos
    completedTag: 'done'
	completedNotebook: 'done'
    name: Done
# Alternatively, columns can be created from notebookPaths instead of tags
	# Path relative to rootNotebookPath
  - notebookPath: 'todo'
    name: To Do
  - notebookPath: 'working'
    name: Working

rootNotebookPath defines which notebook's notes the board should contain. This path is always searched recursively. The default value is "." , which refers to the immediate parent notebook of the settings note.

To create a board which can sort notes from all notebooks "/" can be passed to rootNotebookPath . In this case all notebookPath s will refer to top-level notebooks.

Then, the filtered notes are sorted into columns, either according to tags or sub-notebooks, as defined in the columns section of the settings. If a note matches multiple columns during sorting, it's assigned to the first one. If a note doesn't match a single column, it's assigned to the column marked with backlog: true . If there's no such column, the note is ignored.

Static tables

To maintain maximum compatibility with clients, which don't support this plugin, a markdown table is generated in the settings note, which is kept up-to-date with the board. This way the state of the kanban board can at least be viewed from mobile, the command line or other clients. See the example below:

To Do Working Done
Submit final GSoC proposal Write proposal draft for kanban boards Create mockup for kanban boards
Go outside Do homework

Updates to the notes of a board of course won't be reflected in this table if not done from a client with the plugin installed. To know when the table was last updated a timestamp is added below the table, like so:
Last updated by desktop plugin on 1/2/2020

Working plan

I'm planning to write most of the functionality from scratch, so that the UX can be as close to Joplin's as possible. But I am planning to use dragula.js for the drag and drop feature between the columns, and js-yaml for parsing the settings.

1-2. Week

Building the drag and drop interface.

  1. Create layout
  2. Implement columns and drag and drop (with dummy notes, not updating anything yet)
  3. Create hooks, from which the notes can be updated when dropped

3-4. Week

Build settings parser.

  1. Write test cases
  2. Recognize setting notes
  3. Extract settings
  4. Find all notes to be placed on the board
  5. Sort notes into columns based on parsed settings

5-6. Week

Integrate components into Joplin.

  1. Subscribe to note changes via the data API and re-sort notes on each change
  2. Make note editor switch to selected item
  3. Connect to the hooks of the board UI to Update note properties when dragged
  4. Generate and insert tables from sorted notes

7-8. Week

Build configuration GUI.

  1. Create filters dialog
  2. Create dialog for editing settings
  3. Change board title with double click
  4. Add commands to create new board
  5. Update settings from GUI callbacks

9-10. Week

Testing and bug fixing.

Extra Goals

  • Reorganize columns by dragging
    • When right-clicking a column header, an option to start reordering could be shown. When in reordering mode columns can be dragged around and the note list is grayed out. The order is finalized with a button only visible in this mode.
  • Pin board on top of note list
    • always see the kanban board on the top of the list, instead of the last modified note
    • might not be possible with the current plugin API
  • Add search as a filter argument
    • Filter notes to be displayed by a search query
  • Add option to display board on the left of the note editor
    • Requires change in the plugin API
  • Preserve order of notes within columns
  • CodeMirror extension for syntax highlighting of settings
  • Generate Gantt charts from due dates of todos in backlog using mermaid

This post will serve as a live specification for this project, I will be updating it regularly based on your feedback.

31 Likes

Reserved for future content

Reserved for future content 2

Reserved for future content 3

Reserved for future content 4

Would it be out of scope to build a mobile view? I would consider easy read and write on mobile an essential feature.

1 Like

Hi! Unfortunately, that's not possible currently, since this will be implemented as a plugin, and plugins are not yet supported on mobile. I think it can happen sometime in the future, because it was one of the project ideas for this year's GSoC. As soon as mobile plugin support arrives, I'll make sure that this plugin works on there as well.

3 Likes

Just found the project right now. This looks very good indeed! But I am not sure how this could show on a phone? Maybe 3 tabs so that they show on the screen, and tapping on one tab opens the content on the screen in full?... Having Joplin on the phone is essential. I do not like doing this stuff on the phone though (maybe a bit too old? Hahahah), but I reckon that any feature that cannot be used on a phone will be dead very quickly.

Hi! As I've mentioned in the comment above, currently this will not work on mobile, as plugins are not supported there. The plugin will generate however a static markdown table, so you can view your board. It will look something like this:

3 Likes

While coding the handler which creates the board when a note with a configuration is opened, a question occured to me: how does it make more sense, when the board should be shown?

Let's say you have a notebook like so:

/
├─ tasks/
│  ├─ task1
│  ├─ task2
│  ├─ task3
├─ board note

Currently, the way to see the board would be to open the board note first, then you could open any of the tasks and the board would remain visible. But maybe the board should show up when you just open a task note, without first opening the board note?

I'm asking, because, to get the latter working with the current architecture is not trivial because somehow all boards have to be discovered at startup, then somehow checked each time a note is opened. I haven't looked much into it, just wanted to know first if it's worth it in the first place.

I suggest you do the easy thing first, so this:

Currently, the way to see the board would be to open the board note first, then you could open any of the tasks and the board would remain visible.

Then based on feedback and time remaining we might reconsider. Unless the decision has to be made now and there will be no way back.

1 Like

Hey Balint, this is amazing, thanks for putting in the work on this! Is there already a development version we can install and try out? I

2 Likes

Hey! Sorry for the late answer, I've been having exams this week at university.

Currently the UI is not yet functional, but by next week I expect to have it working. I'll be sure to post the first usable version here as soon as it's ready!

4 Likes

Gooid luck with the exams! I'll stay tuned and check for updates here. Super stoked!

1 Like

Good luck with your exams! Excited to see this project grow, let us know if you need testers!

If you are still interested in testing, this thread has a beta build and details on installing. Kanban Plugin Weekly Report - #15 by mablin7

Plugin released! :partying_face:

I've just released the plugin on npm, it is now available for installing! In my testing the plugin proved to be quite stable and with most of the major features done, I wanted the plugin to be as accessible as possible for people wanting to test it.

Please note, that this is not a final release! There are still bugs and missing features. The main purpose of this release is to test the plugin as much as possible.

9 Likes

It's amazing! I would love to test, but as a noob user, I installed the plugin from the plugin menu... and I don't know how to start a kanban. I tried ````kanban ... ```, but it's not working. I'm a long time user and use a few Joplin plugin, but I would be happy to help if I find a way to start a Kanban :wink:
Thanks again for the hard work!

How do I create a board? This does not work for me

```kanban
columns: 
  - 
    name: Backlog    
    backlog: true
  - 
    name: Working
    tag: wip
  - 
    name: Done
    completed: true
    tag: done
```​


Hey! Thanks for trying out the plugin!

First, make sure you've restarted Joplin after installing the plugin.

Then create a new empty note and paste in the config. Then switch to another note and back. This is a limitation right now, it will be improved in the future.

If still nothing happens, please locate your profile directory (Help > Open profile directory) and send me the kanban-logs.txt file. It doesn't contain any personal info, it's just the logs of this plugin.

1 Like