Using the Theme Designer

Themes

Themes in WaveMaker allow you to select an overall look and feel for a project. Changing the project theme causes the entire project to be restyled. For example, changing the theme changes the following UI properties:

• Font styling for content, captions and headings
• Rounding and borders for buttons and tabs
• Changes to styling when a button or tab is selected, hovered over or clicked.
• Background colors for panels, layers and tabs

Themes, themeStyles and panels

Most web sites use multiple sub-themes to style different types of content differently. For example, the styling for a web site header is almost always quite different from the main content styling.

In WaveMaker, each theme has a number of "sub-themes" that describe how to style several types of content. The same widgets will display differently depending on which themeStyle is applied to them.

The particular styling that will be applied to the widgets contained in a panel depends on the themeStyleType parameter for that panel:

• Panels - document: these are the default settings for the theme and are usually applied to the whole project or to the header, footer and margins.
• Panels - main content: these theme settings are meant to be applied to the main content for the application
• Panels - emphasized content: these theme settings are meant to be applied to content which is meant to contrast with the main content, for example a column to the right of the main content
• Panels - header content: these theme settings are meant to be applied to the header content for the application.

For example, the following screenshot shows the left menu template with two panels - one of which shows main content and the other shows emphasized content.

How themes work

WaveMaker comes with a number of pre-defined themes and a theme editor for creating new themes. WaveMaker also comes with a number of templates. When a new project is created, the developer selects the template and theme for that project.

• theme: the theme contains css settings for several types of content within an application, including header content, main content and emphasized content.
• themeStyleType parameter: the developer can specify what styling to apply to a set of widgets by setting the themeStyleType parameter on a panel which contains those widgets
• template: the templates consist of a set of widgets laid out to take advantage of different theme styles, for example with a header, menu, main content and emphasized content.

Set the project theme

The best way to set the theme for your project is to select your project from the model, and change the theme property in the properties panel.

When the developer creates a new project, the New Project Editor appears and allows the developer to select which theme they want to apply to the project, as well as which template to use to style the overall application, as shown in the following screenshot:

Change the project theme

Select the project variable from the Model menu as shown.

Now set the theme parameter using the dropdown list.

Change the panel theme style

Select a panel. Set the themeStyleType parameter to the themestyle desired: default, main content, emphasized content or header content. All widgets within the panel will be restyled. Default uses the styling specified in "Panels - document"; Main content uses the styling specified in "Panels - Main Content", etc.

Import a Theme

A theme is a directory that contains a number of css files and images. To share a theme, the theme directory is converted into a zip file. The name of the zip file is the same as the name of the theme.

To import a theme, unzip the file into the custom themes directory for your WaveMaker studio. This directory is located in a directory called "themes" that is under the same directory containing your WaveMaker projects.

If your WaveMaker projects directory is c:UsersownerDocumentswavemakerprojects, then your themes will be stored in the directory c:UsersownerDocumentswavemakercommonthemes.

You can find out the name of your projects directory by running WaveMaker studio and selecting File->Preferences. The "WaveMaker Folder" property holds the location of your WaveMaker projects.

To import a theme:

1. Download a WaveMaker theme zip file from the forums (dev.wavemaker.com) or some other source
2. Unzip the theme into your custom themes directory.
3. Restart WaveMaker studio. The new theme will be available in your ThemeDesigner and can be applied to any project.

Export a Theme

A theme is a directory that contains a number of css files and images. To share a theme, the theme directory is converted into a zip file. The name of the zip file is the same as the name of the theme.

After creating a new theme in the Theme Designer, follow these steps to share the theme:

1. Go to the themes directory
2. Select the sub-directory containing the theme to share, such as mygreentheme
3. Create a zip file from this directory, such as mygreentheme.zip
4. Email the zip file to share the theme

Edit a theme

To edit a theme, press the Source button in the WaveMaker studio and select the "Themes" tab. This will bring up the theme designer.

The themes that ship with WaveMaker cannot be edited directly. To copy the default theme, wm_default, press the green plus icon on the upper left side of the theme designer. To copy a particular theme, select that theme from the "Select Theme" drop-down and then press the copy icon.

Note that styling can be set on individual widgets by clicking the style properties for that widget.

Theme Designer Overview

Within the source code editors in studio is now a theme designer tab. Use this to change the basic theme colors, borders, rounding, background images, hover effects, etc...

The theme designer does not allow you to edit any of the built in themes, but DOES allow you to copy them and to edit your copy. When you copy a theme, it is copied into your common folder and is available for editing and for use within ALL of your projects.

Note that each background image provides a pulldown menu of images to pick from. To add new items to this list, simply copy images into your common folder: common/themes/custom_mytheme/images/

Creating a quick theme

The quick theme feature is a very fast way to set up a new theme by entering just a few parameters.

First, pick an existing theme that is similar in font size and rounding to what you want. Next, enter the following parameters:

• Border color: this is the border color for buttons, tabs, fancy panel,
• Border radius: this sets the border radius for buttons, tabs and panels. Zero = no rounding, good settings are 4-6
• Border width: this is the width of the border in pixels
• Page background: this is the page background color in hex, e.g. #ffffff = white, #000000 = black
• Page color: this it the font color for the page
• Page textsize: sets the font size
• Page family: sets the font family
• Clickable background: this sets the background color for clickable widgets such as button, tab, grid. WaveMaker will automatically set the onHover and active styles based on this background color.
• Clickable image: select an image that makes the button look three dimensional.
• Clickable color: sets the font color for clickable widgets
• Clickable textsize: sets the font size for clickable widgets

Clickable and editable widgets

The theme designer simplifies the task of styling many widgets by applying similar styling to similar types of widgets. In particular, the theme designer styles clickable widgets

• Button: all styling is set in the clickable settings for each themeStyle, for example "Panels - Main Content"
• Tab layer: all styling is set in the clickable settings for each themeStyle, for example "Panels - Main Content"
• Grid: the grid header color, odd row background and even row background are set in "Full theme settings: Grids and Tables." The onHover and active styling is set in the themeStyle, for example "Panels - Main Content"

Typically, the place to start in setting these parameters is in "Panels - Main Content." These settings can then be copied into "Panels - Emphasis" and "Panels - Header" using the copy command as shown in the following screenshot.

Creating 3d effect for clickable widgets

The clickable image property in the theme designer creates a gradient effect that makes a button or tab look more three dimentional. Use brightEdge for dark backgrounds and greyEdge images for light backgrounds. The options include

• Images for dark background colors: brightEdge, brightSliverEdge, brightThickEdge, brightThinEdge
• Images for light background colors: greyEdge, greySliverEdge, greyThickEdge, greyThinEdge

Creating a full theme

Before you start, pick the theme colors. Use a color picker such as http://colorschemedesigner.com/ to find complementary colors for the theme. At a minimum, choose the following colors (not all of them have to be different!):

• Default background color: usually white or grey
• Header color: background color, font color
• Menubar color: background color, hover color, selected color
• Main content color: background color (usually white), clickable color (e.g., color for buttons and tabs), hover color (e.g., color when cursor is over a button), selected color
• Emphasized content: background color (usually a contrast to main content), font color

Setting full theme categories

Creating a full theme can involve setting many parameters. The trick lies in understanding which parameters set particular widget behaviors:

• Full theme settings: these settings control the styling for the overall application. Most text content will be in a panel with a themeStyle set to Main Content, Emphasized or Header, so you don't have to worry too much about the clickables and editors styling for this category. The most important settings here are to set the background color for the layoutbox
• Full theme clickable settings: these settings control the styling for the menu widget and also for the calendar widget.
• Full theme dialog settings: sets the theme for all dialog boxes and popups. Choose background color and font, titlebar styling, button styling. For titlebar icons, select between dialogIconsGray and dialogIconsRedYellowOrange
• Full theme grid settings: set the grid header color as well as the color for even and odd rows if desired. The grid's onHover and active settings will be controlled by the themeStyle, for example Main-Content
• Widget settings: these settings allow fine-grained control of widget behavior. The most important settings control the height of tabs, accordion layers and fancy panel heading.
• Panels - Main Content: these are the most important settings, as most content will be in a panel with themeStyle set to "main content". Set the colors carefully for clickables (this includes buttons, tabs, grid rows). The color for a fancy panel header is the same as Clickables-active. Also specify the styling for editors when the user hovers over or clicks them.
• Panels - Emphasized: set the background color and font color of this sub-theme to contrast with the main content sub-theme.
• Panels - Header: set the backgound color, hover color and active colors so that the menu will display

Themes How To: Creating a Green Theme

Suppose you decide to create a new theme with a green color scheme. First, create a basic color palette by starting with a single main color and going to a site like http://colorschemedesigner.com/ to find complementary colors. For this example, there are three key colors - a main color and two accent colors:

1. Main color: #99c433. Used in header background-color. For lighter and darker shades of this color, just enter the main color into the color picker and then select the lighter or darker button in the color picker to change the shade.
2. First accent color: #a32a76
3. Second accent2 color: #9c9b46. Used in emphasis Clickables (Active).

The default theme, wm_default, is a good theme to use as the basis for a new theme. All of the grid and editor settings for this theme use different shades of grey and so usually will not need to be changed.

Now make the following changes under Full Theme Settings

1. Panels Document - Clickables (Default): change to first accent color #a32a76
2. Panels Document - Clickables (Hover): change to first accent color #a32a76 use the color picker to set a lighter shade.
3. Panels Document - Clickables (Active): change to second accent color #9c9b46

1. Panels Main Content- Clickables (Active): change to the main color #a32a76 and use the color picker to set a darker shade.
2. Panels Emphasized Content - Background: change the first accent color #a32a76 and use the color picker to set a lighter shade
3. Panels Emphasized Content - Clickables (Active): change to second accent color #9c9b46
4. Panels Header Background: change color to main color #99c433

Advanced theme topics

You cannot edit themes that prefix with "wm_" as these are built into studio. Similarly, when you create a new theme, you can not prefix your theme name with "wm_".

Importing a Theme

There is no import theme function in studio yet; to import a theme created by another user, go to your WaveMaker projects folder, find the common folder, and in there you should see a "themes" folder. Any folder in the themes folder is treated as a theme. Just copy a theme folder in there, and the next time you load studio, the new theme should show up in the list of theme options.

Adding images to a theme

Note that each background image provides a pulldown menu of images to pick from. To add new items to this list, simply copy images into your common folder located in your WaveMaker projects directory at common/themes/custom_mytheme/images/

Note that the image should be put in a directory according to whether and how it should be repeated: top level directory: no repeat

• repeat folder: repeat and tile
• repeatx: repeat horizontally
• repeatx_bottom:
• repeaty:
• repeaty_right:

Quick theme tips

The Quick Theme editor lets you setup a minimal number of settings needed to have a working theme. Some touching up may be needed after working on a quick theme; its a good idea to review "Panels - Dialogs" after using a quick theme, but typically after going through the few editors in the quick theme, you're most of the way finished in creating your theme.

Two things to be aware of when using the Quick Theme editor:

1. If you've edited settings in the more advanced parts of the theme designer, these settings may be overwritten by the Quick Theme editor.
2. Themes created using the Quick Theme editor do not support special panel types that can be accessed from the wm.Panel properties panel "themeStyleType". This property typically lets you specify that a panel is your Header, Main Content or Emphasized Content panel, but with a Quick Theme, these features will not do anything.

Full Theme

There are four main categories of settings for a Full Theme. These are described below.

Borders

There are three types of widgets which have their own border settings:

1. Editors: while you cannot edit the border width, and border colors are set elsewhere, this is where you set the radius -- or roundness -- of all editors in your project
2. Panels: Set the border width, color and radius/roundness of all major panel types (RoundedPanel, TabLayers, AccordionLayers and other panels that are used for more than just laying out widgets)
3. Clickables: Set the border width, color and radius/roundness of all clickable widgets such as buttons, accordion headers and tablayer buttons.

Background Images

There are some very nice things that can be done with background images. A set of useful images are included with each theme and can be selected from a pulldown menu: "brightSliverEdge0", "brightEdge0" and "brightThickEdge0". There's also a matching set of images named "grey" instead of "bright". Using these as background images in your theme creates nice 3D dynamic looking widgets.

You can add your own background images that will show up in the background-image pulldown menu by placing images in the appropriate subfolder:

• WaveMaker/common/themes/mytheme/images: a basic image, no repeating on any axis, no special positioning
• WaveMaker/common/themes/mytheme/images/repeatx: repeats image across the top of the widget
• WaveMaker/common/themes/mytheme/images/repeatx_bottom: repeats image across the bottom of the widget
• WaveMaker/common/themes/mytheme/images/repeaty: repeats image across the right of the widget
• WaveMaker/common/themes/mytheme/images/repeaty_left: repeats image across the left of the widget
• WaveMaker/common/themes/mytheme/images/repeat: repeats image across the entire widget

Panel Types

There are a number of categories in the Theme Designer named "Panel - ....". These let you customize how different types of panels will behave. The currently supported panel types are as follows:

• Document: This represents a wm.Layout, and lets you specify the default styling for your document.
• Main Content: A user can put a Main Content panel into a page which helps to set the main content off from the margins, header and footer of the application.
• Emphasized Content: A user can put an Emphasized Content Panel into a page, typically within the Main Content area, to emphasize a set of content. This might be used in an aside, or for instructions and tips.
• Header Panel: A user can put a Header Panel into a page; this can be used to put a header at the top of the page, a toolbar in the middle of a page, a table of contents at the side of a page. This panel is used to emphasize controls, unlike "Emphasized Content" which is more about emphasizing information.

Widget Settings

Sometimes, there's no choice but to add widget-specific settings. If the font size gets too big, we need to make the wm.TabLayer buttons taller, and the RoundedPanel header taller. Some widgets just need to be fine tuned to work with a given theme. Going to widget settings, you can find all of the widget-specific customizations that are NOT theme-able.

Also available here is border and borderColor for every widget. If you really want your button to have a blue 3px border when all other clickable elements have a red 1px border, this is where you go to set that. This is also where you go to set default properties for your widgets (note that border and borderColor are properties of your widget, as is the TabLayers headerHeight).

Be warned that changes you make to Widget Settings may be overwritten by changes you make under "Full Theme Settings" (especially changes you make to Borders in "Full Theme Settings").

Custom.css

Anyone who wants control over their theme that isn't available can create a file in their theme folder: "WaveMaker/common/themes/mytheme/custom.css". Why is this better than putting custom css in your application's css? Because once its in custom.css, its accessible to all projects using that theme; when you send someone else your theme, the custom.css file is included. If you want your clickable elements to be blue, but your wm.Buttons should all be green, this is how you'll do it.

/* Note the trick of adding an html selector that makes these settings
   more specific than the css specified through the theme designer */
/* Changes the font for the fancy panel header label for MainContent */
html .my_custom_theme .MainContent .wmfancypanel .wmFancyPanel-labelWidget {
	font-family: Verdana; 
	font-size: 12pt; 
	color: white; 
	font-weight: bold; 
}