1====== Pagesicon Plugin ====== 2 3---- plugin ---- 4description: Manage and expose page and media icons 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 24Install the plugin from the [[plugin:extension|Extension Manager]] using the URL above, or copy it into ''lib/plugins/pagesicon''. 25 26===== Description ===== 27 28The **pagesicon** plugin can: 29 * display an icon at the top of the page; 30 * use this icon as the page favicon; 31 * manage icons from the page action ''?do=pagesicon''; 32 * handle two variants: ''big'' and ''small''; 33 * expose a helper API for other plugins. 34 35The plugin works on the current page. There is no external target to fill in on the management screen. 36 37===== Settings ===== 38 39^ Name ^ Description ^ Default value ^ 40| icon_name | Candidate names for the ''big'' icon (separated by '';''). Supports ''~pagename~''. | ''~pagename~;icon_thumbnail;icon'' | 41| icon_thumbnail_name | Candidate names for the ''small'' icon (separated by '';''). Supports ''~pagename~''. | ''~pagename~;icon'' | 42| default_image | Default image (mediaID), used only when a helper method explicitly asks for a fallback. | '''' | 43| icon_size | Size of the icon displayed at the top of the page (px). | ''55'' | 44| extensions | Allowed image extensions (separated by '';''). | ''svg;png;jpg;jpeg'' | 45| show_on_top | Show the icon at the top of the page. | ''true'' | 46| show_as_favicon | Use the icon as favicon. | ''true'' | 47| parent_fallback | Fallback inheritance policy when the page has no icon: none, direct parent, or first icon found while walking up parent namespaces. | ''none'' | 48 49===== Usage ===== 50 51From a page, use the **Manage icon** action, then: 52 * upload a ''big'' icon; 53 * upload a ''small'' icon; 54 * delete the current icon. 55 56The form: 57 * computes the allowed target filenames from the configuration; 58 * limits uploads to the configured extensions; 59 * opens the media manager on the page namespace. 60 61===== Helper API ===== 62 63Load helper: 64''$pagesicon = plugin_load('helper', 'pagesicon');'' 65 66==== Main methods ==== 67 68^ Method ^ Since ^ Description ^ 69| ''getPageIconId($namespace, $pageID, $size = "bigorsmall")'' | ''2026-03-09'' | Returns the mediaID of a page icon, or ''false''. | 70| ''getMediaIconId($mediaID, $size = "bigorsmall")'' | ''2026-03-09'' | Returns the mediaID of the icon associated with a media file, or ''false''. | 71| ''getPageIconUrl($namespace, $pageID, $size = "bigorsmall", $params = ['width' => 55], &$mtime = null, $withDefault = false)'' | ''2026-03-09'' | Returns the versioned URL of a page icon, or ''false''. | 72| ''getMediaIconUrl($mediaID, $size = "bigorsmall", $params = ['width' => 55], &$mtime = null, $withDefault = false)'' | ''2026-03-09'' | Returns the versioned URL of the icon associated with a media file, or ''false''. | 73| ''getDefaultIconUrl($params = ['width' => 55], &$mtime = null)'' | ''2026-03-09'' | Returns the default image to use when no icon is found. | 74| ''getUploadIconPage($targetPage = "")'' | ''2026-03-06'' | Returns the ''?do=pagesicon'' URL for a page, or ''null'' when unauthorized. | 75| ''getUploadMediaIconPage($mediaID = "")'' | ''2026-03-06'' | Returns the icon management URL associated with a media file. | 76| ''notifyIconUpdated($targetPage, $action = "update", $mediaID = "")'' | ''2026-03-06'' | Triggers the cache invalidation event. | 77| ''isPageIconMedia($mediaID)'' | ''2026-03-11'' | Tells whether a media file should be considered an icon managed by the plugin. | 78 79==== Public utility methods ==== 80 81These methods are a bit more technical, but useful when another plugin wants to reuse the exact naming and configuration logic of ''pagesicon''. 82 83^ Method ^ Since ^ Description ^ 84| ''getConfiguredExtensions()'' | ''2026-03-11'' | Returns the configured list of allowed extensions. | 85| ''getVariantTemplates($variant)'' | ''2026-03-11'' | Returns the configured filename templates for ''big'' or ''small''. | 86| ''normalizeIconBaseName($name)'' | ''2026-03-11'' | Normalizes an icon filename without namespace or extension. | 87| ''getUploadNameChoices($targetPage, $variant)'' | ''2026-03-11'' | Returns the allowed target names for an upload. | 88 89===== Event ===== 90 91On upload or deletion, the plugin emits: 92 * ''PLUGIN_PAGESICON_UPDATED'' 93 94Payload: 95 * ''target_page'' 96 * ''action'' 97 * ''media_id'' 98 99Consumer plugins remain responsible for their own cache invalidation. 100 101===== Compatibility ===== 102 103Older API signatures are still available through legacy aliases. 104 105^ Historical alias ^ Added ^ Deprecated ^ Replacement ^ 106| ''getPageImage(...)'' | ''2026-03-06'' | ''2026-03-09'' | ''getPageIconId(...)'' | 107| ''getMediaImage(...)'' | ''2026-03-06'' | ''2026-03-09'' | ''getMediaIconId(...)'' | 108| ''getImageIcon(...)'' | ''2026-03-06'' | ''2026-03-09'' | ''getPageIconUrl(...)'' | 109| ''getMediaIcon(...)'' | ''2026-03-06'' | ''2026-03-09'' | ''getMediaIconUrl(...)'' | 110| ''getDefaultImageIcon(...)'' | ''2026-03-09'' | ''2026-03-09'' | ''getDefaultIconUrl(...)'' | 111 112===== How it works ===== 113 114Icon resolution follows the configured order: 115 * configured names for the requested variant; 116 * ''~pagename~'' replacements; 117 * historical plugin fallbacks such as ''logo'' and ''thumbnail''. 118 119If no icon is found on the page itself, the plugin can also inherit: 120 * no icon; 121 * the direct parent icon; 122 * the first icon found while walking up parent namespaces. 123 124The URLs returned by the helper are versioned with a ''pi_ts'' parameter based on the media ''filemtime''. 125 126===== Notes ===== 127 128 * The plugin ignores technical pages such as ''sidebar'' and ''footer'' during icon/favicon injection, to avoid a layout include replacing the current page icon. 129 * The management screen uses the current plugin configuration. If a required configuration is empty or invalid, the plugin emits a PHP warning and does not invent fallback values. 130