1====== Pagesicon Plugin ====== 2 3---- plugin ---- 4description: Gère et expose des icônes de page et de média 5author : Valentin LORTET 6email : contact@valentinlortet.fr 7type : Action, Helper 8lastupdate : 2026-03-12 9compatible : Librarian 10depends : 11conflicts : 12similar : 13tags : Media, UI, Navigation, Helper, Icons 14 15downloadurl: https://github.com/Lortet/dokuwiki-plugin-pagesicon/zipball/master 16bugtracker : https://github.com/Lortet/dokuwiki-plugin-pagesicon/issues 17sourcerepo : https://github.com/Lortet/dokuwiki-plugin-pagesicon/ 18donationurl: 19screenshot_img : 20---- 21 22===== Installation ===== 23 24Installer le plugin depuis le [[fr:plugin:extension|Gestionnaire d'extensions]] avec l'URL ci-dessus, ou en copiant le dossier dans ''lib/plugins/pagesicon''. 25 26===== Description ===== 27 28Le plugin **pagesicon** permet : 29 * d'afficher une icône en haut de la page ; 30 * d'utiliser cette icône comme favicon ; 31 * de gérer les icônes depuis l'action de page ''?do=pagesicon'' ; 32 * de gérer deux variantes : ''big'' et ''small'' ; 33 * d'exposer un helper pour les autres plugins. 34 35Le plugin travaille sur la page courante. Il n'y a pas de cible externe à saisir pour l'écran de gestion. 36 37===== Paramètres ===== 38 39^ Nom ^ Description ^ Valeur par défaut ^ 40| icon_name | Noms candidats pour l'icône ''big'' (séparés par '';''). Supporte ''~pagename~''. | ''~pagename~;icon_thumbnail;icon'' | 41| icon_thumbnail_name | Noms candidats pour l'icône ''small'' (séparés par '';''). Supporte ''~pagename~''. | ''~pagename~;icon'' | 42| default_image | Image par défaut (mediaID), utilisée seulement quand une méthode helper demande explicitement un fallback. | '''' | 43| icon_size | Taille de l'icône affichée en haut de page (px). | ''55'' | 44| extensions | Extensions d'images autorisées (séparées par '';''). | ''svg;png;jpg;jpeg'' | 45| show_on_top | Afficher l'icône en haut de page. | ''true'' | 46| show_as_favicon | Utiliser l'icône comme favicon. | ''true'' | 47| parent_fallback | Politique d'héritage si la page n'a pas d'icône : aucune, parent direct, ou première icône trouvée en remontant les parents. | ''none'' | 48 49===== Utilisation ===== 50 51Depuis une page, utiliser l'action **Gérer l'icône** puis : 52 * importer une icône ''big'' ; 53 * importer une icône ''small'' ; 54 * supprimer l'icône actuelle. 55 56Le formulaire : 57 * calcule les noms de fichiers autorisés à partir de la configuration ; 58 * limite les extensions à la liste configurée ; 59 * ouvre le gestionnaire de médias sur le namespace de la page. 60 61===== API Helper ===== 62 63Charger le helper : 64''$pagesicon = plugin_load('helper', 'pagesicon');'' 65 66==== Méthodes principales ==== 67 68^ Méthode ^ Depuis ^ Description ^ 69| ''getPageIconId($namespace, $pageID, $size = 'bigorsmall')'' | ''2026-03-09'' | Retourne le mediaID de l'icône d'une page, ou ''false''. | 70| ''getMediaIconId($mediaID, $size = 'bigorsmall')'' | ''2026-03-09'' | Retourne le mediaID de l'icône associée à un média, ou ''false''. | 71| ''getPageIconUrl($namespace, $pageID, $size = 'bigorsmall', $params = ['width' => 55], &$mtime = null, $withDefault = false)'' | ''2026-03-09'' | Retourne l'URL versionnée d'une icône de page, ou ''false''. | 72| ''getMediaIconUrl($mediaID, $size = 'bigorsmall', $params = ['width' => 55], &$mtime = null, $withDefault = false)'' | ''2026-03-09'' | Retourne l'URL versionnée d'une icône associée à un média, ou ''false''. | 73| ''getDefaultIconUrl($params = ['width' => 55], &$mtime = null)'' | ''2026-03-09'' | Retourne l'image par défaut à utiliser quand aucune icône n'est trouvée. | 74| ''getUploadIconPage($targetPage = "")'' | ''2026-03-06'' | Retourne l'URL ''?do=pagesicon'' d'une page, ou ''null'' si non autorisé. | 75| ''getUploadMediaIconPage($mediaID = "")'' | ''2026-03-06'' | Retourne l'URL de gestion d'icône associée à un média. | 76| ''notifyIconUpdated($targetPage, $action = "update", $mediaID = "")'' | ''2026-03-06'' | Déclenche l'événement d'invalidation de cache. | 77| ''isPageIconMedia($mediaID)'' | ''2026-03-11'' | Indique si un média doit être considéré comme une icône gérée par le plugin. | 78 79===== Événement ===== 80 81Lors d'un upload ou d'une suppression, le plugin émet : 82 * ''PLUGIN_PAGESICON_UPDATED'' 83 84Payload : 85 * ''target_page'' 86 * ''action'' 87 * ''media_id'' 88 89Les plugins consommateurs restent responsables de leur propre invalidation de cache. 90 91===== Compatibilité ===== 92 93Les anciennes signatures de l'API sont conservées via des alias legacy. 94 95^ Alias historique ^ Ajout ^ Déprécié ^ Remplacement ^ 96| ''getPageImage(...)'' | ''2026-03-06'' | ''2026-03-09'' | ''getPageIconId(...)'' | 97| ''getMediaImage(...)'' | ''2026-03-06'' | ''2026-03-09'' | ''getMediaIconId(...)'' | 98| ''getImageIcon(...)'' | ''2026-03-06'' | ''2026-03-09'' | ''getPageIconUrl(...)'' | 99| ''getMediaIcon(...)'' | ''2026-03-06'' | ''2026-03-09'' | ''getMediaIconUrl(...)'' | 100| ''getDefaultImageIcon(...)'' | ''2026-03-09'' | ''2026-03-09'' | ''getDefaultIconUrl(...)'' | 101 102===== Fonctionnement ===== 103 104La résolution d'une icône suit l'ordre défini par la configuration : 105 * noms configurés pour la variante demandée ; 106 * remplacements de ''~pagename~'' ; 107 * fallbacks historiques du plugin comme ''logo'' et ''thumbnail''. 108 109Si aucune icône n'est trouvée sur la page elle-même, le plugin peut aussi hériter : 110 * d'aucune icône ; 111 * de l'icône du parent direct ; 112 * de la première icône trouvée en remontant les parents. 113 114Les URLs retournées par le helper sont versionnées avec un paramètre ''pi_ts'' basé sur le ''filemtime'' du média. 115 116===== Notes ===== 117 118 * Le plugin ignore les pages techniques comme ''sidebar'' et ''footer'' lors de l'injection d'icône/favicon, pour éviter qu'un include de layout remplace l'icône de la page courante. 119 * L'écran de gestion utilise la configuration actuelle du plugin. Si une configuration obligatoire est vide ou invalide, le plugin émet un warning PHP et n'invente pas de valeur de secours. 120