Implementing Themes with Wisej.NET

Styling your WiseJ.net app with Theme Builder

by Jon Hilton

Implementing features is one thing, making them look good is quite another!

It's important for any framework to have a good story around styling and theming your app, and WiseJ.NET has a dedicated Theme Builder to make this easier.

Let's see how it works.

The first step is to download and run the Theme Builder application.

The download includes a single zip file, in which you'll find a file called Wisej.ThemeBuilder.exe.

Launch that and you'll find yourself looking at the Theme Builder UI.

Wisej.NET Theme Builder UI with various panels open, listing aspects of the theme which you can tweak. On the right is a preview of how the current theme will look when applied to your components/pages.

At the top of this screen you can see the currently selected theme (Boostrap-4 in this case).

In the top left pane you'll see a detailed list of all the things you can tweak for the current theme.

There you'll find Colors, Images, Fonts, and Appearances.

In the Appearances section you'll find every Wisej.NET component.

Buttons, ComboBoxes, ScrollBars are all available to be styled from this menu.

When you click on an appearance you'll see it's properties in the bottom left pane.

Here I've selected Button and we can see various properties which can be tweaked, including the button's text color, opacity, text alignment.

The preview pane on the right shows, in real time, how your tweaks affect the visible controls.

All the controls in the preview pane can be clicked, which will select the relevant appearance in the pane on the left.

Not all controls are shown in the preview window, but you can get to them if you select the Controls tab in the menu above the preview pane.

Controls tab showing more controls which can be styled

Simple tweaks to the existing styles

Let's start with a really simple tweak to the existing button style.

First we can locate the Button appearance in the Components pane.

Once there we can select one of its states.

We'll explore states in a moment, but for now we'll make our changes to the Default state.

With Button > Default selected we see its specific styles in the Properties pane.

It's then possible to tweak those individual styles/properties.

Here I've changed the backgroundColor style to make buttons yellow by default.

We'll see how to test and use this updated theme in a moment, but first let's take a quick look at component states.

Customising components with multiple states

Let's explore states with the help of another component, the MessageBox.

With the Controls tab open in the preview pane you'll see the first few controls are various different types of Message Box.

Click on one of those and it will be automatically selected in the Components pane where we can then see all its properties/styles.

In this context states refer to the different types of Message Box we can show (error, information, stop etc.)

We can see the different background colors specified for each state.

Let's tweak the background color for the information state.

As soon as we do that, we can see from the preview that our Message Box now has a bit of a color clash going on!

The text and icon colors could do with a tweak.

The easiest way to identify which appearance needs changing is to click on the element in the preview pane.

In this case, clicking on the title (the "Message Box" text) highlights the MessageBox > Title appearance.

Now we can clearly see that the property we want to tweak for the information state is properties > textColor.

Let's go ahead and change that.

We can do the same with the Image (exclamation), and the CaptionBar (the bar underneath the title).

By the time we're done we've changed these appearances (all for the information state):

• MessageBox > Title

• MessageBox > Image

• MessageBox > CaptionBar

Now we're close to a style we could run with (albeit we won't be winning any style awards for this one!)

But what about that message text?

If we click the text in the preview pane we'll see MessageBox > Message highlighted in the left-hand pane.

But, unlike the other appearances, this one has no alternative state for Information, just the Default state.

The good news is we can add our own additional state(s).

First by clicking the + icon in the top left corner of the Components pane.

In the resulting window we can select the State tab, then type in the name, which in this case needs to be Information.

Then click OK to add the new State.

Now we can add a new property to this state.

First, select properties in the Properties pane, then click the + icon.

We see the Add Style/Property dialog.

We can select the property name textColor and give it a value (in this case, the color we want).

Click OK and the preview will update to show how the message box looks with our new properties applied.

I have a new theme and I'm not afraid to use it!

So far so good, but how to actually use this new style we've defined?

The first step is to save it.

Click the Save As icon (the save icon with a pencil over it) to save your theme somewhere on your machine as a .theme file.

Use your custom theme during development

In Visual Studio, in a new or existing Wisej.NET project you'll see a Themes folder.

Right click that, then select Add > Existing Item.

Locate your newly saved theme, and click OK to add it to the Themes folder.

Once done, it should look something like this:

With this we can use this theme when viewing components in the designer.

For example, here's a simple page with a button.

Notice how, with the correct theme selected in the bottom left, the buttons have picked up the new style (yellow background).

This works for development, but if you launch and view your app in the browser it isn't (yet) using the new theme.

For that we need to tweak the application config.

Use your custom theme at runtime

There are a few ways to select which theme your running Wisej.NET app uses.

You can configure it in your application's Default.json.

{
    "url": "Default.html",
    "startup": "WisejTutorials.Program.Main, WisejTutorials",
    "theme": "WisejTheme" // add this
}

Another way is via web.config.

<configuration>
	<appSettings>
		...		
		<add key="Wisej.DefaultTheme" value="WiseJTheme"/>
	</appSettings>
	...
</configuration>

Either of these approaches will set the theme for the entire app.

Finally, you can also switch theme programmatically, while your app is running:

private void btnChangeTheme_Click(object sender, EventArgs e)
{
    Application.LoadTheme("WisejTheme");
}

Now we know how to create and use themes, there's one thing left to explore; how to define brand new styles from scratch.

But before we do that, there's something we need to understand about appearances.

## Appearances may inherit from a base class

When working with an appearance, you might notice that it inherits a base class.

For example, taking another look at the Message Box. We can see, if we look at the Components pane that it inherits from window.

This means it will pick up all of window's styles/properties by default.

Of course, you can then override those by defining more specific properties.

Where this comes in particularly handy is if you want to create your own items, based on an existing component.

Defining your own, brand new styles

Let's say you want to create an entirely new kind of button.

So not just a different state for the existing button, but a new type of button you can use when you want to have a completely different appearance.

You can add a new appearance to the existing appearances, by clicking the + icon in the Components pane.

In this case, we want our appearance to look like a button.

So we can set it's inherit property to button.

Now it will look the same as the existing button appearance, except for the styles/properties we override.

In this case I've overridden the backgroundColor style to give it a bold purple background and the textColor property to give it white text.

Heading back to our WiseJ.NET application we can use this new style, by setting the appearanceKey for any of our buttons.

By setting appearanceKey to myButton we ensure this button picks up our new MyButton appearance.

In Summary

So there you have it.

You can configure just about any aspect of your Wisej.NET application.

Theme Builder provides a convenient way to see, and tweak the style of any of your Wisej.NET controls.

You can then add the theme to your project and see the results in the designer as you build your components.

Finally, you can specify the theme for your app via config, and/or enable the users to switch theme programmatically as they interact with your application.