beco/RecoReco
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

RecoReco: config modal + metadata storage, off Skeleton (v0.2)

Browse Source
This commit is contained in:
Ruben Carlo Benante
2026-07-07 21:48:46 -03:00
parent 1125bda81a
commit dea624a72d
9 changed files with 170 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
Asset/css/skeleton.css vendored
View File

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

1
Asset/js/skeleton.js
View File

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

92
Controller/RecurrenceController.php Normal file
View File

@@ -0,0 +1,92 @@
<?php
namespace Kanboard\Plugin\RecoReco\Controller;
use Kanboard\Controller\BaseController;
use Kanboard\Model\TaskModel;
/**
* The "Recurring schedule" modal: configure a card's calendar recurrence and store it in task
* metadata. v0.2 is storage only -- no spawning (that is the CLI engine in later versions).
*
* Gate: a card can only be enabled when it has a due date (the recurrence anchor) and is not
* already a native-recurring card (RecoReco and native recurrence are mutually exclusive).
*/
class RecurrenceController extends BaseController
{
public function edit(array $values = array(), array $errors = array())
{
$task = $this->getTask();
if (empty($values)) {
$values = $this->getStoredValues($task);
}
$this->response->html($this->template->render('recoReco:recurrence/edit', array(
'task' => $task,
'values' => $values,
'errors' => $errors,
'columns_list' => $this->columnModel->getList($task['project_id']),
'frequency_list' => $this->getFrequencyList(),
'has_due_date' => ! empty($task['date_due']),
'is_native' => $task['recurrence_status'] != TaskModel::RECURRING_STATUS_NONE,
)));
}
public function save()
{
$task = $this->getTask();
$input = $this->request->getValues();
// Only a plain card (has a due date, not native-recurring) may be enabled.
$can_recur = ! empty($task['date_due']) && $task['recurrence_status'] == TaskModel::RECURRING_STATUS_NONE;
$enabled = ($can_recur && isset($input['recoreco_enabled']) && $input['recoreco_enabled'] == 1) ? 1 : 0;
$frequency = isset($input['recoreco_frequency']) && array_key_exists($input['recoreco_frequency'], $this->getFrequencyList())
? $input['recoreco_frequency']
: 'monthly_day';
$values = array(
'recoreco_enabled' => $enabled,
'recoreco_target_column' => isset($input['recoreco_target_column']) ? (int) $input['recoreco_target_column'] : (int) $task['column_id'],
'recoreco_frequency' => $frequency,
'recoreco_last_day' => isset($input['recoreco_last_day']) ? 1 : 0,
'recoreco_days_before' => isset($input['recoreco_days_before']) && ctype_digit((string) $input['recoreco_days_before']) ? (int) $input['recoreco_days_before'] : 0,
);
// Capture the anchor (the due date at enable time) -- the drift-free pattern. The engine
// (v0.3) reads it to compute occurrences.
if ($enabled) {
$values['recoreco_anchor'] = (int) $task['date_due'];
}
$this->taskMetadataModel->save($task['id'], $values);
$this->flash->success(t('Recurring schedule saved.'));
return $this->response->redirect($this->helper->url->to('TaskViewController', 'show', array('task_id' => $task['id'])), true);
}
private function getStoredValues(array $task)
{
$meta = $this->taskMetadataModel->getAll($task['id']);
return array(
'recoreco_enabled' => isset($meta['recoreco_enabled']) ? (int) $meta['recoreco_enabled'] : 0,
'recoreco_target_column' => isset($meta['recoreco_target_column']) ? (int) $meta['recoreco_target_column'] : (int) $task['column_id'],
'recoreco_frequency' => isset($meta['recoreco_frequency']) ? $meta['recoreco_frequency'] : 'monthly_day',
'recoreco_last_day' => isset($meta['recoreco_last_day']) ? (int) $meta['recoreco_last_day'] : 0,
'recoreco_days_before' => isset($meta['recoreco_days_before']) ? (int) $meta['recoreco_days_before'] : 0,
);
}
private function getFrequencyList()
{
return array(
'yearly' => t('Yearly'),
'monthly_day' => t('Monthly by day'),
'monthly_dow' => t('Monthly by weekday'),
'weekly' => t('Weekly'),
'daily' => t('Daily'),
);
}
}

25
Plugin.php
View File

@@ -1,6 +1,6 @@
<?php
namespace Kanboard\Plugin\Skeleton;
namespace Kanboard\Plugin\RecoReco;
use Kanboard\Core\Plugin\Base;
@@ -8,28 +8,19 @@ class Plugin extends Base
{
public function initialize()
{
// 1. Render a visible word at the top of every page (the demo output).
$this->template->hook->attach('template:layout:top', 'skeleton:layout/header');
// 2. Load the plugin stylesheet (currently empty -- proves the CSS hook fires).
$this->hook->on('template:layout:css', array(
'template' => 'plugins/Skeleton/Asset/css/skeleton.css',
));
// 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',
));
// "Recurring schedule" entry in the task Actions sidebar, right after the basic actions
// (next to native "Edit recurrence"). Opens the RecoReco config modal.
$this->template->hook->attach('template:task:sidebar:after-basic-actions', 'recoReco:task/sidebar_action');
}
public function getPluginName()
{
return 'Skeleton';
return 'RecoReco';
}
public function getPluginDescription()
{
return t('Reusable skeleton/template for building Kanboard plugins.');
return t('Calendar-scheduled recurring cards: a template card spawns a copy on a date (yearly, monthly, weekly, daily), driven by the card due date.');
}
public function getPluginAuthor()
@@ -39,12 +30,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/RecoReco';
}
public function getCompatibleVersion()

80
README.md
View File

@@ -1,19 +1,31 @@
# Skeleton -- a Kanboard plugin template
# RecoReco -- calendar-scheduled recurring cards
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.
Kanboard's built-in recurrence is event-triggered (a card recurs when you move or close it).
RecoReco adds **calendar-triggered** recurrence: a card fires on a date, on its own, via cron --
made for bills, rent, and subscriptions.
## What it demonstrates
A card marked recurring **stays** as a template; on schedule, RecoReco spawns a plain
(non-recurring) copy into a column you choose. The template advances to the next date; the copy
keeps the fired date.
- 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.
RecoReco is opt-in per card and inert until you mark a card, so it needs no per-board setting. It
leaves native recurrence untouched (the two are mutually exclusive per card).
## The idea
- **The due date is the anchor.** All timing (day, month, weekday, time) is read from the card's
due date -- there are no separate date inputs. A card without a due date cannot be made recurring.
- **Frequencies:** yearly, monthly by day, monthly by weekday, weekly, daily.
- **Last day of the month:** an explicit checkbox (honored only when the due date is the last day,
or the last such weekday, of its month).
- **Lead time:** "create the copy N days before the due date", so the card shows up early enough
to act on; the copy is still due on the real day.
## Status
Early development. This version adds the **Recurring schedule** modal (a task sidebar action) and
stores the settings in task metadata. The scheduling engine and the cron command arrive in the
following versions.
## Requirements
@@ -21,45 +33,9 @@ the top of every page. It changes no data and runs no database migration.
## Installation
No build step and no dependencies.
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.
To uninstall, delete `plugins/Skeleton/`. Nothing else is left behind.
## Directory layout
```
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
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.
Copy this folder into your Kanboard installation as `plugins/RecoReco/`. The directory name must be
exactly `RecoReco` (Kanboard derives the plugin namespace from the folder name). No build step and
no database migration.
## License

1
Template/layout/header.php
View File

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

38
Template/recurrence/edit.php Normal file
View File

@@ -0,0 +1,38 @@
<div class="page-header">
<h2><?= t('Recurring schedule') ?></h2>
</div>
<?php $can_recur = $has_due_date && ! $is_native ?>
<?php if (! $has_due_date): ?>
<p class="alert alert-info"><?= t('Please set a due date first. RecoReco uses the card due date as the recurrence anchor.') ?></p>
<?php elseif ($is_native): ?>
<p class="alert alert-info"><?= t('This card already uses Kanboard built-in recurrence. RecoReco and native recurrence cannot be used together.') ?></p>
<?php endif ?>
<form method="post" action="<?= $this->url->href('RecurrenceController', 'save', array('plugin' => 'RecoReco', 'task_id' => $task['id'])) ?>" autocomplete="off">
<?= $this->form->csrf() ?>
<?= $this->form->label(t('Make recurring'), 'recoreco_enabled') ?>
<div class="recoreco-radios">
<label>
<input type="radio" name="recoreco_enabled" value="0" <?= $values['recoreco_enabled'] == 1 ? '' : 'checked="checked"' ?>> <?= t('No') ?>
</label>
<label>
<input type="radio" name="recoreco_enabled" value="1" <?= $values['recoreco_enabled'] == 1 ? 'checked="checked"' : '' ?> <?= $can_recur ? '' : 'disabled="disabled"' ?>> <?= t('Yes') ?>
</label>
</div>
<?= $this->form->label(t('Target column (where the copy appears)'), 'recoreco_target_column') ?>
<?= $this->form->select('recoreco_target_column', $columns_list, $values) ?>
<?= $this->form->label(t('Frequency'), 'recoreco_frequency') ?>
<?= $this->form->select('recoreco_frequency', $frequency_list, $values) ?>
<?= $this->form->checkbox('recoreco_last_day', t('Last day of the month (honored only when the due date is the last day / last weekday of its month)'), 1, $values['recoreco_last_day'] == 1) ?>
<?= $this->form->label(t('Create the copy this many days before the due date'), 'recoreco_days_before') ?>
<?= $this->form->number('recoreco_days_before', $values) ?>
<?= $this->modal->submitButtons() ?>
</form>

3
Template/task/sidebar_action.php Normal file
View File

@@ -0,0 +1,3 @@
<li>
<?= $this->modal->medium('calendar', t('Recurring schedule'), 'RecurrenceController', 'edit', array('plugin' => 'RecoReco', 'task_id' => $task['id'])) ?>
</li>

2
VERSION
View File

@@ -1 +1 @@
RecoReco v0.1
RecoReco v0.2