QualKard: scaffold plugin from Skeleton + ported qualcard grading math (v0.2.0) t1

Asset/css/skeleton.css

@@ -1 +0,0 @@
-/* Skeleton plugin styles -- add CSS here. Loaded via template:layout:css. */

Asset/js/skeleton.js

@@ -1 +0,0 @@
-// Skeleton plugin script -- add JS here. Loaded via template:layout:js.

Helper/QualKardHelper.php

@@ -0,0 +1,121 @@
+<?php
+
+namespace Kanboard\Plugin\QualKard\Helper;
+
+use Kanboard\Core\Base;
+
+/**
+ * QualKard helper: the qualcard grading math (ported from Ruben's C program) plus the per-board gates.
+ *
+ * Scores per grade column: hairy=0.0, hard=1.3, medium=3.0, easy=5.0. The running average is
+ * M1 = (M0 + N)/2, with a new (unread) card seeded at N - 23%. The average maps to a review interval
+ * (qualcard grades G..A, 1..11 days). qualcard's H/same-day and the overdue decay are intentionally
+ * NOT ported: there is no "again now", and the Study column is itself the overdue backlog.
+ */
+class QualKardHelper extends Base
+{
+    const SCORE = array('hairy' => 0.0, 'hard' => 1.3, 'medium' => 3.0, 'easy' => 5.0);
+
+    /**
+     * Running average. New card (unread, $old === null) seeds at N - 23%; otherwise the qualcard mean.
+     */
+    public static function nextAverage($old, $score)
+    {
+        return $old === null ? ($score - 0.23 * $score) : (($old + $score) / 2.0);
+    }
+
+    /**
+     * Average -> review interval in days (qualcard grades G..A).
+     */
+    public static function intervalDays($avg)
+    {
+        if ($avg <= 0.60) {
+            return 1; // G
+        }
+        if ($avg <= 1.35) {
+            return 2; // F
+        }
+        if ($avg <= 2.20) {
+            return 3; // E
+        }
+        if ($avg <= 3.05) {
+            return 5; // D
+        }
+        if ($avg <= 3.90) {
+            return 7; // C
+        }
+        if ($avg <= 4.92) {
+            return 9; // B
+        }
+
+        return 11; // A
+    }
+
+    /**
+     * Next due timestamp: midnight, intervalDays() out.
+     */
+    public static function dueFrom($avg, $now = null)
+    {
+        $now = $now ?: time();
+
+        return strtotime('+'.self::intervalDays($avg).' days', strtotime('today', $now));
+    }
+
+    /**
+     * Mastery badge for a card's average: label + CSS class. null (unread) = "new" (yellow); otherwise
+     * a percent of 5, coloured red (<50) / green (<90) / blue (>=90).
+     *
+     * @param  float|null $avg
+     * @return array{label:string,class:string}
+     */
+    public static function badge($avg)
+    {
+        if ($avg === null) {
+            return array('label' => t('new'), 'class' => 'qk-new');
+        }
+
+        $pct = (int) round($avg / 5.0 * 100);
+        $class = $pct < 50 ? 'qk-low' : ($pct < 90 ? 'qk-mid' : 'qk-high');
+
+        return array('label' => $pct.'%', 'class' => $class);
+    }
+
+    /**
+     * Is QualKard enabled for this board?
+     *
+     * @param  int $project_id
+     * @return bool
+     */
+    public function isEnabled($project_id)
+    {
+        return (int) $this->projectMetadataModel->get($project_id, 'qualkard_enabled', 0) === 1;
+    }
+
+    /**
+     * Is the RecoReco plugin installed? (QualKard needs its move engine.)
+     *
+     * @return bool
+     */
+    public function hasRecoReco()
+    {
+        foreach ($this->container['pluginLoader']->getPlugins() as $plugin) {
+            if ($plugin->getPluginName() === 'RecoReco') {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * The column id stored for a board role ('draft', 'study', 'hairy', ... , 'done').
+     *
+     * @param  int    $project_id
+     * @param  string $role
+     * @return int
+     */
+    public function col($project_id, $role)
+    {
+        return (int) $this->projectMetadataModel->get($project_id, 'qualkard_col_'.$role, 0);
+    }
+}

Plugin.php

@@ -1,35 +1,40 @@
 <?php
 
-namespace Kanboard\Plugin\Skeleton;
+namespace Kanboard\Plugin\QualKard;
 
 use Kanboard\Core\Plugin\Base;
 
+/**
+ * QualKard -- flashcard spaced repetition on Kanboard cards.
+ *
+ * Each card is a flashcard (title = prompt, description = answer). You grade a due card by dragging
+ * it into a grade column (Hairy/Hard/Medium/Easy); QualKard turns the grade into a due date via the
+ * qualcard average + interval, and the companion RecoReco plugin does all the card movement.
+ *
+ * Requires RecoReco (the move engine). Grading math is ported from Ruben's C program "qualcard".
+ */
 class Plugin extends Base
 {
     public function initialize()
     {
-        // 1. Render a visible word at the top of every page (the demo output).
+        // Hooks are wired in later versions (setup on Integrations, the grade handler, the badge).
-        $this->template->hook->attach('template:layout:top', 'skeleton:layout/header');
+    }
 
-        // 2. Load the plugin stylesheet (currently empty -- proves the CSS hook fires).
+    public function getHelpers()
-        $this->hook->on('template:layout:css', array(
+    {
-            'template' => 'plugins/Skeleton/Asset/css/skeleton.css',
+        return array(
-        ));
+            'Plugin\QualKard\Helper' => array('QualKardHelper'),
-
+        );
-        // 3. Load the plugin script (currently empty -- proves the JS hook fires).
-        $this->hook->on('template:layout:js', array(
-            'template' => 'plugins/Skeleton/Asset/js/skeleton.js',
-        ));
     }
 
     public function getPluginName()
     {
-        return 'Skeleton';
+        return 'QualKard';
     }
 
     public function getPluginDescription()
     {
-        return t('Reusable skeleton/template for building Kanboard plugins.');
+        return t('Flashcard spaced repetition: grade a card by dragging it to a column, and it comes back when due (needs RecoReco).');
     }
 
     public function getPluginAuthor()
@@ -39,12 +44,12 @@ class Plugin extends Base
 
     public function getPluginVersion()
     {
-        return '0.1.0';
+        return '0.2.0';
     }
 
     public function getPluginHomepage()
     {
-        return 'https://code.beco.cc/beco/kanboard-plugin-skeleton';
+        return 'https://code.beco.cc/beco/QualKard';
     }
 
     public function getCompatibleVersion()

Template/layout/header.php

@@ -1 +0,0 @@
-<div class="skeleton-plugin-marker">Skeleton</div>

VERSION

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