README.md
1# Pagesicon
2
3J'aime beaucoup DokuWiki, mais je l'ai toujours trouvé un peu triste : il manquait un moyen simple d'ajouter de belles icônes aux pages.
4Avec **pagesicon**, c'est maintenant possible.
5
6Le plugin peut :
7- afficher une icône en haut de la page (show) ;
8- utiliser cette icône comme favicon de l'onglet (show_as_favicon) ;
9- afficher une icône devant les liens internes wiki ;
10- proposer une page de gestion d'ïcone avec `?do=pagesicon` ;
11- gèrer les variantes `big` et `small` suivant le contexte.
12- exposer un helper (API réutilisable) pour les autres plugins.
13
14## Utilisation
15
16Depuis une page, utilisez l'action `Gerer l'icône` pour
17- importer une icône `big` ;
18- importer une icône `small` ;
19- supprimer l'icône actuelle.
20
21## Configuration
22
23Dans le gestionnaire de configuration :
24- `icon_name` : noms de fichiers candidats pour l'icône `big`, séparés par `;`, avec support de `~pagename~`
25- `icon_thumbnail_name` : noms de fichiers candidats pour l'icône `small`, séparés par `;`, avec support de `~pagename~`
26- `default_image` : image par défaut utilisée seulement quand une méthode helper demande explicitement un fallback
27- `icon_size` : taille de l'icône affichée en haut de page
28- `extensions` : extensions autorisées, par exemple `svg;png;jpg;jpeg`
29- `show_on_top` : affiche l'icône dans la page
30- `show_as_favicon` : utilise l'icône comme favicon
31- `parent_fallback` : permet d'utiliser l'icône du parent si la page n'en a pas
32- `link_icons` : affiche une icône devant les liens internes (`none` / `existing` / `all`)
33
34## Ce que le helper fournit
35
36Charger le helper :
37
38```php
39$pagesicon = plugin_load('helper', 'pagesicon');
40```
41
42Methodes principales :
43
44- `getPageIconId()` : retourne le mediaID de l'icône d'une page
45- `getMediaIconId()` : retourne le mediaID de l'icône associée à un média
46- `getPageIconUrl()` : retourne l'URL versionnée de l'icône d'une page
47- `getMediaIconUrl()` : retourne l'URL versionnée de l'icône associée à un média
48- `getDefaultIconUrl()` : retourne l'URL de l'image par défaut à utiliser quand aucune icône n'est trouvée
49- `getUploadIconPage()` : retourne l'URL de gestion d'icône pour une page
50- `getUploadMediaIconPage()` : retourne l'URL de gestion d'icône pour un média
51- `notifyIconUpdated()` : notifie les autres plugins qu'une icône a changé
52
53## Cache et integrations
54
55Quand une icône est modifiée, le plugin déclenche l'événement `PLUGIN_PAGESICON_UPDATED`.
56
57Cela permet aux autres plugins de recharger ou invalider leur propre cache si besoin.
58
59## Héritage d'icône
60
61Si aucune icône n'est trouvée sur la page, le plugin peut aussi :
62- ne rien hériter ;
63- utiliser l'icône du parent direct ;
64- utiliser la première icône trouvée en remontant les parents.
65
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
6The plugin can:
7- display an icon at the top of the page (`show`);
8- use this icon as the browser tab favicon (`show_as_favicon`);
9- display an icon before internal wiki links;
10- provide an icon management page with `?do=pagesicon`;
11- handle `big` and `small` variants depending on the context;
12- expose a helper (reusable API) for other plugins.
13
14## Usage
15
16From a page, use the `Manage icon` action to:
17- upload a `big` icon;
18- upload a `small` icon;
19- delete the current icon.
20
21## Configuration
22
23In the configuration manager:
24- `icon_name`: candidate filenames for the `big` icon, separated by `;`, with support for `~pagename~`
25- `icon_thumbnail_name`: candidate filenames for the `small` icon, separated by `;`, with support for `~pagename~`
26- `default_image`: default image used only when a helper method explicitly asks for a fallback
27- `icon_size`: size of the icon displayed at the top of the page
28- `extensions`: allowed extensions, for example `svg;png;jpg;jpeg`
29- `show_on_top`: displays the icon in the page
30- `show_as_favicon`: uses the icon as favicon
31- `parent_fallback`: allows using a parent icon when the page has none
32- `link_icons`: displays an icon before internal links (`none` / `existing` / `all`)
33
34## What the helper provides
35
36Load helper:
37
38```php
39$pagesicon = plugin_load('helper', 'pagesicon');
40```
41
42Main methods:
43
44- `getPageIconId()`: returns the media ID of a page icon
45- `getMediaIconId()`: returns the media ID of the icon associated with a media file
46- `getPageIconUrl()`: returns the versioned URL of a page icon
47- `getMediaIconUrl()`: returns the versioned URL of the icon associated with a media file
48- `getDefaultIconUrl()`: returns the URL of the default image to use when no icon is found
49- `getUploadIconPage()`: returns the icon management URL for a page
50- `getUploadMediaIconPage()`: returns the icon management URL for a media file
51- `notifyIconUpdated()`: notifies other plugins that an icon changed
52
53## Cache and integrations
54
55When an icon is modified, the plugin triggers the `PLUGIN_PAGESICON_UPDATED` event.
56
57This allows other plugins to refresh or invalidate their own cache when needed.
58
59## Icon inheritance
60
61If no icon is found on the page itself, the plugin can also:
62- inherit no icon;
63- use the direct parent icon;
64- use the first icon found while walking up parent namespaces.
65