Wiki source code of Skin API
Last modified by Eleni Cojocariu on 2026/10/01 08:44
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | 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: {{scm path="xwiki-platform-core/xwiki-platform-skin/xwiki-platform-skin-api/src/main/java/org/xwiki/skin"/}}. | ||
| 2 | |||
| 3 | == SkinManager == | ||
| 4 | |||
| 5 | The component to inject. It is the only way into the other three. | ||
| 6 | |||
| 7 | |=Member|=Returns|=What it does | ||
| 8 | |##getSkin(String id)##|##Skin##|The skin with that id. | ||
| 9 | |##getCurrentSkin(boolean testRights)##|##Skin##|The skin of the current request, resolved through the [[levels>>doc:documentation.xs.admin.skins.levels.WebHome]] 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. | ||
| 10 | |##getDefaultSkin()##|##Skin##|The skin configured as the instance default. | ||
| 11 | |##getDefaultParentSkin()##|##Skin##|The skin used as parent by any skin that names no parent of its own. | ||
| 12 | |||
| 13 | == Skin == | ||
| 14 | |||
| 15 | Extends ##ResourceRepository##, so it also has every member of the table below. | ||
| 16 | |||
| 17 | |=Member|=Returns|=What it does | ||
| 18 | |##getParent()##|##Skin##|The parent skin. Narrows ##ResourceRepository.getParent()##, which returns a plain repository. | ||
| 19 | |##getOutputSyntax()##|##Syntax##|The syntax the skin renders content into, inherited from the parent skin and defaulting to XHTML 1.0. | ||
| 20 | |||
| 21 | == ResourceRepository == | ||
| 22 | |||
| 23 | Somewhere a resource name can be looked up. A skin is one, and so is whatever it inherits from. | ||
| 24 | |||
| 25 | |=Member|=Returns|=What it does | ||
| 26 | |##getParent()##|##ResourceRepository##|The repository used as fallback when this one does not hold the name. | ||
| 27 | |##getId()##|##String##|The repository's identifier. | ||
| 28 | |##getResource(String resourceName)##|##Resource<?>##|The named resource, walking the parent chain; ##null## when no repository in the chain holds it. | ||
| 29 | |##getLocalResource(String resourceName)##|##Resource<?>##|The named resource in this repository alone, without the parent chain; ##null## when it does not hold it. | ||
| 30 | |||
| 31 | 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. | ||
| 32 | |||
| 33 | == Resource == | ||
| 34 | |||
| 35 | One file of a skin. ##Resource<I extends InputSource>## is typed by the kind of input source it opens. | ||
| 36 | |||
| 37 | |=Member|=Returns|=What it does | ||
| 38 | |##getRepository()##|##ResourceRepository##|The repository the resource was found in. | ||
| 39 | |##getId()##|##String##|The resource's unique identifier. | ||
| 40 | |##getPath()##|##String##|The resource's path. | ||
| 41 | |##getResourceName()##|##String##|The resource's name, usually a path relative to the repository. | ||
| 42 | |##getInputSource()##|##I##|An input source for reading the resource. Throws ##Exception##. | ||
| 43 | |##getInstant()##|##Instant##|When the resource was last modified, or ##null## when that is unknown. Default method. Throws ##Exception##. | ||
| 44 | |##getURL(boolean forceSkinAction)##|##String##|A URL for the resource; ##true## forces a dynamic skin URL rather than a static one. Throws ##Exception##. | ||
| 45 | |||
| 46 | == Getting a skin == | ||
| 47 | |||
| 48 | 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>>doc:documentation.xs.dev.skin.WebHome]]. | ||
| 49 | |||
| 50 | {{code language="java"}} | ||
| 51 | @Inject | ||
| 52 | private SkinManager skinManager; | ||
| 53 | |||
| 54 | Skin skin = this.skinManager.getSkin("xwiki:Main.MySkin"); | ||
| 55 | {{/code}} | ||
| 56 | |||
| 57 | The skin in effect for the current request comes from the same component: | ||
| 58 | |||
| 59 | {{code language="java"}} | ||
| 60 | // true checks the view right, but only on a skin that came from the configuration. | ||
| 61 | Skin currentSkin = this.skinManager.getCurrentSkin(true); | ||
| 62 | {{/code}} | ||
| 63 | |||
| 64 | == Looking a resource up == | ||
| 65 | |||
| 66 | Either lookup can come back empty: | ||
| 67 | |||
| 68 | {{code language="java"}} | ||
| 69 | // Walks the parent chain. | ||
| 70 | Resource<?> inherited = currentSkin.getResource("myscript.js"); | ||
| 71 | |||
| 72 | // This skin only. | ||
| 73 | Resource<?> own = currentSkin.getLocalResource("myscript.js"); | ||
| 74 | |||
| 75 | if (inherited != null) { | ||
| 76 | // Which skin the file came from. | ||
| 77 | ResourceRepository source = inherited.getRepository(); | ||
| 78 | } | ||
| 79 | {{/code}} |