Skin API
Reference
The four roles of the org.xwiki.skin package. They are Java only: the skin module implements no script service, so there is no $services.skin for a wiki page. Sources: http://www.github.com/xwiki/xwiki-platform/tree/master/xwiki-platform-core/xwiki-platform-skin/xwiki-platform-skin-api/src/main/java/org/xwiki/skin.
SkinManager
The component to inject. It is the only way into the other three.
| Member | Returns | What it does |
|---|---|---|
| getSkin(String id) | Skin | The skin with that id. |
| getCurrentSkin(boolean testRights) | Skin | The skin of the current request, resolved through the levels the administration documents. With true the current user's view right is checked on the skin coming from the instance configuration only; a skin coming from the request or from a preference is returned unchecked. |
| getDefaultSkin() | Skin | The skin configured as the instance default. |
| getDefaultParentSkin() | Skin | The skin used as parent by any skin that names no parent of its own. |
Skin
Extends ResourceRepository, so it also has every member of the table below.
| Member | Returns | What it does |
|---|---|---|
| getParent() | Skin | The parent skin. Narrows ResourceRepository.getParent(), which returns a plain repository. |
| getOutputSyntax() | Syntax | The syntax the skin renders content into, inherited from the parent skin and defaulting to XHTML 1.0. |
ResourceRepository
Somewhere a resource name can be looked up. A skin is one, and so is whatever it inherits from.
| Member | Returns | What it does |
|---|---|---|
| getParent() | ResourceRepository | The repository used as fallback when this one does not hold the name. |
| getId() | String | The repository's identifier. |
| getResource(String resourceName) | Resource<?> | The named resource, walking the parent chain; null when no repository in the chain holds it. |
| getLocalResource(String resourceName) | Resource<?> | The named resource in this repository alone, without the parent chain; null when it does not hold it. |
The wildcard in Resource<?> is not a limitation of the lookup, only of what the repository can promise about the input source; the type parameter matters when a concrete implementation is held.
Resource
One file of a skin. Resource<I extends InputSource> is typed by the kind of input source it opens.
| Member | Returns | What it does |
|---|---|---|
| getRepository() | ResourceRepository | The repository the resource was found in. |
| getId() | String | The resource's unique identifier. |
| getPath() | String | The resource's path. |
| getResourceName() | String | The resource's name, usually a path relative to the repository. |
| getInputSource() | I | An input source for reading the resource. Throws Exception. |
| getInstant() | Instant | When the resource was last modified, or null when that is unknown. Default method. Throws Exception. |
| getURL(boolean forceSkinAction) | String | A URL for the resource; true forces a dynamic skin URL rather than a static one. Throws Exception. |
Getting a skin
A skin id is either a page reference or the name of a filesystem or JAR skin such as flamingo; which kind resolves to what is on the Skin Module.
@Inject
private SkinManager skinManager;
Skin skin = this.skinManager.getSkin("xwiki:Main.MySkin");The skin in effect for the current request comes from the same component:
// true checks the view right, but only on a skin that came from the configuration.
Skin currentSkin = this.skinManager.getCurrentSkin(true);Looking a resource up
Either lookup can come back empty:
// Walks the parent chain.
Resource<?> inherited = currentSkin.getResource("myscript.js");
// This skin only.
Resource<?> own = currentSkin.getLocalResource("myscript.js");
if (inherited != null) {
// Which skin the file came from.
ResourceRepository source = inherited.getRepository();
}FAQ
Which classes implement these roles?
DefaultSkinManager, WikiSkin, EnvironmentSkin and ClassLoaderSkin, none of them in this artifact. The Skin Module says where they live and why.
How do I know which skin a file came from?
Resource.getRepository(), which for a resource found through getResource() is the skin that actually held it rather than the one the lookup started from.
