< Jewel Components list

Jewel Theme Creation

How to make a new theme for Jewel

Jewel is a component set designed with change of appearance in mind. Jewel comes with a series of pre-designed themes so you can use it right away without having to create your own theme. You can learn more about the existing themes here. The Jewel themes that come with Apache Royale define 12 colors, dark and light, flat / no-flat visuals. However, you may want a personalized look, and you can either adapt one of the existing themes or create one from scratch.

Theme basics

Themes are a combination of files that define styles in Cascading Style Sheets (CSS) and other assets like images (JPG, PNG, SVG,…). In Jewel we use SASS to define the CSS style rules since SASS is a preprocessor scripting language that is interpreted or compiled into CSS.

You can create your own theme without the need of SASS, but we strongly recommend using it for the same reason we use AS3 instead of plain JavaScript.

One of the advantages of using SASS is that we can organize style definitions by separating styles into files. In Jewel we use a .sass file per component so we can easily find all the definitions of the component’s styles.

Generating default.css

The default.css file holds all CSS definitions for a Jewel theme. This file is generated by the SASS compiler. When a library with styles in it is compiled we use SASS to generate the src/main/resuorces/default.css file as part of the build process.

SASS generation is only set up in the Maven build, not in the ANT build. Apache Royale generates all default.css files in the SDK and makes them available to users using ANT, other build tools or IDEs. In the future we expect contributors to add SASS generation for ANT.

Jewel Library

Here you’ll find the ActionScript classes that define each component and support class files that components need to work properly. You’ll find a sass folder with a .sass file that holds all structural definitions file for each component. Those definitions can be normal CSS rules or royale bead definition rules.

You’ll never find a style rule in the Jewel library that defines colors, lines, fonts, or shapes (the theme in the theme library handles these values). We find only the CSS rules needed to generate each Jewel component’s visual structure (such as display, position, z-index, and overflow), and the default ActionScript bead classes that ship with a concrete component per platform (such as BeadView, BeadModel, BeadController, and BeadLayout).

Apache Royale uses CSS throughout the framwework to link beads to the component’s strand so components define the default composition of beads via CSS.

Jewel Theme Library

This library is like a master theme where colors, fonts, icons or shapes are defined, and is the library which generates Jewel theme variants, thanks to SASS preprocessing power. Each Jewel theme in Apache Royale uses the definitions in this library and just changes a few variables to generate the variants.

Primary, Secondary and Emphasized colors

Since Jewel themes support three different colors (Primary, Secondary and Emphasized), the Jewel Theme Library folder structure is:

• Primary color: sass/components-primary for styles that use primary and default colors.
• Secondary color: sass/components-secondary for styles that use secondary colors.
• Emphasized color: sass/components-empahsized for styles that use colors for emphasis.

primary is used by most of the components in Jewel, while only a few like Button, Badge or SnackBar that need the variants use secondary and emphasized.

Theme SASS file

sass/_theme.sass is where we can modify Jewel themes. It’s a very simple configuration file with variables that SASS uses to generate a default.css file. This is essentialy how each of the Jewel themes that comes with Apache Royale is defined.

For example, by default, we can find:

//Theme variables (Flat/No Flat - Dark/Light - Primary/Secondary/Emphasized Color
$flat: false
$dark: false
$primary-color: $blue
$secondary-color: $topaz
$emphasized-color: $emerald

This _theme.sass file will create a Jewel theme variant that will look no-flat and light, with blue as the primary color, topaz as the secondary color and emerald as the emphasized color.

Jewel Theme summary

Jewel library has defintions that you don’t normally need to change, while Jewel Theme library is like a master theme for all Royale Jjewel themes and is a good starting point when you want to create a new Jewel theme or modify an existing one.

To modify a style, make a copy of the Jewel Theme Library and start adjusting the style for each Jewel component.

A Jewel component example

Let’s take the Jewel Alert component as an example and look at the different files that make up this component:

In Jewel library you can find:

• org.apache.royale.jewel.Alert: This is the main Alert component file.
• sass/components/_alert.sass: This is the main definition file that holds all structural CSS rules and the default beads for Alert. The beads defined here for the JavaScript platform are:

j|Alert
    IBeadLayout: ClassReference("org.apache.royale.jewel.beads.layouts.NullLayout")
    IBeadModel: ClassReference("org.apache.royale.jewel.beads.models.AlertModel")
    IBeadController: ClassReference("org.apache.royale.jewel.beads.controllers.AlertController")
    IBeadView:  ClassReference("org.apache.royale.jewel.beads.views.AlertView")

Regarding the CSS selectors for Alert: The main .as file (in this case Alert.as) assigns a css selector to the typeNames variable:

    typeNames = "jewel alert";

In the sass file you find the corresponding CSS selector:

    .jewel.alert

Nested in that selector is the corresponding tree of rules and selectors for that component.

So Alert is composed of four ActionScript files and one .sass file that wires the component with its beads and defines a set of CSS rules to give a concrete CSS structure, but does not define colors, gradients, shapes or icons for Alert. The theme does all of that.

In Jewel Theme library you can find:

• sass/components-primary/_alert.sass: This is the main Alert SASS definition that holds all theme CSS rules. Here you can define colors, gradients, line styles and other visual features that affect how the Alert component appears to the user. All styles are in a .jewel.alert CSS selector.

As you can see, the Alert component doesn’t define any secondary or emphasized color.