https://rogerpenna.github.io/ultra-kanban-widget/
Getting Started with the Ultra Kanban Widget
Welcome! This guide will walk you through setting up and using the Ultra Kanban Widget to supercharge your Grist workflow. With this tool, you can visualize your data as a dynamic, interactive Kanban board.
This widget is multilingual, and new languages may be added in the future. For the purpose of this tutorial, we will proceed using English.
Section 1: Initial Setup (Making it Work in 4 Steps)
Before you can use the widget, you need to tell it how to read your data.
Step 1: Add the Widget to Your Page
- Add a new widget to your Grist page and select Custom.
- Choose to display the Full Document.
- In the widget options on the right, paste the following URL:
https://rogerpenna.github.io/ultra-kanban-widget/
You’ll likely see a message asking you to configure the widget.
Step 2: Choose Your Language
- Click the
Config button at the top right of the widget.
- Go to the “General, WIP & Sorting” tab.
- The first section is “Language Settings”. From the dropdown menu, select English. The configuration menu will instantly translate.
Step 3: Prepare Your Grist Table
Your Kanban board is based on the columns of a single Grist table. The most important column is the one that defines the “lanes” of your board.
- Ensure your table has a Choice or Text column that will represent the stages of your workflow (e.g., a column named “Status” with choices like “To Do”, “In Progress”, and “Done”). This will become your Kanban lanes.
Step 4: The Most Important Step - Map Your Kanban Column
- While still in the “General, WIP & Sorting” tab, find the “Main Kanban Column Mapping” section.
- Click the dropdown menu and select the column from your table that contains your workflow stages (e.g., your “Status” column).
- Click the blue “Save Settings” button at the bottom.
Congratulations! Your Kanban board should now appear, with columns matching the choices or values from the column you selected.
Section 2: Basic Usage
Now that your board is live, here’s how to use it:
- Move Cards: Simply click and drag any card from one lane to another. The data in your Grist table will update automatically.
- View & Edit Card Details: Click on any card to open a detailed “drawer” view on the right. Here you can see and edit all the fields related to that card. Click “Save” to update the record.
Section 3: Customizing Your Board (The Config Menu)
The real power of this widget lies in its customization options. Click Config to explore them.
Tab: “Fields by Lane”
This is a powerful feature: you can control exactly what information is visible for cards in each specific lane.
- First, select a lane from the dropdown at the top (e.g., “In Progress”).
- A table of all your fields will appear. For each field, you can set:
- On Card: Check this to make the field visible directly on the small card on the board.
- Card Pos#: Control the order of fields on the card (0 is the title).
- Visible Drawer: Check this to show the field in the detailed editing view.
- Editable Drawer: Check this to allow the field to be edited in the detailed view.
- Drawer Pos#: Control the order of fields in the detailed view.
Pro Tip: Use the “Replicate” button to copy the field settings from the currently selected lane to other lanes, saving you a lot of time!
Tab: “General, WIP & Sorting”
This tab controls the core logic of your board.
- Card Sorting Within Lanes: Set up to three rules to automatically sort cards within each lane (e.g., sort by “Priority” first, then by “Due Date”).
- Limits per Lane (WIP): Set a “Work-In-Progress” limit. For example, set “Max Allowed Cards” to 3 for the “In Progress” lane to prevent your team from working on too many tasks at once. The lane header will turn red if the limit is exceeded.
- Movement Restrictions: Check the box to only allow cards to be moved to the immediately adjacent lanes (e.g., from “To Do” to “In Progress”, but not directly to “Done”).
Tab: “Visuals”
Make the board your own! Here you can change:
- Layout (Center columns)
- Column and Card colors
- Enable or disable shadows on cards
- The overall background of the widget (solid color or a gradient)
- Default font colors for card titles and fields.
Tab: “Rules”
Automate your workflow with powerful rules that trigger when a card enters a lane.
Section 4: Saving Your Configuration
After making any changes in the Config menu, always remember to click the blue “Save Settings” button at the bottom right.
Enjoy your new, powerful Kanban board
Section 5: Advanced Features
Once you’ve mastered the basics, you can unlock even more power with these advanced configurations.
Advanced Card Sorting and Layout
In the “General, WIP & Sorting” tab, the card sorting section has a special third dropdown menu. Besides Ascending or Descending, you can set a field’s display type to Priority (highlight) or Due Date (highlight).
- How it works:
- Priority (highlight): Select this for a field that represents task priority (e.g., “High”, “Medium”, “Low”). The widget will display this field’s value in the top-right corner of the card for high visibility.
- Due Date (highlight): Select this for a date field. The widget will display its value in the bottom-right corner of the card.
- If you have applied Grist’s Conditional Formatting to these fields (for example, to color-code priorities or make an approaching due date turn red), that formatting will also be displayed directly on the card.
Pro Tip: For a powerful priority system, create a “Priority” column in Grist with choices like 1-Urgent, 2-Normal, 3-Low. In the Kanban sorting options, set it to sort Ascending and choose the Priority (highlight) display type. This will automatically place urgent tasks at the top of each lane and highlight them visually.
Creating Sub-tasks and Linked Processes with Rules
The “Create” rule in the “Rules” tab is a powerful automation tool that allows you to link processes across different tables. A common use case is creating a sub-task checklist for a main Kanban card.
Step 1: Prepare Your Sub-task Table
Before creating the rule, you need a separate Grist table (e.g., “Sub-tasks”) with at least these two essential columns:
- A Reference Column: Create a column of type
Reference that points back to your main Kanban table (e.g., a column named “Parent Task” referencing the “Projects” table). This is how the sub-task knows which main card it belongs to.
- A Status Column: Create a
Choice column to manage the sub-task’s own workflow (e.g., “Sub-task Status” with choices like “Pending” and “Completed”).
Pro Tip: Want to pull information from the parent card into the sub-task table? Use Grist’s dot notation in a formula column. For example, to see the parent card’s name, create a formula column in the “Sub-tasks” table with the formula: $Parent_Task.Name
Step 2: Configure the “Create” Rule
Now, go to the Kanban widget’s “Rules” tab. Let’s say you want to automatically create a set of sub-tasks whenever a project card enters the “In Progress” lane.
- For the “In Progress” lane, click “+ Add Rule” and select the type:
IF card enters THEN create in another table...
- Fill out the mapping fields that appear:
- Target Table: Select your “Sub-tasks” table from the dropdown. The fields below will now populate with columns from that table.
- Relation Field (Kanban card ID): This is the most important link. Choose the
Reference column you created in Step 1 (e.g., “Parent Task”). The widget will automatically fill this with the ID of the card that triggered the rule.
- Status/Lane Column (in Target): Choose the
Choice column from your sub-task table that holds its status (e.g., “Sub-task Status”).
- Initial Lane for New Card (in Target): A dropdown will show the choices from the status column you just selected. Choose the default status for newly created sub-tasks (e.g., “Pending”).
Step 3: Visualize Your Sub-tasks
You can now create a second Kanban widget on a new Grist page and point it to your “Sub-tasks” table. Use the “Sub-task Status” column as its main Kanban column.
Now, you have a complete system:
- When you drag a “Project” card to “In Progress” on your main board…
- A new sub-task card is automatically created in the “Pending” lane on your second board.
- You can manage the sub-task’s lifecycle on its own board, while it remains linked to the parent project card. This is perfect for managing complex projects with distinct sub-processes.
Roma invicta!