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