Skin Extension Object Fields
Reference
The fields of the two skin extension classes, XWiki.JavaScriptExtension and XWiki.StyleSheetExtension, and what each one decides once the object is saved. Create a Skin Extension is the procedure that fills them in, and Skin Extensions explains the mechanism they configure.
The fields
Both classes carry the first five fields. contentType is on the style sheet class only.
| Field | Label in the object editor | Type | What it holds |
|---|---|---|---|
| name | Name | text | Free text. Purely descriptive: the plugin never reads it, and an extension is identified by the page that holds it. |
| code | Code | plain text area | The CSS or the JavaScript that is served. |
| use | Use this extension | list | When the extension loads. Three values, no default. |
| parse | Parse content | yes or no | Whether the code is evaluated as Velocity first. |
| cache | Caching policy | list | The cache headers of the generated file. Four values, default long. |
| contentType | Content Type | list | CSS or LESS. Style sheets only. |
Use this extension
| Value | Label in the editor | When the extension loads | Right the page author needs |
|---|---|---|---|
| currentPage | On this page or on demand | On the page holding the object, and whenever it is pulled | SCRIPT on that page |
| onDemand | On demand only | Only when it is pulled | SCRIPT on that page |
| always | On this wiki | On every page of the wiki | ADMIN on the wiki |
Pulling is done with the script calls on Skin Extension Script API. The right in the last column is checked on the author of the page holding the object, not on the reader and not on whoever pulls it; the reader needs VIEW on that page as well, or the extension is not served and no link to it is even generated. Both rights are described under Right Types.
Parse content
The evaluation happens before minification, so an extension can compute its content instead of storing it. Generate Skin Extension Content with Velocity covers what that allows and what it costs.
Caching policy
| Value | Label in the editor | Cache headers on the generated file |
|---|---|---|
| long | Long | Public, and kept for 30 days. This is the default. |
| short | Short | Public, and kept for one day. |
| default | Default | Public, with no expiry of its own. |
| forbid | No caching | Cache-Control: no-cache, no-store, must-revalidate. |
A long policy does not delay a change to the code. The generated URL carries the page version as a docVersion parameter, so saving the object changes the URL and the browser fetches the new file whatever it had cached.
Content Type
Only on XWiki.StyleSheetExtension. CSS serves the code as it stands, and LESS compiles it first, against the variables of the current skin. Write a Style Sheet Extension in LESS covers the second.
Several objects on one page
Several objects of the same class on one page are served as a single file. parse and contentType are read per object, so one object can be parsed and the next one not, and a CSS object can sit beside a LESS one. The caching policy is not read per object: it is shared by the whole page, and the strictest value present wins for all of them, long being the weakest and forbid the strongest. An object that leaves the field empty counts as long.
JavaScript strict mode
skinx.jsStrictModeEnabled in xwiki.properties decides whether JavaScript extensions are treated as strict mode code. It is false by default. Set to true, the code is parsed expecting strict mode and the minified JavaScript carries the strict mode directive; when that parsing fails, XWiki serves the unminified source instead and logs the errors. It improves performance and security, but it can break extensions that were not written for it.
FAQ
An extension set to load on this wiki does nothing. Why?
The author of the page holding the object needs ADMIN on the wiki, and the check runs when the page is saved: an object saved by an author without that right is left out of the set of always used extensions, and nothing in the interface says so. Only the log records it. Saving the page again, as an author who has the right, puts it back.
