Wiki source code of Skin Extensions

Last modified by Eleni Cojocariu on 2026/11/13 12:33

Show last authors
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.

Get Connected