Wiki source code of Skin Extensions
Last modified by Eleni Cojocariu on 2026/11/13 12:33
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | The [[Skin Extension Plugin>>doc:extensions:Extension.Skin.Skin Extension Plugin]] lets an interface component pull the CSS and the JavaScript it needs, so a page or a whole wiki changes its look and its behaviour without anybody editing the skin's templates or stylesheets. The artifact is ##xwiki-platform-skin-skinx##, whose sources are in {{scm path="xwiki-platform-core/xwiki-platform-skin/xwiki-platform-skin-skinx"/}}. | ||
| 2 | |||
| 3 | An extension is an [[XWiki object>>doc:documentation.xs.dev.data-model.x-objects.WebHome]] on a wiki page, of class ##XWiki.JavaScriptExtension## (JSX) or ##XWiki.StyleSheetExtension## (SSX). Being an object, it is written from the browser, with no access to the filesystem and no restart. SSX works exactly like JSX, the only difference being that the code is CSS. [[Create a Skin Extension>>doc:documentation.xs.dev.skin-extensions.create.WebHome]] is the procedure, and [[Skin Extension Object Fields>>doc:documentation.xs.dev.skin-extensions.object-fields.WebHome]] says what each field of the two classes decides. | ||
| 4 | |||
| 5 | Those two classes are the wiki page form of the mechanism. The plugin ships seven pull hints in all, and four of them take their code from a file of the current skin or from a resource inside a JAR instead of from a page. [[Skin Extension Script API>>doc:documentation.xs.dev.skin-extensions.script-api.WebHome]] lists them with the script call each one answers to. | ||
| 6 | |||
| 7 | An extension is pulled on the pages that need it, from a wiki page or from a Velocity template, or set to load on every page of the wiki. A pull reaches the reader in two round trips: | ||
| 8 | |||
| 9 | {{plantuml}} | ||
| 10 | @startuml | ||
| 11 | !theme bluegray | ||
| 12 | ' ---- XWiki accessible diagram palette (WCAG 2.1 AA): paste verbatim under | ||
| 13 | ' !theme bluegray. Canonical copy: xwiki-doc-writing/tools/ in xwiki-dev-llm. | ||
| 14 | skinparam activity { | ||
| 15 | BackgroundColor #0568AE | ||
| 16 | BorderColor #034873 | ||
| 17 | FontColor #FFFFFF | ||
| 18 | StartColor #04538B | ||
| 19 | EndColor #04538B | ||
| 20 | BarColor #5A5A5A | ||
| 21 | ' Diamonds are blue with white text, not light with dark text: a labelled | ||
| 22 | ' `repeat :x;` takes its fill from DiamondBackgroundColor but its font from | ||
| 23 | ' FontColor above, so a light fill draws that one box white on white, and no | ||
| 24 | ' selector reaches it without reaching the decision diamonds too. | ||
| 25 | DiamondBackgroundColor #0568AE | ||
| 26 | DiamondBorderColor #034873 | ||
| 27 | DiamondFontColor #FFFFFF | ||
| 28 | } | ||
| 29 | skinparam state { | ||
| 30 | BackgroundColor #0568AE | ||
| 31 | BorderColor #034873 | ||
| 32 | FontColor #FFFFFF | ||
| 33 | AttributeFontColor #FFFFFF | ||
| 34 | StartColor #04538B | ||
| 35 | EndColor #04538B | ||
| 36 | } | ||
| 37 | skinparam class { | ||
| 38 | BackgroundColor #0568AE | ||
| 39 | BorderColor #034873 | ||
| 40 | FontColor #FFFFFF | ||
| 41 | HeaderBackgroundColor #0568AE | ||
| 42 | AttributeFontColor #FFFFFF | ||
| 43 | StereotypeFontColor #262626 | ||
| 44 | } | ||
| 45 | skinparam object { | ||
| 46 | BackgroundColor #0568AE | ||
| 47 | BorderColor #034873 | ||
| 48 | FontColor #FFFFFF | ||
| 49 | AttributeFontColor #FFFFFF | ||
| 50 | StereotypeFontColor #262626 | ||
| 51 | } | ||
| 52 | skinparam participant { | ||
| 53 | BackgroundColor #0568AE | ||
| 54 | BorderColor #034873 | ||
| 55 | FontColor #FFFFFF | ||
| 56 | } | ||
| 57 | skinparam actor { | ||
| 58 | BackgroundColor #F5F5F5 | ||
| 59 | BorderColor #5A5A5A | ||
| 60 | FontColor #262626 | ||
| 61 | } | ||
| 62 | skinparam component { | ||
| 63 | BackgroundColor #0568AE | ||
| 64 | BorderColor #034873 | ||
| 65 | FontColor #FFFFFF | ||
| 66 | } | ||
| 67 | skinparam collections { | ||
| 68 | BackgroundColor #0568AE | ||
| 69 | BorderColor #034873 | ||
| 70 | FontColor #FFFFFF | ||
| 71 | } | ||
| 72 | skinparam queue { | ||
| 73 | BackgroundColor #0568AE | ||
| 74 | BorderColor #034873 | ||
| 75 | FontColor #FFFFFF | ||
| 76 | } | ||
| 77 | skinparam stack { | ||
| 78 | BackgroundColor #0568AE | ||
| 79 | BorderColor #034873 | ||
| 80 | FontColor #FFFFFF | ||
| 81 | } | ||
| 82 | ' database, control, entity, boundary and interface draw their label beside or | ||
| 83 | ' under the icon, on the page, in some diagram types: their text stays dark. | ||
| 84 | skinparam database { | ||
| 85 | BackgroundColor #F5F5F5 | ||
| 86 | BorderColor #5A5A5A | ||
| 87 | FontColor #262626 | ||
| 88 | } | ||
| 89 | skinparam control { | ||
| 90 | BackgroundColor #0568AE | ||
| 91 | BorderColor #034873 | ||
| 92 | FontColor #262626 | ||
| 93 | } | ||
| 94 | skinparam entity { | ||
| 95 | BackgroundColor #0568AE | ||
| 96 | BorderColor #034873 | ||
| 97 | FontColor #262626 | ||
| 98 | } | ||
| 99 | skinparam boundary { | ||
| 100 | BackgroundColor #0568AE | ||
| 101 | BorderColor #034873 | ||
| 102 | FontColor #262626 | ||
| 103 | } | ||
| 104 | skinparam usecase { | ||
| 105 | BackgroundColor #0568AE | ||
| 106 | BorderColor #034873 | ||
| 107 | FontColor #FFFFFF | ||
| 108 | StereotypeFontColor #FFFFFF | ||
| 109 | } | ||
| 110 | skinparam card { | ||
| 111 | BackgroundColor #04538B | ||
| 112 | BorderColor #034873 | ||
| 113 | FontColor #FFFFFF | ||
| 114 | } | ||
| 115 | skinparam note { | ||
| 116 | BackgroundColor #04538B | ||
| 117 | BorderColor #034873 | ||
| 118 | FontColor #FFFFFF | ||
| 119 | } | ||
| 120 | skinparam storage { | ||
| 121 | BackgroundColor #8A4A00 | ||
| 122 | BorderColor #8A4A00 | ||
| 123 | FontColor #FFFFFF | ||
| 124 | } | ||
| 125 | skinparam agent { | ||
| 126 | BackgroundColor #8A4A00 | ||
| 127 | BorderColor #8A4A00 | ||
| 128 | FontColor #FFFFFF | ||
| 129 | } | ||
| 130 | skinparam interface { | ||
| 131 | BackgroundColor #A62222 | ||
| 132 | BorderColor #A62222 | ||
| 133 | FontColor #262626 | ||
| 134 | } | ||
| 135 | skinparam node { | ||
| 136 | BackgroundColor #F5F5F5 | ||
| 137 | BorderColor #5A5A5A | ||
| 138 | FontColor #262626 | ||
| 139 | } | ||
| 140 | skinparam cloud { | ||
| 141 | BackgroundColor #F5F5F5 | ||
| 142 | BorderColor #5A5A5A | ||
| 143 | FontColor #262626 | ||
| 144 | } | ||
| 145 | skinparam artifact { | ||
| 146 | BackgroundColor #F5F5F5 | ||
| 147 | BorderColor #5A5A5A | ||
| 148 | FontColor #262626 | ||
| 149 | } | ||
| 150 | skinparam file { | ||
| 151 | BackgroundColor #F5F5F5 | ||
| 152 | BorderColor #5A5A5A | ||
| 153 | FontColor #262626 | ||
| 154 | } | ||
| 155 | skinparam rectangle { | ||
| 156 | BackgroundColor #FFFFFF | ||
| 157 | BorderColor #5A5A5A | ||
| 158 | FontColor #262626 | ||
| 159 | StereotypeFontColor #0568AE | ||
| 160 | } | ||
| 161 | skinparam folder { | ||
| 162 | BackgroundColor #F5F5F5 | ||
| 163 | BorderColor #8A4A00 | ||
| 164 | FontColor #8A4A00 | ||
| 165 | } | ||
| 166 | skinparam frame { | ||
| 167 | BackgroundColor #F5F5F5 | ||
| 168 | BorderColor #04538B | ||
| 169 | FontColor #04538B | ||
| 170 | } | ||
| 171 | skinparam package { | ||
| 172 | BackgroundColor #FFFFFF | ||
| 173 | BorderColor #0568AE | ||
| 174 | FontColor #262626 | ||
| 175 | } | ||
| 176 | skinparam partition { | ||
| 177 | BackgroundColor #FFFFFF | ||
| 178 | BorderColor #0568AE | ||
| 179 | FontColor #0568AE | ||
| 180 | } | ||
| 181 | skinparam swimlane { | ||
| 182 | BorderColor #0568AE | ||
| 183 | TitleBackgroundColor #F5F5F5 | ||
| 184 | TitleFontColor #0568AE | ||
| 185 | } | ||
| 186 | skinparam sequence { | ||
| 187 | BoxBackgroundColor #F5F5F5 | ||
| 188 | BoxBorderColor #5A5A5A | ||
| 189 | BoxFontColor #262626 | ||
| 190 | DelayFontColor #262626 | ||
| 191 | GroupBorderColor #5A5A5A | ||
| 192 | GroupFontColor #262626 | ||
| 193 | LifeLineBorderColor #5A5A5A | ||
| 194 | LifeLineBackgroundColor #F5F5F5 | ||
| 195 | TitleFontColor #0568AE | ||
| 196 | StartColor #0568AE | ||
| 197 | EndColor #0568AE | ||
| 198 | BorderColor #0568AE | ||
| 199 | } | ||
| 200 | skinparam arrow { | ||
| 201 | Color #0568AE | ||
| 202 | FontColor #262626 | ||
| 203 | } | ||
| 204 | skinparam legend { | ||
| 205 | BackgroundColor #F5F5F5 | ||
| 206 | BorderColor #5A5A5A | ||
| 207 | FontColor #262626 | ||
| 208 | } | ||
| 209 | skinparam stereotype { | ||
| 210 | CBackgroundColor #F5F5F5 | ||
| 211 | CBorderColor #5A5A5A | ||
| 212 | ABackgroundColor #F5F5F5 | ||
| 213 | ABorderColor #5A5A5A | ||
| 214 | IBackgroundColor #F5F5F5 | ||
| 215 | IBorderColor #5A5A5A | ||
| 216 | EBackgroundColor #F5F5F5 | ||
| 217 | EBorderColor #5A5A5A | ||
| 218 | NBackgroundColor #F5F5F5 | ||
| 219 | NBorderColor #5A5A5A | ||
| 220 | } | ||
| 221 | skinparam ArrowColor #0568AE | ||
| 222 | ' titleFontColor only: the nested `skinparam title { BackgroundColor }` form | ||
| 223 | ' leaks its background onto every element in the diagram. | ||
| 224 | skinparam titleFontColor #0568AE | ||
| 225 | skinparam titleBorderColor #5A5A5A | ||
| 226 | ' Links otherwise take bluegray's white root colour, unreadable on a light fill. | ||
| 227 | <style> | ||
| 228 | root { | ||
| 229 | HyperLinkColor #0568AE | ||
| 230 | } | ||
| 231 | element { | ||
| 232 | HyperLinkColor #FFFFFF | ||
| 233 | } | ||
| 234 | actor, artifact, boundary, cloud, control, database, entity, file, folder, frame, interface, | ||
| 235 | legend, node, package, rectangle { | ||
| 236 | HyperLinkColor #0568AE | ||
| 237 | } | ||
| 238 | </style> | ||
| 239 | ' ---- end XWiki accessible diagram palette ---- | ||
| 240 | |||
| 241 | participant "wiki page or\nVelocity template" as Caller | ||
| 242 | participant "skinx plugin" as Plugin | ||
| 243 | participant "the response" as Html | ||
| 244 | participant "the browser" as Browser | ||
| 245 | participant "the jsx or ssx action" as Action | ||
| 246 | |||
| 247 | Caller -> Plugin : $xwiki.jsx.use('My.Page') | ||
| 248 | Plugin -> Plugin : records the pull\nfor this request | ||
| 249 | Plugin -> Html : at the end of parsing, replaces the first\nHTML comment named after the plugin class\nwith the generated script tag | ||
| 250 | Html -> Browser : the page, script tag included | ||
| 251 | Browser -> Action : GET /bin/jsx/My/Page | ||
| 252 | Action -> Action : reads the objects of the page,\nparses Velocity or compiles LESS,\nminifies, sets the cache headers | ||
| 253 | Action -> Browser : the extension | ||
| 254 | @enduml | ||
| 255 | {{/plantuml}} | ||
| 256 | |||
| 257 | The comment the plugin writes over is the fully qualified name of the plugin class, {{code language="none"}}<!-- com.xpn.xwiki.plugin.skinx.JsSkinExtensionPlugin -->{{/code}}, and the skin's templates are what leave it in the response: the {{code language="none"}}#javaScriptExtensionHooks{{/code}} and {{code language="none"}}#styleSheetExtensionHooks{{/code}} macros of ##macros.vm## emit one comment per plugin class. Their order there is deliberate, resource then skin file then object, so that a later style sheet overrides an earlier one. Only the first occurrence is replaced, and the plugin does not check that it found one, which is why an extension that never arrives says nothing in the log. Read the page source and look for the comment before suspecting the object. | ||
| 258 | |||
| 259 | A page holds as many objects of a class as it needs, and the response is the concatenation of all of them in document order, one newline apart. The document is therefore the extension, not a container of extensions: several objects are parts of one extension, never two independent ones. The scope follows the same rule. Since the whole document is served as a single response, an object set to load on every page drags every other object of its class on that page into every page of the wiki, so extensions whose scopes differ belong on separate pages. | ||
| 260 | |||
| 261 | The code of an extension does not have to be written by hand. [[Generate Skin Extension Content with Velocity>>doc:documentation.xs.dev.skin-extensions.velocity.WebHome]] covers the extensions the server computes per request, and [[Write a Style Sheet Extension in LESS>>doc:documentation.xs.dev.skin-extensions.less.WebHome]] the style sheets compiled against the variables of the current skin. | ||
| 262 | |||
| 263 | The [[Skin>>doc:documentation.xs.dev.skin.WebHome]] module is a different mechanism. It is the Java API that finds a file inside a skin and follows the skin's inheritance, and it has no part in contributing code to a response. |