10 Commits
v0.2 ... v1.1.3

8 changed files with 445 additions and 50 deletions

18
Asset/css/qualkard.css Normal file
View File

@@ -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% */

View File

@@ -0,0 +1,99 @@
<?php
namespace Kanboard\Plugin\QualKard\Controller;
use Kanboard\Controller\BaseController;
use Kanboard\Core\Controller\AccessForbiddenException;
use Kanboard\Plugin\QualKard\Helper\QualKardHelper;
/**
* QualKard board actions, posted from the project Integrations page: set up the study board, reset
* all cards, or disable. Project-manager gated (the restructure is destructive).
*/
class QualKardController extends BaseController
{
/**
* Turn this project into a study board: rename the first 7 columns to the standard names (create
* or delete to reach exactly 7), move every card to Drafts, store the column roles, reset all
* cards to unread + armed-inert, and enable. Once-per-conversion, explicit + confirmed.
*/
public function setup()
{
$project = $this->authorize();
$helper = new QualKardHelper($this->container);
$names = array('Drafts', 'Study', 'Hairy', 'Hard', 'Medium', 'Easy', 'Done');
$columns = $this->columnModel->getAll($project['id']); // position-ordered rows
$ids = array();
for ($i = 0; $i < 7; $i++) {
if (isset($columns[$i])) {
$this->columnModel->update($columns[$i]['id'], $names[$i]);
$ids[$i] = (int) $columns[$i]['id'];
} else {
$ids[$i] = (int) $this->columnModel->create($project['id'], $names[$i]);
}
}
// Move every card to Drafts BEFORE deleting extras -- remove() is a raw DELETE (tasks cascade).
foreach ($this->taskFinderModel->getAll($project['id']) as $task) {
$this->taskPositionModel->movePosition($project['id'], $task['id'], $ids[0], 1, $task['swimlane_id'], false);
}
for ($i = 7, $n = count($columns); $i < $n; $i++) {
$this->columnModel->remove($columns[$i]['id']);
}
$roles = array('draft', 'study', 'hairy', 'hard', 'medium', 'easy', 'done');
foreach ($roles as $k => $role) {
$this->projectMetadataModel->save($project['id'], array('qualkard_col_'.$role => $ids[$k]));
}
$helper->resetAll($project['id']);
$this->projectMetadataModel->save($project['id'], array('qualkard_enabled' => 1));
$this->flash->success(t('QualKard study board is ready.'));
$this->redirectToIntegrations($project);
}
/**
* Reset every card on the board: unread, moved to Drafts, armed-inert. Keeps the columns.
*/
public function reset()
{
$project = $this->authorize();
(new QualKardHelper($this->container))->resetAll($project['id']);
$this->flash->success(t('All cards reset.'));
$this->redirectToIntegrations($project);
}
/**
* Disable QualKard on this board (non-destructive: leaves columns and cards as they are).
*/
public function disable()
{
$project = $this->authorize();
$this->projectMetadataModel->save($project['id'], array('qualkard_enabled' => 0));
$this->flash->success(t('QualKard disabled on this board.'));
$this->redirectToIntegrations($project);
}
// Project-manager gate + CSRF, shared by every action.
private function authorize()
{
$project = $this->getProject();
if (! $this->helper->user->hasProjectAccess('ProjectEditController', 'edit', $project['id'])) {
throw new AccessForbiddenException();
}
$this->checkCSRFForm();
return $project;
}
private function redirectToIntegrations(array $project)
{
$this->response->redirect($this->helper->url->to('ProjectViewController', 'integrations', array('project_id' => $project['id'])));
}
}

View File

@@ -3,6 +3,7 @@
namespace Kanboard\Plugin\QualKard\Helper; namespace Kanboard\Plugin\QualKard\Helper;
use Kanboard\Core\Base; use Kanboard\Core\Base;
use Kanboard\Model\TaskModel;
/** /**
* QualKard helper: the qualcard grading math (ported from Ruben's C program) plus the per-board gates. * QualKard helper: the qualcard grading math (ported from Ruben's C program) plus the per-board gates.
@@ -16,6 +17,11 @@ class QualKardHelper extends Base
{ {
const SCORE = array('hairy' => 0.0, 'hard' => 1.3, 'medium' => 3.0, 'easy' => 5.0); 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. * Running average. New card (unread, $old === null) seeds at N - 23%; otherwise the qualcard mean.
*/ */
@@ -80,6 +86,18 @@ class QualKardHelper extends Base
return array('label' => $pct.'%', 'class' => $class); 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? * Is QualKard enabled for this board?
* *
@@ -118,4 +136,111 @@ class QualKardHelper extends Base
{ {
return (int) $this->projectMetadataModel->get($project_id, 'qualkard_col_'.$role, 0); 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
* until the first grade arms it. QualKard never toggles recoreco_enabled again.
*
* @param int $task_id
* @param int $project_id
*/
public function arm($task_id, $project_id)
{
$this->taskMetadataModel->save($task_id, array(
'recoreco_enabled' => 1,
'recoreco_move' => 1,
'recoreco_target_column' => $this->col($project_id, 'study'),
'recoreco_trigger_column' => $this->col($project_id, 'done'),
'recoreco_trigger_invert' => 1,
'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');
}
/**
* Reset one card: move to Drafts, mark unread, arm inert, clear the due date.
*
* @param int $task_id
* @param int $project_id
*/
public function resetCard($task_id, $project_id)
{
$task = $this->taskFinderModel->getById($task_id);
if (empty($task)) {
return;
}
$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' => 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));
}
/**
* Reset every card on a board.
*
* @param int $project_id
*/
public function resetAll($project_id)
{
foreach ($this->taskFinderModel->getAll($project_id) as $task) {
$this->resetCard($task['id'], $project_id);
}
}
/**
* 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.
*
* @param int $task_id
* @param float $score
*/
public function grade($task_id, $score)
{
$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' => 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));
}
} }

View File

@@ -3,6 +3,7 @@
namespace Kanboard\Plugin\QualKard; namespace Kanboard\Plugin\QualKard;
use Kanboard\Core\Plugin\Base; use Kanboard\Core\Plugin\Base;
use Kanboard\Model\TaskModel;
/** /**
* QualKard -- flashcard spaced repetition on Kanboard cards. * QualKard -- flashcard spaced repetition on Kanboard cards.
@@ -17,7 +18,43 @@ class Plugin extends Base
{ {
public function initialize() public function initialize()
{ {
// Hooks are wired in later versions (setup on Integrations, the grade handler, the badge). $container = $this->container;
// Per-board setup/reset/disable on Settings -> Integrations.
$this->template->hook->attach('template:project:integrations', 'qualKard:project/integration');
// 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;
}
}
});
// 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() public function getHelpers()
@@ -44,7 +81,7 @@ class Plugin extends Base
public function getPluginVersion() public function getPluginVersion()
{ {
return '0.2.0'; return '1.1.3';
} }
public function getPluginHomepage() public function getPluginHomepage()

161
README.md
View File

@@ -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 Turn a Kanboard board into a spaced-repetition flashcard deck. Each card is a flashcard --
real plugin. By itself it does only one trivial thing: it renders the word "Skeleton" at title is the prompt, description is the answer. You study a card, grade how it went by
the top of every page. It changes no data and runs no database migration. 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 QualKard is **opt-in per board**: installing it changes nothing until a project manager sets a
Settings -> Plugins (name, description, author, version, homepage, compatible version). specific board up under Settings -> Integrations. Setting a board up **restructures its
- A template hook (`template:layout:top`) that injects a template into the page. columns**, so it is a deliberate, confirmed action -- see below.
- 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 ## The study board
plugin needs custom CSS or JS.
- The standard plugin directory layout, with stub folders (`Controller/`, `Model/`, Setting a board up gives it exactly seven columns, each with a fixed role:
`Schema/`, `Locale/`, `Test/`) ready to grow into.
```
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 ## Requirements
- Kanboard >= 1.2.0 - 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 ## 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/`. Then, on the board you want to study:
2. Reload any page. The word "Skeleton" appears at the top.
3. Confirm it under Settings -> Plugins.
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).
``` ## How it stores data
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 to fork this into a new plugin 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
1. Copy the folder and rename it, e.g. `plugins/MyPlugin/`. The folder name must match the date and RecoReco's per-card recurrence config. Uninstalling the plugin leaves that metadata
namespace and start with a capital letter. harmlessly in place -- your columns and cards are untouched.
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.
## License ## License
AGPL-3.0. See 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.

12
Template/board/badge.php Normal file
View File

@@ -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>

View File

@@ -0,0 +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 ($enabled): ?>
<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">
<?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>

View File

@@ -1 +1 @@
QualKard v0.2 QualKard v1.1.3