During the course of developing your Sencha Touch app, you will inevitably get around to theming…after all, while the default styles are nice, they don’t exactly scream individuality. Fortunately, Sencha Touch makes theming ridiculously easy, and there are a lot of resources available to help with getting started with that.

But let’s talk about a specific example. Let’s imagine that you want to simply change the background color on your app’s toolbars. The first thing you’ll probably do is pop open Firebug or Developer Tools to inspect the CSS that’s being applied to your toolbar. Unless you’ve already customized it, you’ll probably seem something like this:

I’ve highlighted “x-toolbar-dark”, because by default, the “UI” configuration option for Ext.Toolbar is set to “dark,” which applies the “x-toolbar-dark” class to your toolbar (it will apply “x-toolbar-light” if you specify “light” for ui…more on this later).

Here’s what the toolbar actually looks like:

If you inspect the properties of this CSS class, you should see something like this:

  • background-color: #456F8D;
  • background-image: -webkit-gradient(linear, 50% 0%, 50% 100%, color-stop(0%, #9cbacf), color-stop(2%, #5182a5), color-stop(100%, #395c75));
  • background-image: -webkit-linear-gradient(#9cbacf,#5182a5 2%,#395c75);
  • background-image: linear-gradient(#9cbacf,#5182a5 2%,#395c75);
  • border-color: black;

Nothing too crazy here…just some background-image gradients to give the toolbar a nice textured feel. Now at this point, you might be tempted to do something crazy, something like creating a new class in an extra custom stylesheet to override these style rules. Or, you might add a custom class via the Ext.Toolbar’s “cls” config, and add the styles for this custom class in your custom stylesheet.

While both of these options will certainly work, they miss out on the power of theming within Sencha Touch. So let’s look at a better way to approach this.

Toolbar UI

If you look at the documentation for Ext.Toolbar (as well as several of the other common components), you’ll notice that it has a config option for “ui”. By default, you can specify either “dark” or “light,” which is what applies either the “x-toolbar-dark” or “x-toolbar-light” classes to our toolbar. So knowing this, the ideal approach to customizing our toolbar’s style is not by creating custom, external style rules to override or circumvent default Sencha Touch styling, but rather to create our own “ui” that we can use in the configuration of our Ext.Toolbar itself.

Fortunately, this is ridiculously easy…but first, some context :)

Default Toolbar UIs

As mentioned, the Toolbar has two default UIs: dark and light. By specifying either of these in the configuration of your Ext.Toolbar, you can easily switch between the two to get the feel that you would like (this is especially helpful if you have stacked toolbars).  Let’s take a look at how these UIs are created.

First, we’ll need to find the .scss (Sassy CSS) file that generates the toolbar CSS classes. You can find that here:

sencha-touch-1.1.0/resources/themes/stylesheets/sencha-touch/default/widgets/_toolbar.scss

A ways down the page, you’ll see something like the following:

@include sencha-toolbar-ui('dark', darken($base-color, 10%));
@include sencha-toolbar-ui('light', $base-color);

Here, our two default UIs are created. This is done by using the sencha-toolbar-ui “mixin,” which is really just a mechanism to allow you reuse chunks of code to construct CSS classes. The great part about mixins, though, is that you can utilize arguments, so it makes creating custom iterations of the same family of classes super easy.

Now let’s take a look at the mixin itself:

@mixin sencha-toolbar-ui($ui-label, $color, $gradient: $toolbar-gradient) {
   $toolbar-border-color: darken($color, 50%);
   $toolbar-button-color: darken($color, 10%);
   .x-toolbar-#{$ui-label} {
      @include background-gradient($color, $gradient);
      border-color: $toolbar-border-color;
      .x-toolbar-title {
         @include color-by-background($color);
         @include bevel-by-background($color);
      }
      .x-button, .x-field-select .x-input-text, .x-field-select:before {
         @include toolbar-button($toolbar-button-color, $gradient);
      }
   }
}

As you can see, the mixing takes up to 3 arguments:

  • The name of the UI
  • The base color for the UI
  • The type of gradient to use for the UI (defaults to the variable $toolbar-gradient)

Then, based on the arguments passed, this mixin will create a CSS class in the form of “x-toolbar-[UI Name]”, and will additionally create classes that riff on the color and gradient that are specified for the overall UI. This will give the toolbar a unified “feel” if it contains buttons.

Creating our Own Toolbar UI

While this UI/SASS/mixin stuff can be a little overwhelming at first, hopefully you see now how it starts to come together. Since we know that the “dark” and “light” UIs for the toolbar are crafted simply by using the sencha-toolbar-ui mixin, it’s pretty clear how we need to proceed to create our own UI. So let’s do that now.

In sencha-touch-1.1.0/resources/sass/, I’ve created a custom .scss file (I’ve called it “custom”…pretty original, I know). In this .scss file, I’m going to create a custom toolbar UI. Since “blue” is way to predictable for a developer, I want to try something sheik, but safe. How about a nice “charcoal” UI?

Here’s how we do it:

$base-color: #588aad; // go big blue!
$include_default_icons: false;
@import 'sencha-touch/default/all';
@include sencha-panel;
@include sencha-buttons;
@include sencha-sheet;
@include sencha-picker;
@include sencha-tabs;
@include sencha-toolbar;
@include sencha-toolbar-forms;
@include sencha-indexbar;
@include sencha-list;
@include sencha-layout;
@include sencha-form;
@include sencha-msgbox;
@include sencha-loading-spinner;

@include pictos-iconmask("bookmarks");
@include pictos-iconmask("compose");
@include pictos-iconmask("trash");
@include pictos-iconmask("search");
@include pictos-iconmask("my-logo");
@include pictos-iconmask("bookmark2");

@include sencha-toolbar-ui('charcoal', #333333,'glossy');

Ok, 98% of the code above has nothing to do with our custom UI. I just wanted to include it, in case you’ve never seen an .scss file. The most important line for our UI is the last one.

What? One line? Is that really all there is to creating a custom toolbar UI? The simple answer is YES.

Easy, right? And this is precisely why I advocate for creating the custom UI, over and against modification of a custom stylesheet. With the custom UI, we don’t need to do anything else besides this one line of code here. Any maintenance moving forward (like tweaking for a more nuanced “charcoal” color) will only require a quick modification here. No extra style sheet to worry about, which is always a good thing.

Using the Custom UI

Alright, so we’ve created our custom UI. How do we use it?

Well, first, we’re going to need to recompile our app’s stylesheet.

In Terminal, navigate to sencha-touch-1.1.0/resources/sass (where we created our custom .scss file), and then type “compass compile“. If everything goes through ok, you should now see a “custom.css” (or whatever you named it) in the sencha-touch-1.1.0/resources/css folder.

If you have no idea what’s going on here, take a look at this article on getting setup for theming in Sencha Touch.

Take this path to your custom CSS file and add it to your main application file so that it’s using it as the main CSS.

Good? Ok, now we can apply our custom UI to a toolbar!

var myToolbar = new Ext.Toolbar({
   dock: "top",
   title: "Fancy Charcoal Toolbar in the House!",
   ui: "charcoal"
});

That’s it! Save your work, refresh your browser, and you should now see your app with a sheik, sophisticated charcoal toolbar :)

The final result?

And the underlying HTML:

(Notice it’s exactly the same as before, but now with the new UI class of “charcoal”)

Wrapping Up

I can’t understate the point enough that what’s been outlined above has only scratched the surface of what’s possible. But hopefully it demonstrates some of the really cool things that can be accomplished with very little effort, and in such a way that is a natural extension of Sencha Touch’s powerful theming capabilities.