1da933f89SLORTET# Pagesicon 2da933f89SLORTET 3da933f89SLORTETI really like DokuWiki, but I always found it a bit sad: there was no simple way to add nice icons to pages. 4da933f89SLORTETWith **pagesicon**, this is now possible. 5da933f89SLORTET 6da933f89SLORTET`pagesicon` is both: 7da933f89SLORTET- a **plugin** (icon display and management), 8da933f89SLORTET- a **helper** (reusable API for other plugins like `catmenu` and `visualindex`). 9da933f89SLORTET 10*74a9e763SLORTET## What the plugin does 11da933f89SLORTET 12da933f89SLORTET- Displays an icon at the top of the page (`show`), when enabled. 13da933f89SLORTET- Can use the page icon as browser tab favicon (`show_as_favicon`). 14da933f89SLORTET- Provides a per-page icon management page: `?do=pagesicon`. 15da933f89SLORTET- Supports `big` and `small` icon variants. 16*74a9e763SLORTET- Notifies other plugins when an icon changes through `PLUGIN_PAGESICON_UPDATED` (for cache invalidation on consumer plugins). 17da933f89SLORTET 18da933f89SLORTET## Configuration 19da933f89SLORTET 20da933f89SLORTETIn the `Configuration Manager`: 21da933f89SLORTET 22da933f89SLORTET- `icon_name`: candidate names for the `big` icon (separated by `;`). 23da933f89SLORTET Supports `~pagename~`. 24da933f89SLORTET 25da933f89SLORTET- `icon_thumbnail_name`: candidate names for the `small` icon (separated by `;`). 26da933f89SLORTET Supports `~pagename~`. 27da933f89SLORTET 28*74a9e763SLORTET- `default_image`: default image (media ID) used only when helper API fallback is explicitly enabled. 29*74a9e763SLORTET 30da933f89SLORTET- `icon_size`: size (px) of the icon shown at the top of pages. 31da933f89SLORTET 32da933f89SLORTET- `extensions`: allowed file extensions (separated by `;`), for example `svg;png;jpg;jpeg`. 33da933f89SLORTET 34da933f89SLORTET- `show_on_top`: enable/disable icon display at the top of pages. 35da933f89SLORTET 36da933f89SLORTET- `show_as_favicon`: use the page icon as favicon. 37da933f89SLORTET 38da933f89SLORTET## Usage 39da933f89SLORTET 40da933f89SLORTETFrom a page, use the `Gérer l'icône` action, then upload/delete. 41da933f89SLORTET 42da933f89SLORTETThe plugin works on the **current page** (`$ID`), not on an external target parameter. 43da933f89SLORTET 44da933f89SLORTET## Helper API 45da933f89SLORTET 46da933f89SLORTETLoad helper: 47da933f89SLORTET 48da933f89SLORTET```php 49da933f89SLORTET$pagesicon = plugin_load('helper', 'pagesicon'); 50da933f89SLORTET``` 51da933f89SLORTET 52da933f89SLORTET### mediaID Resolution 53da933f89SLORTET 54*74a9e763SLORTET- `getPageIconId(string $namespace, string $pageID, string $size = 'bigorsmall')` 55da933f89SLORTET Returns a mediaID (`ns:file.ext`) or `false`. 56da933f89SLORTET 57*74a9e763SLORTET- `getMediaIconId(string $mediaID, string $size = 'bigorsmall')` 58da933f89SLORTET Returns the icon mediaID for a media item, or `false`. 59da933f89SLORTET 60da933f89SLORTET`size` supports: `big`, `small`, `bigorsmall`, `smallorbig`. 61da933f89SLORTET 62da933f89SLORTET### Versioned URL Resolution 63da933f89SLORTET 64*74a9e763SLORTET- `getPageIconUrl(string $namespace, string $pageID, string $size = 'bigorsmall', array $params = ['width' => 55], ?int &$mtime = null, bool $withDefault = false)` 65da933f89SLORTET Returns an icon URL (with `pi_ts=<filemtime>`) or `false`. 66da933f89SLORTET Also fills `$mtime`. 67da933f89SLORTET 68*74a9e763SLORTET- `getMediaIconUrl(string $mediaID, string $size = 'bigorsmall', array $params = ['width' => 55], ?int &$mtime = null, bool $withDefault = false)` 69da933f89SLORTET Returns a media icon URL (with `pi_ts=<filemtime>`) or `false`. 70da933f89SLORTET Also fills `$mtime`. 71da933f89SLORTET 72*74a9e763SLORTET- `getDefaultIconUrl(array $params = ['width' => 55], ?int &$mtime = null)` 73*74a9e763SLORTET Returns the configured default image URL, or `false`. 74*74a9e763SLORTET 75da933f89SLORTET### Management URLs 76da933f89SLORTET 77da933f89SLORTET- `getUploadIconPage(string $targetPage = '')` 78da933f89SLORTET Returns the page URL with `?do=pagesicon`, or `null` when not authorized. 79da933f89SLORTET 80da933f89SLORTET- `getUploadMediaIconPage(string $mediaID = '')` 81da933f89SLORTET Returns the icon management URL associated with a media item. 82da933f89SLORTET 83da933f89SLORTET### Notification 84da933f89SLORTET 85da933f89SLORTET- `notifyIconUpdated(string $targetPage, string $action = 'update', string $mediaID = '')` 86da933f89SLORTET 87da933f89SLORTETEffects: 88da933f89SLORTET- updates `purgefile`, 89da933f89SLORTET- triggers `PLUGIN_PAGESICON_UPDATED`. 90da933f89SLORTET 91da933f89SLORTETPayload: 92da933f89SLORTET- `target_page`, 93da933f89SLORTET- `action`, 94da933f89SLORTET- `media_id`. 95da933f89SLORTET 96da933f89SLORTETEach consumer plugin remains responsible for its own cache invalidation strategy. 97*74a9e763SLORTET 98*74a9e763SLORTET## Signature compatibility 99*74a9e763SLORTET 100*74a9e763SLORTET- Before `09-03-2025`: 101*74a9e763SLORTET - `getPageImage(string $namespace, string $pageID, string $size = 'bigorsmall')` 102*74a9e763SLORTET - `getMediaImage(string $mediaID, string $size = 'bigorsmall')` 103*74a9e763SLORTET - `getImageIcon(string $namespace, string $pageID, string $size = 'bigorsmall', array $params = ['width' => 55], ?int &$mtime = null)` 104*74a9e763SLORTET - `getMediaIcon(string $mediaID, string $size = 'bigorsmall', array $params = ['width' => 55], ?int &$mtime = null)` 105*74a9e763SLORTET 106*74a9e763SLORTETCompatibility is preserved through legacy aliases: 107*74a9e763SLORTET- `getPageImage(...)` -> `getPageIconId(...)` (legacy `$withDefault` argument is ignored) 108*74a9e763SLORTET- `getMediaImage(...)` -> `getMediaIconId(...)` (legacy `$withDefault` argument is ignored) 109*74a9e763SLORTET- `getImageIcon(...)` -> `getPageIconUrl(...)` 110*74a9e763SLORTET- `getMediaIcon(...)` -> `getMediaIconUrl(...)` 111*74a9e763SLORTET- `getDefaultImageIcon(...)` -> `getDefaultIconUrl(...)` 112