Sencha Touch Theming: Building Our Custom Stylesheet with SASS

Ok, let’s recap. So far, we’ve looked at some basic concepts related to how to approach modifying a Sencha Touch app theme, as well as walked through exactly how all the pieces fit together in the SASS magic. With all this behind us, it’s finally time to create a custom .scss file-let’s get started!

Setting Things Up

In the following example, we’ll be doing some minor riffs on the standard sencha-touch.css file. If you’re in the mood for a super-customized theme of your own, well, you’ve got a lot of work ahead of you. Instead of jumping headfirst into something like that, why not start with some small changes, and build from there?

First things first, we need to decide where we want our new .scss file to live. While we can put it in the /resources/sass/ folder where the other core ones are, for this example we’ll create a new folder at the same level…just to keep things straight. I’m going to call mine “custom” (pretty creative, eh?).

Now, in order for us to let Compass know where our .scss file lives, we need to create our own config.rb file (check out the last post for more info about this). I’ll create that file, and here’s more or less what the contents look like:

# Get the directory that this configuration file exists in
dir = File.dirname(__FILE__)
# Load the sencha-touch framework automatically.
load File.join(dir, '..', 'themes')
# Compass configurations
sass_path = dir
css_path = File.join(dir, "..", "css")
environment = :production
output_style = :compressed

If you were to look at the config.rb file in the resources/sass/ folder, you’ll notice it’s the same content. This is fine, since my “custom” sass folder is at the same level as the resources/sass folder. If it were put somewhere else, we’d have to update this file. But for the time being, this will work.

Okay, easy enough. Let’s close that file…we don’t need to do anything else with it.

Next, we need to create a new .scss file. You can call it what you like, but just remember that Compass will make a .css file with the same name that you choose for the .scss. I’m calling mine custom.scss (again, super original), and here’s the contents:

$base-color: #7A1E08;
$base-gradient: 'glossy';
@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-carousel;
@include sencha-indexbar;
@include sencha-list;
@include sencha-layout;
@include sencha-form;
@include sencha-msgbox;
@include sencha-loading-spinner;

As with the config.rb file, you’d notice that this is exactly the same as the sencha-touch.scss file. That’s because I think it’s easier to start with what’s already working, and customize from there. If you want headaches, feel free to start from scratch 🙂

Gettin’ Custom

Alright, now that we have our files setup, we can move on to customizing our new .scss file to create a super-sweet custom .css file that will help our app look a little less generic and whole lot more awesome. Here’s what I want to do in this example:

• Change the “main” color of the application (from blue-ish whatever to something a little.more.green.)
• Pull in some additional icon masks from the huge repository that ships with Sencha (betcha didn’t know there were so many…it’s awesome)
• Create a new “ui” that we can use for toolbars

Changing the Base Color

The first task-changing the “base” color-is stupid-simple. You see the first line of our .scss file? Just change the hex value to the color you want. Yep, that’s it. I’m changing mine to something greener:

$base-color: #7A1E08;

Done (see, this is easy, right?)

Icon Masks

The next task-pulling in extra icon masks-is also pretty simple, but first a little context. By default, the sencha-touch.css file has a handful of icon masks defined that can be used in toolbars and whatnot. These are great, and pretty useful for quite a lot of contexts, but there are only so many defined.

Now before I knew about the awesomeness of SASS in Sencha theming, I did what I thought was a pretty reasonable thing to do: I busted open sencha-touch.css, saw how the icon masks were defined, and replicated them for my own icons. The major problem with this approach, of course, is that:

1. I had to modify a TON of style rules, just to add in a new icon mask
2. Sencha Touch uses base64 data Urls for image masks…which means I had to convert my files to base64 urls, add them in, and then bang my head against the wall when they didn’t work because of tiny typos or whatever other ridiculousness prevented it from working.
3. Imagine the frustration when the icon mask needs to be updated…yes, bad idea.

One other thing I did not realize is that just because Sencha defaults only a handful of image masks, there are actually about a BILLION icon masks that ship with the installation. If you browse to resources/themes/default/images/pictos/, you’ll see what I mean.

So all together, the sheer number of icon masks that are provided, combined with the simplicity of SASS, means that there is probably an icon that will fit your needs…and if there isn’t, it’s only a matter of dropping it in the library folder, modifying the .scss to pull it in, and recompile. Stupid-simple.

Alright, enough of that tangent. Let’s add some icon masks!

With SASS, primarily because Sencha’s approach already has what’s called a “mixin” defined for pulling in icon masks to be included in the compiled .css. A mixin is really just a reusable bit combination of CSS, properties, etc. It can even be passed arguments, which is precisely what the pictos-iconmask mixin allows. Here’s what this mixin looks like (from _mixins.scss:

@mixin pictos-iconmask($name) {
    .x-tab img.#{$name}, .x-button img.x-icon-mask.#{$name} {
         -webkit-mask-image: theme_image($theme-name, "pictos/" + $name + ".png")
    }
}

Pretty simple: it looks like a more or less regular kind of function, accepting a single argument (“name”), which is used to ultimately establish some custom CSS classes which set an image mask equal to the value of the argument.

And here’s how we’ll use that in our .scss file to pull in the custom icon mask of “flag”:

@include pictos-iconmask("flag");

If it hasn’t sunk it, pulling in any one or multiple of the hundreds of icon masks from the Sencha pictos repository is as easy as 1.) figuring out the icons name and 2.) implementing the custom mixin using that name. SASS is pretty nifty, eh? 🙂

So before we go on to our final task, a quick word here. If you look at the .css file that’s generated, and drill specifically into the rules established for these icon masks, you’ll quickly notice that they eat up a significant number of bytes for each icon mask (because, remember, they’re using the base64 data urls for the images, which is definitely longer than simply pointing to an image path….). Therefore, in an effort to keep your .css file as small and lean as possible, it’s a good idea to NOT get the fancy idea of simply including every single icon in your .scss file, just so you’ll have them available. Rather, you should only include the ones that you are absolutely using. What’s more, it’s probably a good idea to go the extra step and override the inclusion of the handful of icons that Sencha includes by default. This can be easily done in our custom .scss like so:

$include_default_icons: false;

Clear? Excellent. Let’s wrap this up.

Defining a Custom “UI”

One of the cool parts about Sencha components is that you can specify a “ui” for them to use. Example:

var myToolbar = new Ext.Toolbar({
    dock : 'top',
    title: 'My Toolbar',
    ui: "dark"
});

This UI, in effect, is just a collection of CSS rules that define how that component should look. By default, Sencha has a few like “dark” and “light”-while these are fine and dandy, they leave much to be desired if you want to significantly customize your Sencha Touch app.

Fortunately, like the icon masks we looked at before, ui’s are controlled by mixins. There are ui mixins for all the major components, and they are pretty simple to customize. First, here’s what the toolbar ui mixin looks like (from _toolbar.scss):

@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);
     }
     ....
}

And the “defaults”:

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

Pretty basic: the “dark” and “light” uis are created, simply by passing different color values to the mixin. So based on this, it’s pretty straightforward what we need to do:

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

Really, it’s that simple? Yes, it is. Now, if I go back to my Toolbar component, I can use “charcoal” for the UI, and any toolbar that has that UI will have a super-sweet glossy charcoal-y color to it:

var myToolbar = new Ext.Toolbar({
    dock : 'top',
    title: 'My Toolbar',
    ui: "charcoal"
});

Wrapping Up

So it was something of a journey getting to our custom .scss file, but I hope it was worth it. As you can see, customizing a Sencha Touch app with SASS is not only a pretty straightforward proposition, but it is an incredibly powerful option that opens up worlds of possibilities for customizing your app. With SASS, the tediousness of massively complex CSS is minimized, and you can concentrate on implementing your vision for your app’s aesthetic. Furthermore, the Sencha Touch team has done a really nice job of implementing a really robust set of mixings, variables, and other SASS goodness to make the task of customization stupidly simple.

To put a bow on this, here’s the final state of my custom .scss file based on this post. Please leave a comment or two if you have questions. Thanks!

$base_color: #50c20b; // green
$include_default_icons: false;
// import the framework and base components
@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;
//comment out components we're not using
//@include sencha-carousel;
//@include sencha-indexbar;
@include sencha-list;
@include sencha-layout;
@include sencha-form;
@include sencha-msgbox;
// include custom icon masks
@include pictos-iconmask("favorites");
@include pictos-iconmask("search");
@include pictos-iconmask("add_black");
@include pictos-iconmask("bookmarks");
@include pictos-iconmask("trash");
@include pictos-iconmask("more");
@include pictos-iconmask("chart2");
@include pictos-iconmask("flag");
@include pictos-iconmask("refresh");
@include pictos-iconmask("home");
@include pictos-iconmask("delete");
@include pictos-iconmask("settings");
@include pictos-iconmask("user_add");
// create custom ui for toolbar
@include sencha-toolbar-ui('charcoal', #333);