Skip to content

Creating a theme

Jump to bottom
Mark Reeves edited this page Mar 12, 2020 · 20 revisions

This page is out of date and needs to be completely rewritten for versions of WComponents post 1.5.11.

Introduction

A WComponents theme should extend the default wcomponents-theme. A theme may also extend another theme which itself extends wcomponents-theme. It is possible to create a complete theme from scratch (which does not extend wcomponents-theme) but that is not recommended.

The WComponents themes represent the client layer. The theme for a web application will consist of JavaScript, Sass, XML, HTML and images required to represent the application's user interface in a browser. The intention of the implementation mechanism is to allow customization of wcomponents-theme. A typical reason to do this is to change the default banner, the colors, icons, images etc. Other reasons may be to make the scripts smaller by excluding functionality you do not need or to add support for browsers not catered for by WComponents out of the box.

Customizations are achieved by:

  • excluding resources from wcomponents-theme
  • adding additional resources not present in wcomponents-theme
  • overriding resources in wcomponents-theme

An implementation is created simply by mirroring the directory structure of the common theme source code, a picture tells a thousand words, see below. NOTE: you may choose to mirror all of the directories but you only need to create those you will use.

myimplementation <-- THE NAME OF THE IMPLEMENTATION
|-- POM.xml
|-- sources.xml <-- IF you need to have Maven create a sources zip.
|-- inherit.txt <-- ONLY if your implementation inherits from an implementation other than 'default'.
'-- src
  |-- main
  |   |-- images
  |   |-- js
  |   |-- resource
  |   '-- sass
  |       |-- _theme.scss <-- used to import theme partials in to the WComponents Sass
  |       |-- _theme-vars.scss <-- to override WComponents Sass vars and add any new ones
  |       |-- _theme-phone.scss <-- optional responsive design for phone sized screens
  |       `-- theme <-- directory for theme partials
  |
  '-- test
    '-- intern
      '-- resources

Source code in wcomponents-theme will be built into each implementation. One could, for example, create an implementation out of nothing but empty directories and you will end up with a theme that is exactly the same as the default build with no customisation at all.

Source code in the myimplementation directory will be integrated with the common code for your implementation. In the case of Sass/CSS where source order may be important the implementation CSS is appended to the default CSS so any rule with a selector of equal precedence in an implementation will override default.

A sample set of them commands to get started is shown below.

mkdir my-theme
cd my-theme
git init
touch README.md
touch POM.xml
mkdir -p src/main/sass/theme
touch src/main/sass/_theme-vars.scss

The POM

WComponents themes currently build using Maven. Therefore they need a POM. Note though that the POM refers to the wcomponent-theme-parent as the current project's parent and the WComponents version used to create your theme must be added twice: once in the parent section as the parent version and once as a property which is then used during the rest fo the build cycle. This is unfortunate but, as usual, we can blame maven.

The following is a sample POM for the theme created using the commands above.

<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>com.github.bordertech.wcomponents</groupId>
    <artifactId>wcomponents-theme-parent</artifactId>
    <!--
      Manually change this to the desired version of WComponents AND
      change it in wc.project.version below.
    -->
    <version>1.5.2</version>
  </parent>

  <properties>
    <!--
      Manually keep this in sync with the WComponents version we
      inherit from above.
    -->
    <wc.project.version>1.5.2</wc.project.version>
    <theme.dir>${basedir}${file.separator}..</theme.dir>
    <theme.impl.dir>${theme.dir}</theme.impl.dir>
    <theme.core.dir>${theme.unpack.dir}${file.separator}${theme.default.name}</theme.core.dir>
    <theme.impl.name>${project.artifactId}</theme.impl.name>
    <theme.skip.antrun>false</theme.skip.antrun>
    <theme.skip.unpack>false</theme.skip.unpack>
  </properties>

  <version>1.0.0-SNAPSHOT</version>
  <groupId>wcomponent</groupId>
  <!--
    The artifactId must (currently) be the same as the project
    directory name due to a flaw in the build mechanism.
  -->
  <artifactId>my-theme</artifactId>
  <packaging>pom</packaging>
</project>

File naming

Your implementation will probably consist of a number of files which add to or replace source files in the core. A source file with the same name as a file in wcomponents-theme will replace that file, otherwise your source will be added to the wcomponents-theme source in such a way as will cause over-rides where necessary.

The files in your theme implementation must use the appropriate file extension to be included in the build. These extensions are:

  • Javascript: .js
  • Sass: .scss

Inheriting from another Implementation

It is possible to "subclass" an implementation. To do this include a text file in the implementation root directory. The file must be called inherit.txt and must contain the PATH of the implementation to inherit from.

Making your theme changes

Changing CSS

The CSS produced by WComponent's default theme is structural with very little design. This is to make it easier to change an application's look without causing structural integrity issues. The Sass does contain a large number of variables used to control theme support for some Java API options where full support could cause a large amount of unnecessary Sass. For example it is possible to limit support for many aspects of WFieldLayout by setting Sass vars.

The Sass is modular based on the UI components in src/main/sass/components/_*.scss and generic or common styles in src/main/sass/common/_*.scss.

The easiest first step in creating a look and feel theme is to change the colors. WComponents core theme does define a small number of colours for opaque backgrounds, disabled controls and borders. These are defined as Sass vars in src/main/sass/vars/_wcscss and may be overridden in a theme's _theme-vars.scss. Other colours and design CSS are determined in the theme being created.

The default theme includes very few images and inbuilt iconography is done using Font Awesome. Other images should be added to your implementation's src/main/images directory and added to Sass as required.

Overriding or adding to the Sass is undertaken in the common way: a file with the same name as a common file will replace that common file, a file with a different name will add. When the Sass is built the implementation specific Sass is appended to the file created from the concatenation of the wcomponents-theme Sass. This allows the use of selectors with the same specificity in an implementation to override wcomponents-theme selectors.

Changing the JavaScript

To override a script file make a new file with the same name as a common file. To add extensions make files with new file names. The code standards, conventions and requirements are complex and outlined separately from this document as it goes beyond themeing into component development.

Including and excluding components

Each UI control consists of XSLT, JavaScript and Sass. The XSLT is never sent to the client but processed in Java, the CSS generated by Sass is included by default. The JavaScript is only included if required.

To exclude Sass for whole components copy and edit the file src/main/sass/wc.scss which is the core file used to generate the WComponents CSS.

Further information

Some start pages

Clone this wiki locally