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-11 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 48===== Usage ===== 49 50From a page, use the **Manage icon** action, then: 51 * upload a ''big'' icon; 52 * upload a ''small'' icon; 53 * delete the current icon. 54 55The form: 56 * computes the allowed target filenames from the configuration; 57 * limits uploads to the configured extensions; 58 * opens the media manager on the page namespace. 59 60===== Helper API ===== 61 62Load helper: 63''$pagesicon = plugin_load('helper', 'pagesicon');'' 64 65==== Main methods ==== 66 67^ Method ^ Since ^ Description ^ 68| ''getPageIconId($namespace, $pageID, $size = "bigorsmall")'' | ''2026-03-09'' | Returns the mediaID of a page icon, or ''false''. | 69| ''getMediaIconId($mediaID, $size = "bigorsmall")'' | ''2026-03-09'' | Returns the mediaID of the icon associated with a media file, or ''false''. | 70| ''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''. | 71| ''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''. | 72| ''getDefaultIconUrl($params = ['width' => 55], &$mtime = null)'' | ''2026-03-09'' | Returns the default image to use when no icon is found. | 73| ''getUploadIconPage($targetPage = "")'' | ''2026-03-06'' | Returns the ''?do=pagesicon'' URL for a page, or ''null'' when unauthorized. | 74| ''getUploadMediaIconPage($mediaID = "")'' | ''2026-03-06'' | Returns the icon management URL associated with a media file. | 75| ''notifyIconUpdated($targetPage, $action = "update", $mediaID = "")'' | ''2026-03-06'' | Triggers the cache invalidation event. | 76| ''isPageIconMedia($mediaID)'' | ''2026-03-11'' | Tells whether a media file should be considered an icon managed by the plugin. | 77 78==== Public utility methods ==== 79 80These methods are a bit more technical, but useful when another plugin wants to reuse the exact naming and configuration logic of ''pagesicon''. 81 82^ Method ^ Since ^ Description ^ 83| ''getConfiguredExtensions()'' | ''2026-03-11'' | Returns the configured list of allowed extensions. | 84| ''getVariantTemplates($variant)'' | ''2026-03-11'' | Returns the configured filename templates for ''big'' or ''small''. | 85| ''normalizeIconBaseName($name)'' | ''2026-03-11'' | Normalizes an icon filename without namespace or extension. | 86| ''getUploadNameChoices($targetPage, $variant)'' | ''2026-03-11'' | Returns the allowed target names for an upload. | 87 88===== Event ===== 89 90On upload or deletion, the plugin emits: 91 * ''PLUGIN_PAGESICON_UPDATED'' 92 93Payload: 94 * ''target_page'' 95 * ''action'' 96 * ''media_id'' 97 98Consumer plugins remain responsible for their own cache invalidation. 99 100===== Compatibility ===== 101 102Older API signatures are still available through legacy aliases. 103 104^ Historical alias ^ Added ^ Deprecated ^ Replacement ^ 105| ''getPageImage(...)'' | ''2026-03-06'' | ''2026-03-09'' | ''getPageIconId(...)'' | 106| ''getMediaImage(...)'' | ''2026-03-06'' | ''2026-03-09'' | ''getMediaIconId(...)'' | 107| ''getImageIcon(...)'' | ''2026-03-06'' | ''2026-03-09'' | ''getPageIconUrl(...)'' | 108| ''getMediaIcon(...)'' | ''2026-03-06'' | ''2026-03-09'' | ''getMediaIconUrl(...)'' | 109| ''getDefaultImageIcon(...)'' | ''2026-03-09'' | ''2026-03-09'' | ''getDefaultIconUrl(...)'' | 110 111===== How it works ===== 112 113Icon resolution follows the configured order: 114 * configured names for the requested variant; 115 * ''~pagename~'' replacements; 116 * historical plugin fallbacks such as ''logo'' and ''thumbnail''. 117 118The URLs returned by the helper are versioned with a ''pi_ts'' parameter based on the media ''filemtime''. 119 120===== Notes ===== 121 122 * The plugin ignores technical pages such as ''sidebar'' and ''footer'' during icon/favicon injection, to avoid a layout include replacing the current page icon. 123 * 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. 124