FinanceBuddy v1.3.0 — per-board currency shipped. All clean (php -l, ASCII, README + TODO synced)

Asset/css/finance.css

@@ -2,13 +2,27 @@
  * FinanceBuddy styles.
  */
 
-/* Per-column net total in the column header (its own line, subtle pill). */
+/* The column header (.board-column-expanded-header) is a flex row, so the total is a flex item. To
+   drop it onto its own line under the title, let that header wrap (scoped with :has to headers that
+   actually contain the total -- i.e. enabled boards only) and give the total full width. No
+   background (dropped per request); "Total:" stays black, only the amount span is colored by sign. */
+.board-column-expanded-header:has(.fb-column-total) {
+    flex-wrap: wrap;
+}
+
 .fb-column-total {
+    flex-basis: 100%;
+    margin-top: 2px;
+    text-align: right;
+}
+
+/* The visible pill hugs the text (not the full width) and is right-justified on its line. */
+.fb-total-pill {
     display: inline-block;
-    margin-top: 3px;
     padding: 0 5px;
     font-weight: bold;
     font-size: 0.95em;
+    color: #000;
     background: rgba(0, 0, 0, 0.05);
     border-radius: 3px;
 }

Asset/js/relocate.js

@@ -0,0 +1,59 @@
+/*
+ * FinanceBuddy -- place the "Hide/Show column total" entry inside the native column menu.
+ *
+ * Kanboard only exposes the template:board:column:dropdown hook AFTER the column menu <ul>, and its
+ * dropdown JS clones just that <ul> when the menu opens. So the hook item cannot reach the menu on
+ * its own. column_dropdown.php renders the item hidden next to the menu; this script moves each such
+ * item into that column's real <ul> so it appears alongside "Hide this column", etc.
+ *
+ * BoardDragAndDrop.refresh() does $("#board-container").replaceWith(data) on every drag-and-drop and
+ * poll refresh, so the observer is bound to the STABLE parent of #board-container (which survives the
+ * swap), not to #board-container itself -- otherwise it would be left watching a detached node and
+ * the entry would vanish until a full page reload.
+ */
+(function () {
+    "use strict";
+
+    function relocate() {
+        var items = document.querySelectorAll(".financebuddy-menu-item");
+
+        for (var i = 0; i < items.length; i++) {
+            var li = items[i];
+
+            // Already moved into a menu list: just make sure it is visible.
+            if (li.closest("ul")) {
+                li.style.display = "";
+                continue;
+            }
+
+            // The hook renders the item as a child of the column's dropdown wrapper; its first <ul>
+            // is the native menu.
+            var menu = li.parentNode ? li.parentNode.querySelector("ul") : null;
+
+            if (menu) {
+                menu.appendChild(li);
+                li.style.display = "";
+            }
+        }
+    }
+
+    function init() {
+        var container = document.getElementById("board-container");
+
+        if (!container) {
+            return;
+        }
+
+        relocate();
+
+        if (window.MutationObserver && container.parentNode) {
+            new MutationObserver(relocate).observe(container.parentNode, { childList: true, subtree: true });
+        }
+    }
+
+    if (document.readyState === "loading") {
+        document.addEventListener("DOMContentLoaded", init);
+    } else {
+        init();
+    }
+})();

Controller/FinanceColumnController.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace Kanboard\Plugin\FinanceBuddy\Controller;
+
+use Kanboard\Controller\BaseController;
+use Kanboard\Core\Controller\AccessForbiddenException;
+use Kanboard\Plugin\FinanceBuddy\Helper\FinanceHelper;
+
+/**
+ * Toggle a board column's header total on/off from the column dropdown menu. The per-column flag
+ * lives in project metadata; project-manager gated (same scope as enabling FinanceBuddy). Returns
+ * to the board, whose reload re-renders the header with or without the total.
+ */
+class FinanceColumnController extends BaseController
+{
+    public function toggleTotal()
+    {
+        $this->checkCSRFParam();
+        $project = $this->getProject();
+
+        if (! $this->helper->user->hasProjectAccess('ProjectEditController', 'edit', $project['id'])) {
+            throw new AccessForbiddenException();
+        }
+
+        $key = FinanceHelper::HIDE_TOTAL_PREFIX.$this->request->getIntegerParam('column_id');
+
+        // Store the literal 'on'/'off' (both non-empty) rather than 1/0, so the flag is never lost
+        // to PHP's empty("0") === true on the metadata save.
+        $hidden = $this->projectMetadataModel->get($project['id'], $key, FinanceHelper::HIDE_TOTAL_OFF) === FinanceHelper::HIDE_TOTAL_ON;
+        $this->projectMetadataModel->save($project['id'], array($key => $hidden ? FinanceHelper::HIDE_TOTAL_OFF : FinanceHelper::HIDE_TOTAL_ON));
+
+        $this->response->redirect($this->helper->url->to('BoardViewController', 'show', array('project_id' => $project['id'])));
+    }
+}

Helper/FinanceHelper.php

@@ -19,6 +19,19 @@ class FinanceHelper extends Base
     const INSTALLMENT_CURRENT_KEY = 'financebuddy_installment_current';
     const INSTALLMENT_TOTAL_KEY = 'financebuddy_installment_total';
 
+    // Per-board currency symbol shown before every amount (default "R$"). Up to 4 chars; the stored
+    // value is trimmed, capped, and defaulted on read, so an empty or oversized value is harmless.
+    const CURRENCY_KEY = 'financebuddy_currency';
+    const CURRENCY_DEFAULT = 'R$';
+    const CURRENCY_MAX_LENGTH = 4;
+
+    // Per-column opt-out of the header total. Stored per column in PROJECT metadata as
+    // financebuddy_hide_total_<column_id> = 'on' (hidden) or 'off' (shown, the default). Literal
+    // on/off, never 1/0, so the flag is never dropped by the metadata save (PHP empty("0") === true).
+    const HIDE_TOTAL_PREFIX = 'financebuddy_hide_total_';
+    const HIDE_TOTAL_ON = 'on';
+    const HIDE_TOTAL_OFF = 'off';
+
     // Hidden marker present only when the task form was submitted with the finance fieldset, so
     // non-finance task updates (moves, API calls) are ignored by the persistence hooks.
     const FORM_MARKER = 'financebuddy_form';
@@ -26,6 +39,9 @@ class FinanceHelper extends Base
     // Memoized per project_id: the board hooks below call isEnabled() once per card.
     private static $enabledCache = array();
 
+    // Memoized per project_id: currency() is likewise resolved once per card/column render.
+    private static $currencyCache = array();
+
     /**
      * Is FinanceBuddy enabled for this board?
      *
@@ -43,6 +59,26 @@ class FinanceHelper extends Base
         return self::$enabledCache[$project_id];
     }
 
+    /**
+     * Per-board currency symbol shown before amounts: the stored value trimmed and capped to
+     * CURRENCY_MAX_LENGTH, or CURRENCY_DEFAULT ("R$") when empty. Memoized per project.
+     *
+     * @param  integer $project_id
+     * @return string
+     */
+    public function currency($project_id)
+    {
+        $project_id = (int) $project_id;
+
+        if (! isset(self::$currencyCache[$project_id])) {
+            $symbol = trim((string) $this->projectMetadataModel->get($project_id, self::CURRENCY_KEY, ''));
+            $symbol = mb_substr($symbol, 0, self::CURRENCY_MAX_LENGTH);
+            self::$currencyCache[$project_id] = $symbol === '' ? self::CURRENCY_DEFAULT : $symbol;
+        }
+
+        return self::$currencyCache[$project_id];
+    }
+
     /**
      * Stored finance values for a task, with defaults. One query (getAll) since the board renders
      * this per card.
@@ -110,6 +146,18 @@ class FinanceHelper extends Base
         return $net;
     }
 
+    /**
+     * Has this column's header total been hidden (per-column opt-out)?
+     *
+     * @param  integer $project_id
+     * @param  integer $column_id
+     * @return bool
+     */
+    public function isTotalHidden($project_id, $column_id)
+    {
+        return $this->projectMetadataModel->get((int) $project_id, self::HIDE_TOTAL_PREFIX.(int) $column_id, self::HIDE_TOTAL_OFF) === self::HIDE_TOTAL_ON;
+    }
+
     /**
      * Values to prefill the task-form fields: a re-post (after a validation error) wins, then the
      * stored metadata for an existing task, otherwise blanks for a new task.

Model/FinancePersistence.php

@@ -73,6 +73,19 @@ class FinancePersistence extends Base
         }
     }
 
+    /**
+     * recoreco:task:spawned -- RecoReco (calendar recurrence) just spawned a copy. Its ongoing card
+     * is the TEMPLATE that stays (unlike native recurrence, whose ongoing card is the new child), so
+     * advance the SOURCE template's installment. The clone already copied the current installment
+     * verbatim via onDuplication during RecoReco's duplicate() call.
+     */
+    public function onRecoRecoSpawn(array &$payload)
+    {
+        if (! empty($payload['source_task_id'])) {
+            $this->advanceInstallment((int) $payload['source_task_id']);
+        }
+    }
+
     /**
      * model:task:modification:prepare -- fires before UPDATE, $values by reference. The task id is
      * removed from $values by core, but it is the route parameter of the modification request.
@@ -176,6 +189,34 @@ class FinancePersistence extends Base
         ));
     }
 
+    /**
+     * Advance a task's current installment by one, in place. A finite plan clamps at total+1, one
+     * past the last installment: that overflow is the "plan complete" tombstone (p4/3) that RecoReco
+     * reads to stop a following recurrence, and it caps runaway when nothing follows. Clones still
+     * read p1/total .. pTotal/total because a clone snapshots current BEFORE this advance. An
+     * open-ended plan (no total) increments unbounded (p2 -> p3); cards with no numeric current
+     * installment are left alone.
+     */
+    private function advanceInstallment($task_id)
+    {
+        $current = $this->taskMetadataModel->get($task_id, FinanceHelper::INSTALLMENT_CURRENT_KEY, '');
+
+        if ($current === '' || ! ctype_digit((string) $current)) {
+            return;
+        }
+
+        $total = $this->taskMetadataModel->get($task_id, FinanceHelper::INSTALLMENT_TOTAL_KEY, '');
+        $next = (int) $current + 1;
+
+        if ($total !== '' && ctype_digit((string) $total) && $next > (int) $total + 1) {
+            $next = (int) $total + 1;
+        }
+
+        $this->taskMetadataModel->save($task_id, array(
+            FinanceHelper::INSTALLMENT_CURRENT_KEY => (string) $next,
+        ));
+    }
+
     private function intOrBlank($raw)
     {
         $raw = trim((string) $raw);

Plugin.php

@@ -34,6 +34,11 @@ class Plugin extends Base
         // and a manual Duplicate copies it verbatim.
         $this->hook->on('model:task:duplication:aftersave', array($persistence, 'onDuplication'));
 
+        // RecoReco (calendar recurrence) spawns a copy and emits this signal. The clone already got
+        // the finance verbatim (via onDuplication above); here we advance the SOURCE template's
+        // installment, since RecoReco's ongoing card is the template that stays.
+        $this->hook->on('recoreco:task:spawned', array($persistence, 'onRecoRecoSpawn'));
+
         // The line-3 money badge on each board card, rendered directly under the title. Two hooks:
         // "private" is the normal board, "public" is the read-only board shared by token.
         $this->template->hook->attach('template:board:private:task:after-title', 'financeBuddy:board/task_money');
@@ -42,6 +47,14 @@ class Plugin extends Base
         // Per-column net total (credits - debits) in the column header.
         $this->template->hook->attach('template:board:column:header', 'financeBuddy:board/column_total');
 
+        // "Hide/Show column total" toggle in the column dropdown menu. The only column-menu hook
+        // renders after the native <ul>, so column_dropdown.php emits the item hidden and relocate.js
+        // moves it into the menu (same technique as BulkMoveTasks, with the stable-parent observer).
+        $this->template->hook->attach('template:board:column:dropdown', 'financeBuddy:board/column_dropdown');
+        $this->hook->on('template:layout:js', array(
+            'template' => 'plugins/FinanceBuddy/Asset/js/relocate.js',
+        ));
+
         // The same money badge at the top of the opened card (task view), under the title, so a
         // card shows its money whether you are on the board or reading the card. Reuses the board
         // badge template (both hooks pass $task).
@@ -72,7 +85,7 @@ class Plugin extends Base
 
     public function getPluginVersion()
     {
-        return '1.0.1';
+        return '1.3.0';
     }
 
     public function getPluginHomepage()

README.md

@@ -30,7 +30,7 @@ Once a board is enabled:
 
 The task edit/create form gains a **Finance** section in the middle column:
 
-- **Amount** in R$.
+- **Amount** in the board's currency (default R$).
 - **Debit** or **Credit** (money out vs money in).
 - **Installment** current / total (for example `2` of `10`). Leave the total blank for an
   open-ended recurring bill.
@@ -51,11 +51,28 @@ Each column header shows a **`Total:`** of its cards -- credits positive, debits
 net): red when negative (what you owe), green when positive, gray at zero. It is shown for every
 column, including `Total: R$0,00`.
 
+You can hide the total on a per-column basis: open the column's dropdown menu (the caret next to
+the column title) and pick **"Hide column total"**; the same menu then offers **"Show column
+total"** to bring it back. This is a per-board manager action, remembered per column.
+
+### Installments and recurrence
+
+FinanceBuddy carries the money across copies. Kanboard's built-in recurrence and RecoReco's
+calendar recurrence advance the installment on the next occurrence (`p2/10 -> p3/10`); a manual
+duplicate copies it as-is. When a RecoReco-followed plan finishes, the parked template is left one
+past the last installment (`p3/3 -> p4/3`) as a "plan complete" marker that RecoReco reads to stop
+recurring; the copies themselves still read `p1/3 .. p3/3`. Open-ended plans (blank total) keep
+counting.
+
 ## Money format
 
-Amounts show in R$ with a comma decimal and no thousand separator (for example `R$1234,56`).
+Amounts show with a comma decimal and no thousand separator (for example `R$1234,56`). Input
-Input accepts either a dot or a comma as the decimal separator, so `1234.56` and `1234,56` are
+accepts either a dot or a comma as the decimal separator, so `1234.56` and `1234,56` are the same
-the same value.
+value.
+
+The currency symbol shown before every amount is **per board**: set it under
+Settings -> Integrations next to the enable checkbox (up to 4 characters, e.g. `US$`, `EUR`, `GBP`).
+Leave it empty for the default `R$`.
 
 ## How it stores data
 
@@ -78,3 +95,23 @@ Settings -> Integrations and tick "Enable FinanceBuddy on this board".
 ## 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.
+- **[QualKard](https://code.beco.cc/beco/QualKard)** -- flashcard spaced repetition: grade a card by
+  dragging it to a column, and it comes back when due (needs RecoReco).
+- **[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/column_dropdown.php

@@ -0,0 +1,17 @@
+<?php if ($this->FinanceHelper->isEnabled($column['project_id']) && $this->user->hasProjectAccess('ProjectEditController', 'edit', $column['project_id'])): ?>
+    <?php /* Rendered here (outside the menu <ul>) by the only column-menu hook, then moved into the
+             column's real dropdown <ul> by Asset/js/relocate.js so it sits next to the native
+             entries. Hidden until relocated to avoid a flash in the header. */ ?>
+    <?php $hidden = $this->FinanceHelper->isTotalHidden($column['project_id'], $column['id']); ?>
+    <li class="financebuddy-menu-item" style="display: none;">
+        <?= $this->url->link(
+            $hidden
+                ? '<i class="fa fa-eye fa-fw"></i> '.t('Show column total')
+                : '<i class="fa fa-eye-slash fa-fw"></i> '.t('Hide column total'),
+            'FinanceColumnController',
+            'toggleTotal',
+            array('plugin' => 'FinanceBuddy', 'project_id' => $column['project_id'], 'column_id' => $column['id']),
+            true
+        ) ?>
+    </li>
+<?php endif ?>

Template/board/column_total.php

@@ -1,24 +1,30 @@
 <?php
 // Per-column net total in the column header (credits - debits). Shown in every column of an
-// enabled board, including "total R$0,00" -- never hidden on zero. Server-side, re-renders on
+// enabled board, including "Total: R$0,00" -- never hidden on zero. Server-side, re-renders on
-// every board refresh.
+// every board refresh. Rendered on its own full-width line under the title; "Total:" stays the
+// default (black) and only the amount is colored by sign.
 if (empty($column['project_id']) || ! $this->FinanceHelper->isEnabled($column['project_id'])) {
     return;
 }
 
+// Per-column opt-out, toggled from the column dropdown menu.
+if ($this->FinanceHelper->isTotalHidden($column['project_id'], $column['id'])) {
+    return;
+}
+
 $net = $this->FinanceHelper->columnNet($column);
 
 if ($net > 0) {
-    $class = 'fb-column-total fb-total-credit';
+    $amount_class = 'fb-total-credit';
     $sign = '+';
 } elseif ($net < 0) {
-    $class = 'fb-column-total fb-total-debit';
+    $amount_class = 'fb-total-debit';
     $sign = '-';
 } else {
-    $class = 'fb-column-total fb-total-zero';
+    $amount_class = 'fb-total-zero';
     $sign = '';
 }
 ?>
-<div class="<?= $class ?>">
+<div class="fb-column-total">
-    <?= t('Total') ?>: <span class="fb-amount"><?= $sign ?>R$<?= \Kanboard\Plugin\FinanceBuddy\Helper\FinanceHelper::money(abs($net)) ?></span>
+    <span class="fb-total-pill"><?= t('Total') ?>: <span class="fb-amount <?= $amount_class ?>"><?= $sign ?><?= $this->text->e($this->FinanceHelper->currency($column['project_id'])) ?><?= \Kanboard\Plugin\FinanceBuddy\Helper\FinanceHelper::money(abs($net)) ?></span></span>
 </div>

Template/board/task_money.php

@@ -15,13 +15,18 @@ if ($fb['amount'] === '' || (float) $fb['amount'] <= 0) {
 $credit = $fb['direction'] === 'credit';
 $sign = $credit ? '+' : '-';
 $total = $fb['installment_total'];
-$current = $fb['installment_current'] !== '' ? $fb['installment_current'] : '1';
+$current = $fb['installment_current'];
+
+// Installments: "p2/10" when a total is set; "p2" (open-ended) when only the current is set;
+// nothing when neither is set. Default the current to 1 if only a total was entered.
+$show_installments = $current !== '' || $total !== '';
+$current_display = $current !== '' ? $current : '1';
 ?>
 <div class="fb-line">
     <span class="fb-badge <?= $credit ? 'fb-badge-credit' : 'fb-badge-debit' ?>">
-        <?= $sign ?>R$<?= \Kanboard\Plugin\FinanceBuddy\Helper\FinanceHelper::money($fb['amount']) ?>
+        <?= $sign ?><?= $this->text->e($this->FinanceHelper->currency($task['project_id'])) ?><?= \Kanboard\Plugin\FinanceBuddy\Helper\FinanceHelper::money($fb['amount']) ?>
     </span>
-    <?php if ($total !== ''): ?>
+    <?php if ($show_installments): ?>
-        <span class="fb-installments">p<?= $this->text->e($current) ?>/<?= $this->text->e($total) ?></span>
+        <span class="fb-installments">p<?= $this->text->e($current_display) ?><?= $total !== '' ? '/'.$this->text->e($total) : '' ?></span>
     <?php endif ?>
 </div>

Template/project/integration.php

@@ -13,8 +13,15 @@
     <p class="form-help">
         <?= t('When enabled, cards on this board can carry a money value (debit or credit, with optional installments), shown on the card and totalled per column. Boards left disabled are unaffected.') ?>
     </p>
+
+    <?= $this->form->label(t('Currency symbol'), 'financebuddy_currency') ?>
+    <?= $this->form->text('financebuddy_currency', $values, array(), array('maxlength="4"', 'placeholder="R$"')) ?>
+    <p class="form-help">
+        <?= t('Shown before every amount on this board (up to 4 characters). Leave empty for the default R$.') ?>
+    </p>
 </div>
 
 <div class="form-actions">
     <button type="submit" class="btn btn-blue"><?= t('Save') ?></button>
 </div>
+<hr>

Template/task/form_fields.php

@@ -5,7 +5,7 @@
 <div class="fb-form">
     <input type="hidden" name="<?= \Kanboard\Plugin\FinanceBuddy\Helper\FinanceHelper::FORM_MARKER ?>" value="1">
 
-    <label for="financebuddy_amount"><?= t('Amount (R$)') ?></label>
+    <label for="financebuddy_amount"><?= $this->text->e(t('Amount (%s)', $this->FinanceHelper->currency($values['project_id']))) ?></label>
     <input type="text" id="financebuddy_amount" name="financebuddy_amount" value="<?= $this->text->e($fb['amount']) ?>" placeholder="0,00" autocomplete="off">
 
     <label><?= t('Type') ?></label>
@@ -24,6 +24,6 @@
         <span><?= t('of') ?></span>
         <input type="number" min="1" name="financebuddy_installment_total" value="<?= $this->text->e($fb['installment_total']) ?>" class="fb-form-num">
     </div>
-    <p class="form-help"><?= t('Leave the total blank for an open-ended recurring bill.') ?></p>
+    <p class="form-help"><?= t('Set a total for a finite plan (shows p2/10); leave it blank for an open-ended count (shows p2).') ?></p>
 </div>
 <?php endif ?>

VERSION

@@ -1 +1 @@
-FinanceBuddy v1.0.1
+FinanceBuddy v1.3.0