OrganonTweaks/README.md

# OrganonTweaks -- umbrella plugin for small Kanboard tweaks

A home for small, unrelated Kanboard adjustments that are not big enough to deserve their
own plugin. Each tweak is self-contained; more will be added over time. If a tweak grows
into a real subsystem it graduates into its own plugin (see PLAN-organon-tweaks-plugin.md).

## Tweaks

### Remove an empty column

Adds a **Remove this Column** entry (trash icon) to a board column's header dropdown, next
to the other column actions. It appears only when the column is completely empty -- no
tasks, open or closed -- because Kanboard's column removal is a plain delete and a non-empty
column would orphan its tasks. Clicking it asks for confirmation, then removes the column
and returns to the board.

- The menu entry is rendered by the `template:board:column:dropdown` hook (which sits
  outside the native menu list), then moved into the menu by `Asset/js/relocate.js`.
- The empty check counts open and closed tasks via a helper
  (`Helper/OrganonColumnHelper.php`, `taskFinderModel->countByColumnId(...)`), since the
  board's own count is open-only.
- Only users allowed to manage columns see it, and the controller re-checks both the
  permission and the emptiness before deleting.

### Always show the comment icon

Kanboard shows the comment icon on a board card only once it has at least one comment, so
adding the *first* comment means opening the card and finding the sidebar link. With this
tweak on, a card with no comments shows a comment bubble with a **"+"** that opens the same
comment modal, letting you add the first comment straight from the board. Cards that already
have comments keep showing the count as before.

- Rendered by the `template:board:task:icons` hook (`Template/board/task_comment_icon.php`),
  only when the card has no comments and the user may create one (so it does not show for
  read-only viewers).
- **On by default.** Toggle it under "Settings -> Organon Tweaks".

### Keep the board scroll position across refreshes

When you drop a card (or Kanboard auto-refreshes the board via polling), it rebuilds the
board with `$("#board-container").replaceWith(...)`, and the new element starts scrolled to
the far left -- so the view jumps back to the first column. This tweak remembers the
horizontal scroll position and restores it as soon as the rebuilt board appears, so the
board stays where you were.

- Implemented in `Asset/js/keep-scroll.js`: it observes the stable parent (the container
  itself is replaced), reads/writes `scrollLeft` on whichever `#board-container` is current.
- **On by default.** Toggle it under "Settings -> Organon Tweaks".

### Open a card only on a quick click

Dropping a card sometimes leaks a trailing "click" that opens the card -- an unwanted side
effect of the drag. A real click is a quick press-release; a drag is a press held much
longer. So `Asset/js/click-guard.js` times the press on a card (`mousedown`/`touchstart` to
the following `click`) and, if it was held longer than **100 ms**, swallows the click in the
capture phase before Kanboard's open handler -- so a drag never opens the card. Normal
clicks (well under 100 ms) still open cards as usual. The 100 ms threshold is fixed.

- **On by default.** Toggle it under "Settings -> Organon Tweaks".

### Enhance the recurrence dialog

Kanboard's native "Edit recurrence" dialog is a plain form. This makes two small usability
edits when it opens (there is no template hook, so it is done in JS,
`Asset/js/enhance-recurrence.js`):

- the "Generate recurrent task" **Yes/No dropdown** becomes two **radio buttons** (one click
  to set, instead of open + select). The original select is kept hidden and stays in sync, so
  the form submits exactly as before.
- a small **[+7]** button next to the "Factor" input adds 7 to it (one week of days).

- **On by default.** Toggle it under "Settings -> Organon Tweaks".

## Settings

Global (per Kanboard instance) and admin-only, under "Settings -> Organon Tweaks":

- **Always show the comment icon on board cards** -- default on.
- **Keep the board scroll position across refreshes** -- default on.
- **Open a card only on a quick click** -- default on.
- **Enhance the recurrence dialog** -- default on.

## Requirements

- Kanboard >= 1.2.0

## Installation

Copy this folder into your Kanboard installation as `plugins/OrganonTweaks/`. The directory
name must be exactly `OrganonTweaks` (Kanboard derives the plugin namespace from the folder
name). No build step and no database migration.

## License

AGPL-3.0. See LICENSE.

## More Kanboard plugins by Ruben (drbeco)

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.
- **[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.