Step 1: Install Ruby

To get SASS setup, you’ll first need to install Ruby and Ruby Gems (SASS is bundled with something called “Compass”, and Compass is a “Gem” that can be added into Ruby). You can go the painful route and install Ruby and then add Gems into it. However, if you’re stupid about these things, you can do what I did and just grab the Ruby 1.92 installer–it comes pre-built with Gems already configured.

Get the Ruby 1.92 Installer

When prompted, choose “”Add Ruby executables to you PATH”

I installed to the default directory on Windows (C:\Ruby192\)

Step 2: Setup Compass

Now that Ruby is installed, the next step is to get Compass (e.g., SASS) setup. This step actually took me the longest, simply because I’m stupid about command-line stuff. So here’s a play-by-play of what to do (this is for Windows…I assume Mac is similar), just in case you suffer from a similar level of stupidity:

• Open a new Command Shell (Start -> Run -> type “cmd”)
• Navigate to your Ruby installation directory (cd/ruby192)
• Type “gem install compass –pre” – if it works, you should see a bunch of text appear about things being installed, configured, and what not.
• BTW, we’re using “–pre” to get a beta version (0.11) of Compass. This is necessary, as the latest non-beta will break when compiling.

Step 3: Done!

You’re done. The next step is to actually start customizing some sassy stylesheets!

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);

It’s not that you couldn’t immediately jump in and produce something awesome–you definitely could, and it would be pretty simple. I suggest browsing the default theme, however, because despite how easy it is to being customizing your own .scss file with new colors, icon masks, and whatever else strikes your fancy, actually understanding (if even in a very preliminary sort of way) what’s going on will help prevent future frustrations that may dampen your sudden excitement to start theming.

With that thought in mind, let’s take a few moments to peek around the default theme to see how the magic happens.

config.rb

In your Sencha Touch installation, browse to /resources/sass/. In this folder, you’ll see a file named config.rb. This file, written in Ruby, is one of those “setup it up and leave it alone” kind of files. In a nutshell, this file brings all of theme together, letting the compiler know where particular assets are located, how it should output the content, etc. If you follow the lead of Sencha Touch’s default theme, this is a file you can leave alone…or copy and modify according to how you set things up.

One of the more important things to note about this file is the “load” directive. This tells the compiler where to find the core assets (.scss files) that contain the code which will generate the ultimate .css files. In the default config.rb file, this loads .scss files located in the /resources/themes/ folder. We’ll take a look at that in a second, but for now, just remember that the config.rb file absolutely needs to point to the right location, or else the compilation won’t work right. So if it’s working…leave the file alone!

The last thing to point out is the css_path configuration. This is important, because it specifies where the compiled .css file will be saved (in this case /resources/css/). And the way that Compass works, there will be a one-to-one correlation between the .scss files that are a part of the compilation and the .css files that are produced. So, if we were to run the compilation in the /resources/sass/ folder, we would find a .css file in the /resources/css/ folder for each .scss that was compiled: in other words, /resources/sass/sencha-touch.scss = /resources/css/sencha-touch.css.

sencha-touch.scss

I hope that last point was clear. If it wasn’t, I’ll reiterate it this way: You know the sencha-touch.css file that you are probably loading based on your following of the “Getting Started” example? All of the style rules in this .css file are the direct result of a compilation of the resources/sass/sencha-touch.scss file. While you probably thought the .css file was the result of some poor slob painstakingly putting together all that complexity, the actual production of the .css file comes as a result of sencha-touch.scss getting compiled, and SASS working its magic.

If you open up sencha-touch.scss, you’ll probably be pretty underwhelmed. It’s a very small file, but deceptively so. In reality, it is a gateway to initializing the entire beauty of SASS, a process that will eventually involve dozens of other .scss files.

So the very first line you come across is a variable: $base-color: #7A1E08.  This one line will control the overall color scheme for the Sencha Touch application. If you were to modify this to, say, some green color, recompiled, and then refreshed your application, you’d notice that the entire aesthetic of your app would change; that one simple line would have deep impacts in the theme of your application.

That’s pretty cool in itself, but let’s keep moving…A few lines more, we come across the following:

@import ‘sencha-touch/default/all’;

In SASS, you can import other .scss files. So in this example, the sencha-touch.scss file includes another called ‘all.scss’. But where is this file? Well, if you look in /resources/themes/stylesheets/sencha-touch/default/, you’ll find a file named _all.scss; despite initial appearances, this is the one that’s included on sencha-touch.scss.

HUH?

Yes, at first it’s a little confusing. Let’s break it down, and hopefully it will make more sense.

First off, how does Compass know to look there to find that file?

If you remember the config.rb file we looked at earlier, look at the “load” directive. This tells Compass where the theme is located (e.g., the “themes” folder).

Okay, but how about the “stylesheets” folder? I don’t remember that being configured anywhere!

True, we didn’t specify that in config.rb, nor anywhere else. The answer is that this is “default” configuration of Compass. There is a configuration variable called “css_dir” in Compass…unless you override, it defaults to “stylesheets.” If that’s something that might drive you crazy, feel free to add css_dir = “stylesheets” to your config.rb file; it won’t change anything, but may make getting your head around it a bit easier

Fine, that makes sense. But how about that “_all.scss” file? The import directive didn’t have an underscore?!?

This is another Compass-thingy. By default, Compass will compile ALL .scss files to .css files. However, you can create what is called a “partial“–this is just a normal .scss file with an underscore at the beginning of the file name. This tells Compass not to compile, but it’s still able to find the file and use it.

Moving On

Hopefully it’s now what this simple import statement is doing. The remainder of the sencha-touch.scss file that we’ve been looking at is the inclusion of the default set of Sencha Touch style collections. While we won’t get into these right now, you might make note that these can be commented out in order to save precious bytes on the total size of the compiled .css. In other words, if you’re not going to use something (like Carousel), don’t include it! The loading speed of your app will thank you.

_all.scss

For the last discussion of this exploration, go ahead and find that elusive _all.scss file and open it up. You’ll notice that it’s yet another gateway file, merely importing more .scss files. As you have time, follow the path of imports, making note of how the files are inherited and what each file does. As you browse these files, you’ll eventually get to terminal pages that actually have quasi-CSS-looking code. This is where the magic of SASS happens. Using a conglomeration of SASS variables, mixins, and super-sweet rule nesting, the final complexity that is the sencha-touch.css is built, bit by bit. Then all of it is wrapped up, compiled, and spit out as our awesome .css file.

Wrapping Up

Yes, I know: we didn’t actually get to any custom theme building. However, I think the walk through is important, if for nothing else than to provide some exposure to how the many .scss files that make up the final sencha-touch.css file work together. Plus, if you’ve taken the time to actually understand how all the bits fit together, you’ll find that setting up your own custom .scss file (or even an entirely custom theme) is a lot less painful and frustrating. After all, creating custom design should be fun and inspiring–you shouldn’t have to fight with environmental unknowns when trying to achieve your goals. So even though this little detour has not produced any custom styling, we’re now in a much better place to start tackling a customization…and that’s what we’ll dive into in the next post.

However, if you’re like me, you probably get to the point with your apps where you want to customize the look and feel. I mean, while the Sencha Touch default palette is nice, it’s pretty generic, so before long you’ll need to start developing a custom theme for your app.

An Abortive Start

Initially, this can be a challenge with Sencha Touch apps. The challenge stems not from the fact that anything magical is happening behind the scenes: it’s just JavaScript, CSS3, and HTML after all. Rather, it’s the way that it’s all packaged up.

If you take a look at one of the stylesheets, you’ll notice how crazy complicated they are. Let’s say you wanted to change the color of all the navigation backgrounds, for example. Well, you could use Chrome’s developer tools to inspect each and every interface, grab the selectors, and then try to overwrite them with a custom style sheet (that’s what I did my first time). But you’d find that you’re editing dozens of lines of code, just to make a simple change.

And what about custom navigation toolbar icons? Well, by default Sencha Touch’s stylesheets use the base 64 dataUrls of the images within the stylesheets. And there are only a handful available by default. So if you wanted to add your own custom icon, not only would you have to replicate the exact lines of code for navigation icons, but you’d also have to figure out the base 64 of your image, enter it PRECISELY within the stylesheet, and hope for the best. Best of luck if you ever need to tweak that image in any way.

Sounds onerous, eh? That’s because using a traditional “modify and overwrite” approach to stylesheets won’t get you very far with customizing your own theme for Sencha Touch. In fact, if you’re like me, you’ll get frustrated with it in about 20 minutes and give up.

Starting Over (The Right Way)

Fortunately, there is a much better and far less painful way to customize Sencha Touch themes. The answer lies in SASS.

SASS, short for for Syntactically Awesome Stylesheets, is basically an extension of CSS that allows for lots of cool stuff that we all wish CSS had–variables, nesting selectors, functions or “mixins”–you know, THAT cool stuff . SASS makes this happen by using custom files with an extension of “.scss.” These files are then compiled in Ruby, and produce a valid, well-formatted .css file. But because of the extensible nature of SASS, simple, intuitive structures in the .scss files can create massively complex .css files, all without the pain of trying to maintain the complexity of the .css file itself.

So for example, let’s say you wanted to change the default “base” color of your Sencha Touch app. If you tried to do this via manual editing of the sencha-touch.css style sheet, you’d quickly find that you have literally hundreds of instances of this one color littered throughout your CSS file. While you could easily do a find-and-replace, that’s obviously not a great solution, and just opens the door to you messing up and breaking something.

With SASS, you can define this one color as a variable (more about this in future articles), and then use that variable throughout the .scss file to define this color. Yes, that’s right: define the color once, reuse it to your heart’s content. And when you’re sick of that color, you can simply change the value of the variable, and that’s all you have to worry about. Like I said, it’s exactly what we all wish CSS could do

This one example is just scratching the surface of what SASS can do. I won’t belabor the point here, but be sure to check out the SASS website to see the full story of what can be accomplished.

Getting Started With SASS

Even if changing the one color is all you want to accomplish, you’ll need to get your environment set up for SASS. Because .scss files are compiled into .css files, you’ll need to get Ruby set up in your development environment in order to take advantage of the awesomeness of SASS.  Here are the steps for getting everything set up. I’m deliberately dumbing this process down, since a lot of the tutorials I found assumed more knowledge of command line stuff than I knew when I was setting SASS up. So my apologies if this is overly descriptive.

UPDATE! The following is for Sencha Touch 1.0.1. If you are trying to get setup using Sencha Touch 1.1.0, see this updated walk through instead. It will help prevent major compilation fails

Step 1: Install Ruby

To get SASS setup, you’ll first need to install Ruby and Ruby Gems (SASS is bundled with something called “Compass”, and Compass is a “Gem” that can be added into Ruby). You can go the painful route and install Ruby and then add Gems into it. However, if you’re stupid about these things, you can do what I did and just grab the Ruby 1.92 installer–it comes pre-built with Gems already configured.

• Get the Ruby 1.92 Installer
• Double-click the file to install, and choose “”Add Ruby executables to you PATH”
• I installed to the default directory on Windows (C:\Ruby192\)

Step 2: Setup Compass

Now that Ruby is installed, the next step is to get Compass (e.g., SASS) setup. This step actually took me the longest, simply because I’m stupid about command-line stuff. So here’s a play-by-play of what to do (this is for Windows…I assume Mac is similar), just in case you suffer from a similar level of stupidity:

• Open a new Command Shell (Start -> Run -> type “cmd”)
• Navigate to your Ruby installation directory (cd/ruby192)
• Type “gem install compass” – if it works, you should see a bunch of text appear about things being installed, configured, and what not.

Step 3: You’re Done!

At this point, “SASS” is ready to go. In the next article, I’ll walk through a basic setup for creating a custom theme file for your Sencha Touch app.