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