Click or drag to resize

Themes

The Wisej theme system is quite sophisticated and goes beyond simple CSS or SASS. Themes in Wisej are single JSON files that define colors, images, fonts, and appearances that control all visual aspects of a Wisej control.

Themes are also tightly integrated with the designer and the server side of the controls. The designer in Visual Studio is capable of rendering themes very accurately and the server code behind Wisej controls reads and manages all the metrics and values associated with the appearances and states of all the controls.

Images, Colors and Fonts can be indirected in their respective sections and let a theme designer change their values in a single place to update all the references throughout the theme. While Appearances can inherit from other appearances.

The ThemeBuilder that is included with Wisej is a powerful tool that allows web developers and designers to manage and preview themes as well as apply their changes to a running application to see how the theme works live.

Another unique feature of the theme system is the support for The theme mixins. Wisej supports unlimited, dynamically loaded, mixins. This feature allows developers to create small partial theme files that are targeted to a component, or a part of the application, and can be distributed bundled as embedded resources. Wisej discovers the mixins (runtime and design time) and applies them to the base theme.

Tip Tip

This document describes the structure of Wisej's theme files. However, you most likely will not need to edit the theme manually. All aspects of a theme are managed by the Theme Builder tool provided with Wisej.

Images

The images section contains the list of images used throughout the theme. Each image entry has a name and value that defines the image. It is not necessary to indirect images, all the values that are supported in the images section can be used directly as image sources. However, it's very convenient to specify an image only once and reuse by name.

The image value can be:

  • Full URL

    The full URL of an image can refer to any image anywhere. You can use a http or https or any other protocol that returns an image that can be displayed by a browser. The URL can also specify custom parameters.

    The default wallpaper URL.
    "images":
    {
      "wallpaper": "https://s3.amazonaws.com/Wisej/images/Wisej-desktop.jpg"
    },
  • Partial URL

    A partial URL is the same as the Full URL, except that it doesn't specify the protocol and the server. The URL is either relative to the application using the theme, if baseUrl is not specified, or to the baseUrl setting in the theme.

    The checkbox icon.
    "images":
    {
      "checkbox-checked": "data:image/svg+xml;base64,PD94bWwgdmV...",
    },
  • Base64 Embedded Image

    The image value can be the image itself, in any format, using the base64 notation. The advantage of using this format is that all the images are included in the single theme file. It's a lot easier to export and to manage. All the themes that we provide use embedded SVG images.

    The default wallpaper URL with the baseUrl
    "images":
    {
      "baseUrl": "https://s3.amazonaws.com/Wisej/images/"
      "wallpaper": "Wisej-desktop.jpg"
    },

The application can use any theme image simply by name. Wisej's client framework resolves the image dynamically at runtime. It uses heavy caching and it's extremely fast.

Colors

The colors section contains the list of colors used throughout the theme. Each color entry has a name and value that defines the color. It is not necessary to indirect colors, all the values that are supported in the colors section can be used directly in any color property. However, it's very convenient to specify colors in one place and reuse them by name.

The color value can be:

  • #RRGGBB

  • rgb(red, green, blue)

  • rgba(red, green, blue, alpha)

  • HTML Color Names (list)

The application can use any theme color simply by name. Wisej's client framework resolves the color dynamically at runtime. It uses heavy caching and it's extremely fast.

System Colors

Wisej translates .NET's SystemColors to theme colors, if the theme defines colors with the same name with the first character lowercased: i.e. SystemColors.ActiveBorder is translated on the client to the value of "activeBorder" in the colors section.

Fonts

The colors section contains the list of fonts used throughout the theme. Each font entry has a name and the font definition properties that defines the font. It is not necessary to indirect fonts, all the values that are supported in the fonts section can be used directly in any font property. However, it's very convenient, especially for fonts, to specify the definition in one place and reuse them by name.

Fonts are a bit more complex than colors and images. The basic definition of a font contains the name, the size in pixels, and the family array:

Basic font definition
"fonts":
{
  "default":
  {
    "size": 13,
    "family": ["helvetica", "arial", "verdana", "sans-serif"]
  },
},

However, the theme engine also supports the full font definition:

Full font definition
"fonts":
{
  "menu": 
  {
      "size": 13,
      "family": ["Roboto", "Slabo", "Arial"],
      "lineHeight": 23.0,
      "bold": true,
      "italic": true,
      "decoration": "underline",
      "textShadow": "2px 2px #ff0000",
      "sources": [
      {
          "family": "Roboto",
          "source": ["https://fonts.gstatic.com/s/roboto/v15/ek4gzZ-GeXAPcSbHtCeQI_esZW2xOQ-xsNqO47m55DA.woff2"]
      }, 
      {
          "family": "Slabo",
          "source": ["https://fonts.gstatic.com/s/slabo27px/v3/LfR9_S_HMdQ73mwIHBRxoSEAvth_LlrfE80CYdSH47w.woff2"]
      }]
  }
},

The font definition above creates a new theme font named menu, with size 13px, line height 23px, bold, italic and underlined, with a shadow and using Roboto, Slabo and Arial, in that order.

The textShadow property corresponds to the C33 text-shadow style.

The sources property is an array of font sources. Each source is defined as a map with the family name and the corresponding URLs. Wisej supports the following formats: "eot", "woff", "ttf", "svg", "woff2".

Appearances

Appearances are keys that group a set of styles and properties to apply to a widget depending on its state. A widget defines the name of the appearance key that it wants to use. i.e. the Wisej.web.Button widget uses the "button" appearance key. A widget can change which key it uses at any time. There is no limit to the number of appearances in a theme.

An appearance can inherit from another appearance to simplify settings. For example, in the built-in themes, the "button-ok" appearance inherits from the "button" appearance and changes the default background color and the hovered background color.

Appearance inheritance
"appearances":
{
  "button-ok":
  {
    "inherit": "button"
    "states":
    {
      ...
    }
  }
}

All styles and properties are grouped in states. The states represent common states, such as "pressed", "clicked", "focused", "hovered", ... and more widget specific states such as "vertical", "active", ... A widget can have multiple states at the same time. The theme engine applies the styles and properties under a matching state in the order they are defined in the theme file.

Note Note

Wisej supports composite states to fine tune the order in which styles and properties are applied. i.e. the state "barBottom-vertical" is applied to widgets with the "barBottom" and the "vertical" states in the order it is found in the theme definition.

States

An appearance contains any number of states (the name of the supported state depends on the widget using the appearance), and a child components (not to confuse with child controls). Each state can define a predefined set of styles and a set of properties that depend on the widget using the appearance.

For a description of the most common states, see Theme States. However, it's impossible to list all the supported states since they depend on each widget's internal implementation.

Styles

The styles are all predefined in Wisej and roughly correspond to CSS styles. In fact, Wisej creates a dynamic CSS class and applies it to the widgets that use the appearance key and match the state that contains the style. It's very similar to using CSS classes with HTML elements.

For a complete definition of the allowed styles, see Theme Styles. Styles are managed by so-called Decorator classed in the JavaScript framework and are predefined in Wisej.

Properties

Properties are different from styles and are specific to the widget that is using the owning appearance key. The value of properties is passed to the widget which decides how to render the property value in the DOM. Unlike styles, limited by CSS specs, properties are defined by the widget. For example, the "rowHeight" property of the "table" appearance is used by the Wisej.web.DataGrid widget to set the default height of its rows.

For a description of the most common properties and their format, see Theme Properties. However, it's impossible to list all the supported properties since they depend on the widgets.

Components

Components are identical to appearances and contain more states and components. The only difference is that component appearance keys are used by child widgets and depend on the internal name that the owner widget used when creating the child widget.

For example, in the built-in themes, the "splitbutton" appearance key contains two components names "button" and "arrow" and since the two child components are actually both buttons, the child appearances both inherit from "button".

In case you need to refer to a child appearance (that is a component in an appearance key), you can address it using a simple path notation: "splitbutton/arrow".

Theme Builder

Wisej provides probably the best theme builder on the market. It's a self contained (single executable) tool for Windows that can design and preview the theme files independently. The tool is also capable of loading a running Wisej application and apply theme changes in preview mode.

The tool provides the capability to export/import all the images at once, to edit the source definition in a foldable text editor, and has built-in support for SVG images, including the generation of thumbnails and preview images.

Mixins

Theme mixins are partial theme files, with the extension .mixin.theme, that define or override only a part of the base theme. The base theme is whatever theme is loaded by the application. There is no limit to the number of mixins that can be applied to a base theme.

This technique allows developers to theme extensions and custom components independently, without having to modify the full themes. It also allows a developer to override aspects of the base theme without having to clone a theme and therefore lose the option to use other themes.

Theme mixin that changes all buttons to red.
{
  "name": "MyMixin",
  "appearances":
  {
    "button":
    {
      "inherit": "button",
      "states":
      {
        "default":
        {
          "styles":
          {
            "backgroundColor": "red"
          }
        }
      }
    }
  }
}
Note Note

Wisej discovers the mixins dynamically from the embedded resource of all referenced assemblies and the /Themes folder in the running application. The mixins are applied in alphabetical order. An assembly that wants to expose a Wisej resource must have the assembly attribute [assembly:WisejResource].

Settings

Wisej themes have a new section named "settings" that contains system settings and theme settings.

  • System Settings are special values that are recognized by the Wisej widget library. Currently the only supported setting is: "overlapped-scrollbars": true | false.

    When overlapped-scrollbars is set to true, Wisej will render the scrollbars above the content to scroll, very similar to Windows UWP scrollbars.

    See the new Graphite-3 theme for an example of cool auto expanding and overlapped scrollbars.

  • Value Settings are custom values that are substituted in the theme's appearances. It allows a theme to set common values in one place to simplify updating the theme or creating variations of the theme. Example:

    JavaScript
    {
      "settings": {
        "border-size": 1,
        "caption-height": 12
      },
      "appearances": {
        "window": {
          "states": {
            "default": {
              "styles": {
                "width": "$border-size"
              }
            }
          }
        }
      }
    }
Stylesheet

Starting with Wisej 2, themes can contain an embedded set of css rules. This new feature allows theme designers to fine tune a theme by adding specific css rules in the theme itself.

The css rules can target custom classes or theme classes created by Wisej. When the application loads a new theme it discards the previous theme-embedded stylesheet and loads the new one.

The Theme Builder supports the css editor and shows a new Stylesheet section. Embedded stylesheet rules can also be added using a json editor in Visual Studio:

JavaScript
{
  "settings": {
    ...
  },
  "appearances": {
    ...
  },
  "stylesheet": {
    "rules": [
      ".qx-button: {",
      " background-color: green",
      "}"
    ]
  }
}

Stylesheet.rules is defined as an array of strings representing text lines in the css string to keep the source of the theme readable and manageable using a text editor.

See Also