README.md
1# Pagesicon
2
3J'aime beaucoup DokuWiki, mais je l'ai toujours trouvé un peu triste : il manquait une façon simple de mettre de belles icônes sur les pages.
4Avec **pagesicon**, c'est possible.
5
6`pagesicon` est à la fois :
7- un **plugin** (affichage et gestion des icônes),
8- un **helper** (API réutilisable par d'autres plugins, comme `catmenu` et `visualindex`).
9
10## Ce que fait le plugin
11
12- Affiche une icône en haut de la page (`show`), si activé.
13- Peut utiliser l'icône de la page comme favicon d'onglet (`show_as_favicon`).
14- Fournit une page de gestion d'icône par page : `?do=pagesicon`.
15- Gère les variantes `big` et `small`.
16- Notifie les autres plugins quand une icône change via `PLUGIN_PAGESICON_UPDATED` (pour invalider leurs caches).
17
18## Paramètres de configuration
19
20Dans le `Configuration Manager` :
21
22- `icon_name` : noms candidats pour l'icône `big` (séparés par `;`).
23 Supporte `~pagename~`.
24
25- `icon_thumbnail_name` : noms candidats pour l'icône `small` (séparés par `;`).
26 Supporte `~pagename~`.
27
28- `default_image` : image par défaut (mediaID) utilisée uniquement quand le fallback est explicitement activé dans l'API helper.
29
30- `icon_size` : taille (px) de l'icône affichée en haut de page.
31
32- `extensions` : extensions autorisées (séparées par `;`), par exemple `svg;png;jpg;jpeg`.
33
34- `show_on_top` : activer/désactiver l'affichage en haut de page.
35
36- `show_as_favicon` : utiliser l'icône de la page comme favicon.
37
38## Usage
39
40Depuis une page, utiliser l'action `Gérer l'icône` puis uploader/supprimer.
41
42Le plugin travaille sur la **page courante** (`$ID`), pas sur une cible passée en paramètre.
43
44## API helper
45
46Charger le helper :
47
48```php
49$pagesicon = plugin_load('helper', 'pagesicon');
50```
51
52### Résolution en mediaID
53
54- `getPageIconId(string $namespace, string $pageID, string $size = 'bigorsmall')`
55 Retourne un mediaID (`ns:file.ext`) ou `false`.
56
57- `getMediaIconId(string $mediaID, string $size = 'bigorsmall')`
58 Retourne le mediaID d'icône pour un média, ou `false`.
59
60`size` accepte : `big`, `small`, `bigorsmall`, `smallorbig`.
61
62### Résolution en URL versionnée
63
64- `getPageIconUrl(string $namespace, string $pageID, string $size = 'bigorsmall', array $params = ['width' => 55], ?int &$mtime = null, bool $withDefault = false)`
65 Retourne une URL d'icône (avec `pi_ts=<filemtime>`) ou `false`.
66 Renseigne aussi `$mtime`.
67
68- `getMediaIconUrl(string $mediaID, string $size = 'bigorsmall', array $params = ['width' => 55], ?int &$mtime = null, bool $withDefault = false)`
69 Retourne une URL d'icône de média (avec `pi_ts=<filemtime>`) ou `false`.
70 Renseigne aussi `$mtime`.
71
72- `getDefaultIconUrl(array $params = ['width' => 55], ?int &$mtime = null)`
73 Retourne l'URL de l'image par défaut configurée, ou `false`.
74
75### URLs de gestion
76
77- `getUploadIconPage(string $targetPage = '')`
78 Retourne l'URL `?do=pagesicon` d'une page, ou `null` si non autorisé.
79
80- `getUploadMediaIconPage(string $mediaID = '')`
81 Retourne l'URL de gestion d'icône associée à un média.
82
83### Notification
84
85- `notifyIconUpdated(string $targetPage, string $action = 'update', string $mediaID = '')`
86
87Effets :
88- met à jour `purgefile`,
89- déclenche l'événement `PLUGIN_PAGESICON_UPDATED`.
90
91Payload :
92- `target_page`,
93- `action`,
94- `media_id`.
95
96Chaque plugin consommateur est responsable de sa propre invalidation de cache.
97
98## Compatibilité des signatures
99
100- Avant `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
106La compatibilité est conservée via des alias legacy :
107- `getPageImage(...)` -> `getPageIconId(...)` (le paramètre legacy `$withDefault` est ignoré)
108- `getMediaImage(...)` -> `getMediaIconId(...)` (le paramètre legacy `$withDefault` est ignoré)
109- `getImageIcon(...)` -> `getPageIconUrl(...)`
110- `getMediaIcon(...)` -> `getMediaIconUrl(...)`
111- `getDefaultImageIcon(...)` -> `getDefaultIconUrl(...)`
112
README_EN.md
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