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 withtag: 'todo', the note'stodotag is removed andwipis 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,completedTagorcompletedNotebookwill 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
notebookPathwas used in the old column, the note dropped into backlog will be moved into therootNotebookPath. If that's"/", then it's moved to the settings note's notebook. - if
tagswere used, all tags, which are mentioned in other columns' settings, will be removed from the dropped note.
- if
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.
- 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.
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.
- Create layout
- Implement columns and drag and drop (with dummy notes, not updating anything yet)
- Create hooks, from which the notes can be updated when dropped
3-4. Week
Build settings parser.
- Write test cases
- Recognize setting notes
- Extract settings
- Find all notes to be placed on the board
- Sort notes into columns based on parsed settings
5-6. Week
Integrate components into Joplin.
- Subscribe to note changes via the data API and re-sort notes on each change
- Make note editor switch to selected item
- Connect to the hooks of the board UI to Update note properties when dragged
- Generate and insert tables from sorted notes
7-8. Week
Build configuration GUI.
- Create filters dialog
- Create dialog for editing settings
- Change board title with double click
- Add commands to create new board
- 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.
