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`. 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- `icon_size`: size (px) of the icon shown at the top of pages. 29 30- `extensions`: allowed file extensions (separated by `;`), for example `svg;png;jpg;jpeg`. 31 32- `show_on_top`: enable/disable icon display at the top of pages. 33 34- `show_as_favicon`: use the page icon as favicon. 35 36## Usage 37 38From a page, use the `Gérer l'icône` action, then upload/delete. 39 40The plugin works on the **current page** (`$ID`), not on an external target parameter. 41 42## Helper API 43 44Load helper: 45 46```php 47$pagesicon = plugin_load('helper', 'pagesicon'); 48``` 49 50### mediaID Resolution 51 52- `getPageImage(string $namespace, string $pageID, string $size = 'bigorsmall')` 53 Returns a mediaID (`ns:file.ext`) or `false`. 54 55- `getMediaImage(string $mediaID, string $size = 'bigorsmall')` 56 Returns the icon mediaID for a media item, or `false`. 57 58`size` supports: `big`, `small`, `bigorsmall`, `smallorbig`. 59 60### Versioned URL Resolution 61 62- `getImageIcon(string $namespace, string $pageID, string $size = 'bigorsmall', array $params = ['width' => 55], ?int &$mtime = null)` 63 Returns an icon URL (with `pi_ts=<filemtime>`) or `false`. 64 Also fills `$mtime`. 65 66- `getMediaIcon(string $mediaID, string $size = 'bigorsmall', array $params = ['width' => 55], ?int &$mtime = null)` 67 Returns a media icon URL (with `pi_ts=<filemtime>`) or `false`. 68 Also fills `$mtime`. 69 70### Management URLs 71 72- `getUploadIconPage(string $targetPage = '')` 73 Returns the page URL with `?do=pagesicon`, or `null` when not authorized. 74 75- `getUploadMediaIconPage(string $mediaID = '')` 76 Returns the icon management URL associated with a media item. 77 78### Notification 79 80- `notifyIconUpdated(string $targetPage, string $action = 'update', string $mediaID = '')` 81 82Effects: 83- updates `purgefile`, 84- triggers `PLUGIN_PAGESICON_UPDATED`. 85 86Payload: 87- `target_page`, 88- `action`, 89- `media_id`. 90 91Each consumer plugin remains responsible for its own cache invalidation strategy. 92