Skin Extensions
Explanation
The 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 http://www.github.com/xwiki/xwiki-platform/tree/master/xwiki-platform-core/xwiki-platform-skin/xwiki-platform-skin-skinx.
An extension is an XWiki object 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 is the procedure, and Skin Extension Object Fields says what each field of the two classes decides.
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 lists them with the script call each one answers to.
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:
The comment the plugin writes over is the fully qualified name of the plugin class, <!-- com.xpn.xwiki.plugin.skinx.JsSkinExtensionPlugin -->, and the skin's templates are what leave it in the response: the #javaScriptExtensionHooks and #styleSheetExtensionHooks 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.
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.
The code of an extension does not have to be written by hand. Generate Skin Extension Content with Velocity covers the extensions the server computes per request, and Write a Style Sheet Extension in LESS the style sheets compiled against the variables of the current skin.
The Skin 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.
FAQ
When is a skin extension the right tool, rather than a front-end module?
The question is where the code is maintained. A skin extension is maintained inside the wiki, shipped in a XAR next to the pages that use it. Code that is built, versioned and tested outside the wiki belongs in a front-end module instead, which is what JavaScript and Front-End describe.
More
To find more about the current topic, you can search or use the table below and filter the columns to narrow your choices.
