Theme Files

The 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 application 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.

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 application.

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.

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

  "images":
  {
    "baseUrl": "https://s3.amazonaws.com/Wisej/images/"
    "wallpaper": "Wisej-desktop.jpg"
  },

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

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

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 or points, and the family array:

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

However, the theme engine also supports the 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".

Wisej supports using pixels (px), points (pt), and the default font size (em) in the font definitions.

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.

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

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. 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.

{
  "name": "MyMixin",
  "appearances":
  {
    "button":
    {
      "inherit": "button",
      "states":
      {
        "default":
        {
          "styles":
          {
            "backgroundColor": "red"
          }
        }
      }
    }
  }
}

Wisej discovers the mixins dynamically from the embedded resources of all referenced assemblies and the /Theme 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].

A mixin can create new appearances, colors, images or fonts and it can override existing ones. When overriding an existing appearance, you can either start from scratch or inherit from the base appearance with the same name and then change only what you want to change. The JSON snippet above shows a mixin where the appearance "button" inherits from the theme appearance "button" (same name) and overrides some of its styles and properties.

ElementsWisej.NET Theme Builder