drop-to-Drafts un-studies one card (new badge, clear due, remove anchor -> inert) (v1.1.4)

Asset/css/qualkard.css

@@ -0,0 +1,18 @@
+/* QualKard mastery badge (under the card title on the board). */
+.qk-line {
+    margin-top: 2px;
+}
+
+.qk-badge {
+    display: inline-block;
+    padding: 0 6px;
+    border-radius: 3px;
+    color: #fff;
+    font-size: 0.85em;
+    font-weight: bold;
+}
+
+.qk-new  { background: #e6b800; } /* unread */
+.qk-low  { background: #c0392b; } /* < 50% */
+.qk-mid  { background: #27ae60; } /* 50-89% */
+.qk-high { background: #2980b9; } /* >= 90% */

Helper/QualKardHelper.php

@@ -17,6 +17,11 @@ class QualKardHelper extends Base
 {
     const SCORE = array('hairy' => 0.0, 'hard' => 1.3, 'medium' => 3.0, 'easy' => 5.0);
 
+    // Stored qualkard_avg value for an unread card. A literal, non-empty marker: it survives PHP's
+    // empty() -- which drops the numeric string "0" on save -- and stays distinct from a real average
+    // of 0 (a card graded hairy from new). Graded averages are stored with decimals for the same reason.
+    const UNREAD = 'new';
+
     /**
      * Running average. New card (unread, $old === null) seeds at N - 23%; otherwise the qualcard mean.
      */
@@ -81,6 +86,18 @@ class QualKardHelper extends Base
         return array('label' => $pct.'%', 'class' => $class);
     }
 
+    /**
+     * A stored qualkard_avg -> float, or null when the card is unread. The unread marker is the
+     * literal self::UNREAD; '' and null are also treated as unread for any card written before it.
+     *
+     * @param  string|null $raw
+     * @return float|null
+     */
+    private static function parseAvg($raw)
+    {
+        return ($raw === '' || $raw === null || $raw === self::UNREAD) ? null : (float) $raw;
+    }
+
     /**
      * Is QualKard enabled for this board?
      *
@@ -120,6 +137,18 @@ class QualKardHelper extends Base
         return (int) $this->projectMetadataModel->get($project_id, 'qualkard_col_'.$role, 0);
     }
 
+    /**
+     * Is FinanceBuddy enabled on this board? QualKard refuses to convert a FinanceBuddy board (its
+     * restructure would wreck the finance columns).
+     *
+     * @param  int $project_id
+     * @return bool
+     */
+    public function fbEnabled($project_id)
+    {
+        return (int) $this->projectMetadataModel->get($project_id, 'financebuddy_enabled', 0) === 1;
+    }
+
     /**
      * Write the inert RecoReco config for a card: move-mode to Study, fire from anywhere but Done,
      * daily (innocuous -- QualKard sets the due date on each grade), anchor 0 so RecoReco skips it
@@ -139,6 +168,13 @@ class QualKardHelper extends Base
             'recoreco_frequency' => 'daily',
             'recoreco_anchor' => 0,
         ));
+
+        // QualKard adopts the card as a fresh flashcard, so wipe any stale RecoReco copy lineage. A
+        // card that was a RecoReco duplicate carries recoreco_clone/recoreco_source; left in place it
+        // makes an armed QualKard card look like a copy (yellow icon, "cannot be made recurring"
+        // modal) while the cron still moves it. Removing them makes it a clean move-mode template.
+        $this->taskMetadataModel->remove($task_id, 'recoreco_clone');
+        $this->taskMetadataModel->remove($task_id, 'recoreco_source');
     }
 
     /**
@@ -156,7 +192,7 @@ class QualKardHelper extends Base
         }
 
         $this->taskPositionModel->movePosition($project_id, $task_id, $this->col($project_id, 'draft'), 1, (int) $task['swimlane_id'], false);
-        $this->taskMetadataModel->save($task_id, array('qualkard_avg' => '')); // '' = unread
+        $this->taskMetadataModel->save($task_id, array('qualkard_avg' => self::UNREAD)); // brand-new card
         $this->arm($task_id, $project_id);
         $this->db->table(TaskModel::TABLE)->eq('id', $task_id)->update(array('date_due' => 0));
     }
@@ -173,6 +209,25 @@ class QualKardHelper extends Base
         }
     }
 
+    /**
+     * Surgically un-study ONE card that the user dropped back into Drafts: wipe its mastery to
+     * unread, clear the due date, and make it inert to RecoReco. Unlike resetCard() this does not
+     * move or re-arm the card (it is already in Drafts and already armed) -- a lighter, per-card
+     * counterpart to the board-wide Reset.
+     *
+     * The anchor is REMOVED, not saved as 0: Kanboard's metadata save drops the string "0" (empty()),
+     * which would leave the old positive anchor in place and let RecoReco pull the card back out of
+     * Drafts on the next cron. A removed key reads back as the default 0, so RecoReco skips it.
+     *
+     * @param int $task_id
+     */
+    public function park($task_id)
+    {
+        $this->taskMetadataModel->save($task_id, array('qualkard_avg' => self::UNREAD)); // mastery -> new
+        $this->taskMetadataModel->remove($task_id, 'recoreco_anchor');                   // -> inert
+        $this->db->table(TaskModel::TABLE)->eq('id', $task_id)->update(array('date_due' => 0));
+    }
+
     /**
      * Grade a card by a score (a grade column's value): update the running average, compute the next
      * due date, and arm the anchor. RecoReco moves the card from here.
@@ -182,15 +237,29 @@ class QualKardHelper extends Base
      */
     public function grade($task_id, $score)
     {
-        $raw = $this->taskMetadataModel->get($task_id, 'qualkard_avg', '');
-        $old = ($raw === '' || $raw === null) ? null : (float) $raw;
+        $raw = $this->taskMetadataModel->get($task_id, 'qualkard_avg', self::UNREAD);
+        $old = self::parseAvg($raw);
         $avg = self::nextAverage($old, $score);
         $due = self::dueFrom($avg);
 
+        // Store with decimals so an exact 0 is "0.0000", never the empty()-dropped "0".
         $this->taskMetadataModel->save($task_id, array(
-            'qualkard_avg' => (string) $avg,
+            'qualkard_avg' => sprintf('%.4f', $avg),
             'recoreco_anchor' => $due,
         ));
         $this->db->table(TaskModel::TABLE)->eq('id', $task_id)->update(array('date_due' => $due));
     }
+
+    /**
+     * The mastery badge (label + CSS class) for a card, from its stored average.
+     *
+     * @param  int $task_id
+     * @return array
+     */
+    public function cardBadge($task_id)
+    {
+        $raw = $this->taskMetadataModel->get($task_id, 'qualkard_avg', self::UNREAD);
+
+        return self::badge(self::parseAvg($raw));
+    }
 }

Plugin.php

@@ -3,6 +3,7 @@
 namespace Kanboard\Plugin\QualKard;
 
 use Kanboard\Core\Plugin\Base;
+use Kanboard\Model\TaskModel;
 
 /**
  * QualKard -- flashcard spaced repetition on Kanboard cards.
@@ -17,10 +18,48 @@ class Plugin extends Base
 {
     public function initialize()
     {
+        $container = $this->container;
+
         // Per-board setup/reset/disable on Settings -> Integrations.
         $this->template->hook->attach('template:project:integrations', 'qualKard:project/integration');
 
-        // (The grade handler and the badge are wired in later versions.)
+        // New card on a QualKard board -> reset it (unread, armed inert, moved to Drafts).
+        $this->hook->on('model:task:creation:aftersave', function ($task_id) use ($container) {
+            $helper = new \Kanboard\Plugin\QualKard\Helper\QualKardHelper($container);
+            $task = $container['taskFinderModel']->getById($task_id);
+            if (! empty($task) && $helper->isEnabled($task['project_id'])) {
+                $helper->resetCard($task_id, (int) $task['project_id']);
+            }
+        });
+
+        // Card dragged INTO a grade column -> grade it (RecoReco then handles the movement). The
+        // plugin on() wrapper drops the event, so we subscribe on the dispatcher to get the TaskEvent.
+        $this->dispatcher->addListener(TaskModel::EVENT_MOVE_COLUMN, function ($event) use ($container) {
+            $task = $event['task'];
+            $helper = new \Kanboard\Plugin\QualKard\Helper\QualKardHelper($container);
+            if (! $helper->isEnabled($task['project_id'])) {
+                return;
+            }
+            $dst = (int) $event['dst_column_id'];
+            foreach (array('hairy', 'hard', 'medium', 'easy') as $role) {
+                if ($dst === $helper->col($task['project_id'], $role)) {
+                    $helper->grade($task['id'], \Kanboard\Plugin\QualKard\Helper\QualKardHelper::SCORE[$role]);
+                    return;
+                }
+            }
+
+            // Dropped back into Drafts -> surgically un-study this one card (new badge, no due, inert).
+            if ($dst === $helper->col($task['project_id'], 'draft')) {
+                $helper->park($task['id']);
+            }
+        });
+
+        // Mastery badge under the card title on the board, plus its stylesheet.
+        $this->template->hook->attach('template:board:private:task:after-title', 'qualKard:board/badge');
+        $this->template->hook->attach('template:board:public:task:after-title', 'qualKard:board/badge');
+        $this->hook->on('template:layout:css', array(
+            'template' => 'plugins/QualKard/Asset/css/qualkard.css',
+        ));
     }
 
     public function getHelpers()
@@ -47,7 +86,7 @@ class Plugin extends Base
 
     public function getPluginVersion()
     {
-        return '0.3.0';
+        return '1.1.4';
     }
 
     public function getPluginHomepage()

README.md

@@ -1,66 +1,133 @@
-# Skeleton -- a Kanboard plugin template
+# QualKard -- flashcard spaced repetition on your Kanboard
 
-A minimal, working Kanboard plugin that you copy and rename as the starting point for a
-real plugin. By itself it does only one trivial thing: it renders the word "Skeleton" at
-the top of every page. It changes no data and runs no database migration.
+Turn a Kanboard board into a spaced-repetition flashcard deck. Each card is a flashcard --
+title is the prompt, description is the answer. You study a card, grade how it went by
+dragging it into a grade column, and QualKard schedules when it should come back. Cards you
+find easy drift far into the future; hairy ones return tomorrow.
 
-## What it demonstrates
+The scheduling math is ported from Ruben's C program **qualcard** (the "K" here just marks the
+Kanboard port). The card movement -- bringing a card back when it falls due -- is done by the
+companion **RecoReco** plugin, so QualKard needs RecoReco installed and RecoReco's cron running.
 
-- A complete `Plugin.php` registration class with all the metadata Kanboard shows in
-  Settings -> Plugins (name, description, author, version, homepage, compatible version).
-- A template hook (`template:layout:top`) that injects a template into the page.
-- Asset hooks (`template:layout:css` and `template:layout:js`) that load a stylesheet and
-  a script. They are empty for now but prove the injection path works -- handy when a real
-  plugin needs custom CSS or JS.
-- The standard plugin directory layout, with stub folders (`Controller/`, `Model/`,
-  `Schema/`, `Locale/`, `Test/`) ready to grow into.
+QualKard is **opt-in per board**: installing it changes nothing until a project manager sets a
+specific board up under Settings -> Integrations. Setting a board up **restructures its
+columns**, so it is a deliberate, confirmed action -- see below.
+
+## The study board
+
+Setting a board up gives it exactly seven columns, each with a fixed role:
+
+```
+Drafts | Study | Hairy | Hard | Medium | Easy | Done
+```
+
+- **Drafts** -- where new and reset cards wait. A draft is inert: it never comes due on its own.
+- **Study** -- the review queue. RecoReco moves a card here when it falls due; this column is
+  itself the "overdue" backlog, so it can hold more than one day's worth.
+- **Hairy / Hard / Medium / Easy** -- the four grade columns. You review a card in Study, then
+  drag it into one of these to record how it went.
+- **Done** -- a resting place you drag a card to when you want it out of rotation. A card in Done
+  does not come back (it is the one column that does not re-trigger).
+
+## Studying
+
+1. Read the prompt (the card title) in **Study**, recall the answer, then open the card to check
+   the description.
+2. Drag the card into the grade column that matches how it went:
+
+   | Column | Meaning | Score |
+   |--------|---------|------:|
+   | Hairy  | no idea / wrong        | 0.0 |
+   | Hard   | right, but a struggle  | 1.3 |
+   | Medium | right, some effort     | 3.0 |
+   | Easy   | instant                | 5.0 |
+
+3. QualKard folds that score into the card's running average and sets the card's **due date** the
+   right number of days out (1 day for a hairy average, up to 11 for a mastered one). RecoReco
+   picks the card up from the grade column and, when it next falls due, moves it back to **Study**.
+
+You never edit a due date or move a card back yourself -- grading is the only action.
+
+### How the schedule is computed
+
+Each card keeps a running average of its scores. A brand-new card is seeded a little below its
+first score; after that the average is the mean of the old average and the new score. The average
+maps to an interval:
+
+| Average    | Interval |
+|------------|---------:|
+| <= 0.60    | 1 day    |
+| <= 1.35    | 2 days   |
+| <= 2.20    | 3 days   |
+| <= 3.05    | 5 days   |
+| <= 3.90    | 7 days   |
+| <= 4.92    | 9 days   |
+| otherwise  | 11 days  |
+
+So a card you keep grading Easy climbs toward an 11-day gap, while one you keep missing stays at a
+day or two until it sticks.
+
+## The mastery badge
+
+Each card shows a small badge under its title, on the board and at the top of the opened card:
+
+- **new** (yellow) -- an unread card that has never been graded.
+- a **percent** of mastery (the average as a fraction of 5), coloured **red** below 50%,
+  **green** through 89%, and **blue** at 90% and up.
 
 ## Requirements
 
 - Kanboard >= 1.2.0
+- The **RecoReco** plugin, installed and enabled, with its cron task running (RecoReco is what
+  moves due cards back to Study). QualKard's setup button stays disabled until RecoReco is present.
+
+QualKard refuses to set up a board that has **FinanceBuddy** enabled: the restructure would wreck a
+finance board's columns. Disable FinanceBuddy on that board first, or use a different board.
 
 ## Installation
 
-No build step and no dependencies.
+Copy this folder into your Kanboard installation as `plugins/QualKard/`. The directory name must be
+exactly `QualKard` (Kanboard derives the plugin namespace from the folder name). No build step and
+no database migration.
 
-1. Copy this folder into your Kanboard installation as `plugins/Skeleton/`.
-2. Reload any page. The word "Skeleton" appears at the top.
-3. Confirm it under Settings -> Plugins.
+Then, on the board you want to study:
 
-To uninstall, delete `plugins/Skeleton/`. Nothing else is left behind.
+1. Go to Settings -> Integrations.
+2. Under QualKard, click **Set up QualKard study board**, and confirm. This renames the board's
+   columns to the seven roles above (creating or removing columns to reach exactly seven) and moves
+   every existing card into Drafts.
+3. Make sure RecoReco's cron is running so due cards come back.
 
-## Directory layout
+From the same page you can later **Reset all cards** (send every card back to Drafts, unread) or
+**Disable QualKard machinery** (stop the automation without touching your columns or cards).
 
-```
-Skeleton/
-  Plugin.php              Registration and hook wiring (the only required file).
-  README.md
-  LICENSE                 AGPL-3.0.
-  Template/
-    layout/header.php     The visible "Skeleton" word.
-  Asset/
-    css/skeleton.css      Loaded via template:layout:css.
-    js/skeleton.js        Loaded via template:layout:js.
-  Controller/             Stub for future request handlers.
-  Model/                  Stub for future business logic / DB access.
-  Schema/                 Stub for future database migrations.
-  Locale/                 Stub for future translations (e.g. pt_BR/, fr_FR/).
-  Test/                   Stub for future unit tests.
-```
+## How it stores data
 
-## How to fork this into a new plugin
-
-1. Copy the folder and rename it, e.g. `plugins/MyPlugin/`. The folder name must match the
-   namespace and start with a capital letter.
-2. In `Plugin.php`, change the namespace from `Kanboard\Plugin\Skeleton` to
-   `Kanboard\Plugin\MyPlugin`.
-3. Update the metadata methods (`getPluginName`, `getPluginDescription`, `getPluginAuthor`,
-   `getPluginVersion`, `getPluginHomepage`, `getCompatibleVersion`).
-4. Update the hook target paths: the lowercase prefix in `'skeleton:layout/header'` and the
-   `plugins/Skeleton/Asset/...` asset paths must match the new plugin name.
-5. Replace `Template/layout/header.php` with your real template, or attach to a different
-   hook. See the Kanboard plugin hooks documentation for the full list of hook points.
+No database migration. The per-board enable flag and the seven column roles are stored in project
+metadata; each card's running average lives in task metadata, and QualKard writes the card's due
+date and RecoReco's per-card recurrence config. Uninstalling the plugin leaves that metadata
+harmlessly in place -- your columns and cards are untouched.
 
 ## License
 
 AGPL-3.0. See LICENSE.
+
+## More Kanboard plugins by Dr. Beco
+
+All free and AGPL-3.0, at [code.beco.cc](https://code.beco.cc/beco):
+
+- **[RecoReco](https://code.beco.cc/beco/RecoReco)** -- calendar-scheduled recurring cards (yearly,
+  monthly, weekly, daily), driven by the card due date.
+- **[FinanceBuddy](https://code.beco.cc/beco/FinanceBuddy)** -- attach a money value (debit/credit
+  and installments) to cards, shown on the card and totalled per column.
+- **[WorkspaceOrg](https://code.beco.cc/beco/WorkspaceOrg)** -- group your projects into personal
+  per-user workspaces, shown on a "My workspaces" dashboard page with a badge on each project.
+- **[OrganonTweaks](https://code.beco.cc/beco/OrganonTweaks)** -- an umbrella of small
+  quality-of-life board tweaks: remove an empty column, always show the comment icon, emphasize due
+  dates, extra search keywords and shared board filters, and more.
+- **[BulkMoveTasks](https://code.beco.cc/beco/BulkMoveTasks)** -- move every task from one board
+  column to another in a single action.
+- **[ShrinkVertically](https://code.beco.cc/beco/ShrinkVertically)** -- shrink vertically-collapsed
+  board columns so the horizontal scrollbar stays within reach.
+- **[TweakDrag](https://code.beco.cc/beco/TweakDrag)** -- board drag and touch niceties:
+  drag-to-scroll, a wider column gap, and smoother card dragging.

Template/board/badge.php

@@ -0,0 +1,12 @@
+<?php
+// Mastery badge under the card title on a QualKard board. Server-rendered (survives board refresh).
+// Yellow "new" for an unread card; otherwise a percent of 5, red (<50) / green (<90) / blue (>=90).
+if (empty($task['project_id']) || ! $this->QualKardHelper->isEnabled($task['project_id'])) {
+    return;
+}
+
+$b = $this->QualKardHelper->cardBadge($task['id']);
+?>
+<div class="qk-line">
+    <span class="qk-badge <?= $b['class'] ?>"><?= $this->text->e($b['label']) ?></span>
+</div>

Template/project/integration.php

@@ -1,28 +1,37 @@
+<?php
+// QualKard is inside the shared Integrations form, so the buttons use formaction (NOT nested <form>s)
+// to post to QualKard's own controller. Set up is destructive; disabling only stops the automation.
+$has = $this->QualKardHelper->hasRecoReco();
+$fb = $this->QualKardHelper->fbEnabled($project['id']);
+$enabled = $this->QualKardHelper->isEnabled($project['id']);
+$blocked = ! $has || $fb;
+?>
 <h3><i class="fa fa-graduation-cap fa-fw" aria-hidden="true"></i> <?= t('QualKard') ?></h3>
 <div class="listing">
-<?php if (! $this->helper->QualKardHelper->hasRecoReco()): ?>
+<?php if ($enabled): ?>
 
-    <p class="form-help"><?= t('QualKard needs the RecoReco plugin (its move engine). Install RecoReco to use QualKard.') ?></p>
-
-<?php elseif (! $this->helper->QualKardHelper->isEnabled($project['id'])): ?>
-
-    <p class="form-help"><?= t('Turn this project into a spaced-repetition study board. This restructures the columns to Drafts | Study | Hairy | Hard | Medium | Easy | Done and moves every card to Drafts.') ?></p>
-    <form method="post" action="<?= $this->url->href('QualKardController', 'setup', array('plugin' => 'QualKard', 'project_id' => $project['id'])) ?>" onsubmit="return confirm('<?= t('This restructures the board and moves all cards to Drafts. Continue?') ?>');">
-        <?= $this->form->csrf() ?>
-        <button type="submit" class="btn btn-blue"><?= t('Set up QualKard study board') ?></button>
-    </form>
+    <p class="form-help"><?= t('QualKard is enabled on this board.') ?></p>
+    <div class="form-actions">
+        <button type="submit" class="btn" formaction="<?= $this->url->href('QualKardController', 'reset', array('plugin' => 'QualKard', 'project_id' => $project['id'])) ?>" onclick="return confirm('<?= t('Reset every card to unread and move them to Drafts. Continue?') ?>');"><?= t('Reset all cards') ?></button>
+        <button type="submit" class="btn btn-red" formaction="<?= $this->url->href('QualKardController', 'disable', array('plugin' => 'QualKard', 'project_id' => $project['id'])) ?>"><?= t('Disable QualKard machinery') ?></button>
+    </div>
+    <p class="form-help"><?= t('"Disable" only stops the QualKard automation -- it does not restructure the board or touch your cards.') ?></p>
 
 <?php else: ?>
 
-    <p class="form-help"><?= t('QualKard is enabled on this board.') ?></p>
-    <form method="post" style="display:inline" action="<?= $this->url->href('QualKardController', 'reset', array('plugin' => 'QualKard', 'project_id' => $project['id'])) ?>" onsubmit="return confirm('<?= t('Reset every card to unread and move them to Drafts. Continue?') ?>');">
-        <?= $this->form->csrf() ?>
-        <button type="submit" class="btn"><?= t('Reset all cards') ?></button>
-    </form>
-    <form method="post" style="display:inline" action="<?= $this->url->href('QualKardController', 'disable', array('plugin' => 'QualKard', 'project_id' => $project['id'])) ?>">
-        <?= $this->form->csrf() ?>
-        <button type="submit" class="btn btn-red"><?= t('Disable QualKard') ?></button>
-    </form>
+    <p class="form-help">
+    <?php if (! $has): ?>
+        <?= t('QualKard needs the RecoReco plugin (its move engine).') ?>
+    <?php elseif ($fb): ?>
+        <?= t('Disabled while FinanceBuddy is enabled here -- QualKard would restructure the columns.') ?>
+    <?php else: ?>
+        <?= t('Set up turns this project into a study board: columns become Drafts | Study | Hairy | Hard | Medium | Easy | Done and every card moves to Drafts.') ?>
+    <?php endif ?>
+    </p>
+    <div class="form-actions"<?= $blocked ? ' style="opacity:0.5"' : '' ?>>
+        <button type="submit" class="btn btn-blue" <?= $blocked ? 'disabled="disabled"' : '' ?> formaction="<?= $this->url->href('QualKardController', 'setup', array('plugin' => 'QualKard', 'project_id' => $project['id'])) ?>" onclick="return confirm('<?= t('This restructures the board and moves all cards to Drafts. Continue?') ?>');"><?= t('Set up QualKard study board') ?></button>
+    </div>
 
 <?php endif ?>
 </div>
+<hr>

VERSION

@@ -1 +1 @@
-QualKard v0.3
+QualKard v1.1.4