Junco Skin
![]() | Skin based on the Twitter Bootstrap framework and Bootswatch themes collection |
Type | Skin (filesystem) |
Category | Skin |
Developed by | |
Rating | |
Website | https://github.com/evalica/bootswatch/tr... |
License | GNU Lesser General Public License 2.1 |
Compatibility | XWiki 5.2 - 6.4.5, see more |
Table of contents
Description
About
Junco Skin is built on the Twitter Bootstrap framework and Bootswatch themes collection. The advantage of this is that it supports all the functionality, improvements and themes the Bootstrap community creates.
Junco Skin is build on top of Colibri Skin (which in XWiki 5.2 is the base skin). Another advantages of Junco is that it doesn't provide custom velocity templates, instead it inherits the templates from Colibri. This means that Junco Skin doesn't branch the functionality (just the styling) and will benefit of every code improvement will be made on the default templates by the XWiki community.
Built with Bootstrap version 3.0.0 and based on XWiki's 5.2 Colibri Skin. | ||
Junco Skin is responsive and supports Bootstrap's Grid System. | ||
Currently Junco Skin doesn't support changing the ColorThemes on the fly. This means that every theme fully supports just one ColorTheme that needs to be provided by the developer. |
Themes
Junco Skin provides the default styling and mapping rules between Bootstrap framework and XWiki. In order to be usable and polished we recommend to use one of the provided themes or create one of your own. A theme brings custom styling for colors, typography, layout, etc.
Theme: Default
variables.less, the XWiki's CSS API selectors found in legacy.css and a mapping between them.
It should not be used in production, instead if provides the base for any other theme that will extend it by adding custom colors, typography, layout, etc. It uses the provided defaults from Bootstrap'sTheme: Simplex
Bootswatch, in particular the original Simplex. In order for the Bootswatch themes to be compatible with XWiki, they need to be build using the XWiki mapping. Also in case of coloristic incompatibilities please provide a custom ColorTheme. Any theme can be further extended by adding additional styling to it.
Simplex Theme was created as an example of integration of Bootstrap's free themes provided byTheme: Colibri
Colibri Skin. The logic behind this is to provide backward compatibility for any extension done using the Colibri style, while providing the advantages of Bootstrap framework.
Colibri Theme has been made to mimic as much as it can theTheme: Blueberry
Blueberry Theme was created in order to demonstrate the styling capabilities of Junco.
Resources
Structure: ZIP file
webapps/xwiki/skins/junco/ |_ style.css |_ legacy.css |_ ie-all.css |_ htmlheader.vm |_ themes/ |_ blueberry/ | |_ bootstrap.min.css |_ colibri/ | |_ bootstrap.min.css |_ default/ | |_ bootstrap.min.css |_ simplex/ |_ bootstrap.min.css
- style.css
- Is the main css file of any XWiki skin;
- By default, it will load legacy.css and default/bootstrap.min.css files;
- legacy.css
- Contains legacy selectors from the base Colibri Skin;
- The content of this file needs to be considered as API and should not be modified;
- It also implements ColorThemes variables;
- ie-all.css
- Hosts selectors that target Internet Explorer browsers;
- The existence of this file also prevents the fallback on the webapps/xwiki/skins/colibri/ie-all.css file;
- htmlheader.vm
- The only template overwritten by Junco;
- It uses the HTML5 doctype;
<!DOCTYPE html><html lang="$xcontext.language"></html> - It adds the viewport meta tag, for proper rendering on mobile devices;
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- themes/
- Contains themes files for the Junco skin.
Structure: XAR files
xwiki-platform-junco-theme-<THEME>.xar |_ ColorThemes/ | |_ <THEME> |_ Themes/ |_ <THEME>
- ColorThemes/ (example: Blueberry Theme)
- Each theme needs to provide its custom ColorThemes.<THEME> page in order to assure color consistency with the uicomponents that implement the ColorThemes values;
- Themes/ (example: Blueberry Theme)
- Each theme will provide a Themes.<THEME> page that represents a skin file that overwrites the style.css.
@import "$xwiki.getSkinFile('legacy.css', true)#if ("$!{request.colorTheme}" != '')?colorTheme=${request.colorTheme}#end";
Development
Dependencies
Bootstrap uses LESS stylesheet language. This means that the Bootstrap files need to be compiled in order to have usable CSS. There are a number of options to compile LESS, one of them is installing Node.js, which includes the Node Package Manager (npm). Once you have the npm you need to install Grunt.
Structure: Bootswatch Themes
For comparison, initially Bootswatch Themes consist of two files:
<Bootswatch_THEME>/ |_ bootswatch.less |_ variables.less
- bootswatch.less Optional content (example: Simplex Theme)
- Is used to define more extensive structural changes, specific just to the current theme;
- Can be empty, meaning that you are relying on the bootstrap.less defaults;
- variables.less Mandatory (example: Simplex Theme)
- Overwrites default Bootstrap values;
- Defines color values, typography, iconography, spacing, etc.;
- See more details about the customizable values.
Initially the global/build.less file looks like this:
@import "../bower_components/bootstrap/less/bootstrap.less";
@import "variables.less";
@import "../global/global.less";
@import "bootswatch.less";
@import "../bower_components/bootstrap/less/utilities.less";
Structure: Junco Themes
The Junco Skin manages to not overwrite the default XWiki velocity templates by providing a mapping between XWiki CSS classes and Bootstrap's ones. This is done by taking advantage of LESS mixins and :extend() function.
Although we could write the mapping and all the specific XWiki styling inside bootswatch.less, we separated XWiki functionality in several additional files.
global/ |_ build.less |_ global.less |_ xwiki-colortheme.less |_ xwiki-common.less |_ xwiki-layout.less |_ xwiki-mapping.less |_ xwiki-variables.less
Currently the global/build.less file looks like this:
@import "../bower_components/bootstrap/less/bootstrap.less";
@import "variables.less";
@import "../global/global.less";
@import "../global/xwiki-mapping.less";
@import "../global/xwiki-common.less";
@import "../global/xwiki-layout.less";
@import "bootswatch.less";
@import "../bower_components/bootstrap/less/utilities.less";
Mandatory files:
- global/xwiki-mapping.less Mandatory
- If there are XWiki classes that have the same functionality as other Bootstrap classes but a different naming, it needs to be mapped;
- Examples: .clearfloats -> .clearfix; .buttonwrapper .button -> .btn .btn-primary; etc.
- global/xwiki-common.less Mandatory
- Contains rules that are common to any theme;
- Examples: fixing bugs generated by the usage inside XWiki of classes that have a different meaning inside Bootstrap (.label, .row, etc.);
- global/xwiki-layout.less Mandatory Extendable
- Takes care of the default layout;
- Examples: defines the responsive structure of containers both for view and edit modes.
Advanced files (needed if you want to support ColorThemes values):
- global/xwiki-colortheme.less Optional Extendable
- Similar to colorThemeInit.vm, it provides the ColorThemes values taken from ColorThemes.DefaultColorTheme;
- It doesn't cover all the existing ColorThemes variables, just the ones that makes sense to be mapped with Bootstrap. For example, we don't need *GradientColor values since we can use LESS functions to calculate lighten() or darken() tones of the same colors;
- global/xwiki-variables.less Optional
- Depends on: global/xwiki-colortheme.less;
- If xwiki-mapping.less provides a mapping between XWiki and Bootstrap CSS classes and mixins, this file maps the ColorThemes variables to Bootstrap's variables;
- If your theme wants to support ColorThemes values it should not change this file, instead it should provide it's own xwiki-colortheme.less with custom values, as seen in Advanced Junco Themes.
Simple Themes
All Bootstrap themes in the wild are considered to be 'Simple Junco Themes'. Choose a theme from a collection (Bootswatch, Bootswatchr, etc.) or create one yourself, compile it using the XWiki mapping and it's ready to be used.
<Simple_Junco_THEME>/ |_ bootswatch.less |_ variables.less
- bootswatch.less Optional content (example: Simplex Theme)
- Is used to define more extensive structural changes, specific just to the current theme;
- Can be empty, meaning that you are relying on the bootstrap.less defaults;
- variables.less Mandatory (example: Simplex Theme)
- See the default values and the official generator;
- Third-party generators: Bootswatchr, StyleBootstrap, BootTheme, Lavish, PaintStrap, etc.
Advanced Themes
A theme is considered to be advanced if it adds another layer of complexity (usually related to XWiki classes and structures), besides the two mandatory variables.less and bootswatch.less files.
<Advanced_Junco_THEME>/ |_ bootswatch.less |_ variables.less |_ xwiki-colortheme.less |_ xwiki-layout.less
- bootswatch.less Optional content (example: Blueberry Theme)
- Is used to define more extensive structural changes, specific just to the current theme;
- Can be empty, meaning that you are relying on the bootstrap.less defaults;
- If you provide a custom layout this is the place to import it:
@import "xwiki-layout.less";
- variables.less Mandatory or Extends (example: Blueberry Theme)
- Mandatory:
- Overwrites default Bootstrap values;
- Defines color values, typography, iconography, spacing, etc. specific just to the current theme;
- Extends:
- If you want to support ColorThemes values, you need to extend the global/xwiki-variables.less:
@import "../global/xwiki-variables.less"; - If you provide custom ColorThemes values this is the place to import it:
@import "xwiki-colortheme.less";
- If you want to support ColorThemes values, you need to extend the global/xwiki-variables.less:
- Mandatory:
- xwiki-colortheme.less Optional Extends (example: Blueberry Theme)
- Custom ColorThemes values, specific just to the current theme;
- You should provide a 'ColorThemes.<THEME>' page that copies your theme's values;
- Extends: global/xwiki-colortheme.less;
- xwiki-layout.less Optional Extends (example: Blueberry Theme)
- Custom layout, specific just to the current theme;
- Extends: global/xwiki-layout.less.
Building your theme
- Make sure you have the dependencies, the right folder structure and the files are included correctly;
- In order to be able to build your theme using Grunt, you need to add your theme to the file that configures and defines the tasks: Gruntfile.js, in the swatch: task configuration; swatch: { colibri:{}, blueberry:{}, simplex:{}, <THEME>:{} }
- Type grunt swatch: <THEME> to build the CSS for a theme. Example: grunt swatch:blueberry;
- The build will create two files /<THEME>/bootstrap.css and /<THEME>/bootstrap.min.css that can be put in your webapps/xwiki/skins/junco/themes/<THEME> folder; (example: blueberry/bootstrap.min.css)
- For full compatibility, provide the Themes.<THEME> and ColorThemes.<THEME> pages.
Prerequisites & Installation Instructions
- Download the skins/ folder inside your expanded XWiki WAR directory. and unzip it into the
- In order to change the skin for your instance please check Changing the skin section in the Admin Guide.
- Var. A: Use one of the provided themes ( , , etc.)
- Download the corresponding XAR file and import it in the wiki;
- Go to Administration > Look & Feel > Presentation and set:
- 'Skin' property to 'Themes.<THEME>';
- 'Color Theme' property to 'ColorThemes.<THEME>'.
- See:
- Var. B: Customize XWiki.DefaultSkin or create a new skin
- Change the 'Base Skin' property from 'colibri' to 'junco';
- In this case themes/default/ theme will be used;
- Var. A: Use one of the provided themes ( , , etc.)
Release Notes
v1.1
- Removing any templates overwrites (htmlheader.vm);
- Adding skin.properties (since 6.4, see XWIKI-11460) and set it to Colibri Skin;
v1.0
- Initial version
Dependencies
Dependencies for this extension (evalica:junco-skin 1.1):
- org.xwiki.platform:xwiki-platform-colibri 6.4