Junco Skin

Version 48.1 by Thomas Mortagne on 2021/03/17 21:53

color_wheelSkin based on the Twitter Bootstrap framework and Bootswatch themes collection
TypeSkin (filesystem)
CategorySkin
Developed by

Ecaterina Moraru (Valica)

Rating
0 Votes
Websitehttps://github.com/evalica/bootswatch/tr...
LicenseGNU Lesser General Public License 2.1
Compatibility

XWiki 5.2 - 6.4.5, see more

Description

Deprecated: This skin is not maintained anymore. It was an experimental skin introducing the Bootstrap framework inside XWiki. Please use Flamingo Skin instead.

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.

Info:Built with Bootstrap version 3.0.0 and based on XWiki's 5.2 Colibri Skin.
Strength:Junco Skin is responsive and supports Bootstrap's Grid System.
Limitation: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

Base Junco Theme 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's variables.less, the XWiki's CSS API selectors found in legacy.css and a mapping between them.

DefaultTheme.png

Theme: Simplex

Simple Junco Theme Simplex Theme was created as an example of integration of Bootstrap's free themes provided by 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.

SimplexTheme.png

Theme: Colibri

Advanced Junco Theme Colibri Theme has been made to mimic as much as it can the 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.

Download

ColibriTheme.png

Theme: Blueberry

Advanced Junco Theme Blueberry Theme was created in order to demonstrate the styling capabilities of Junco.

Download

BlueberryTheme.png

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>
      With this doctype the validation does not pass, please see the related issue XWIKI-7552. The doctype is needed to make sure Bootstrap's components fully work.
    • 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.

Limitation: Currently the Junco Themes are build locally and provided minimized for the end-user. In the future we could integrate the themes build process inside xwiki-platform. Read Development section for build details.

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('themes/<THEME>/bootstrap.min.css', true)";
@import "$xwiki.getSkinFile('legacy.css', true)#if ("$!{request.colorTheme}" != '')?colorTheme=${request.colorTheme}#end";

Development

Junco Themes are build on Bootswatch, which in turn is using Bootstrap sources.

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)

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";

In the wild Bootstrap Themes do not work as they are on the XWiki structure. They need to be compiled using the XWiki mapping in order to be used, see Simple Junco Themes.

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;
    • Limitation: Currently the ColorThemes values are static and cannot be changed on the fly by enabling another ColorTheme. In the future this could be fixed.
  • 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

Examples: Simplex Theme, Default Theme 

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

Simple Junco Themes do not support ColorThemes values, since they were not created to be used by XWiki in the first place. They are usable because of the mapping, but you need to be careful on the color combinations.

Advanced Themes

Examples: Blueberry Theme, Colibri Theme 

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";
  • 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)

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 ZIP file and unzip it into the skins/ folder inside your expanded XWiki WAR directory.
  • 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 (Colibri Theme XAR, Blueberry Theme XAR, 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:

          administrationSettings.png 

    • 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; 

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
Tags: skin
    

Get Connected