Sencha Inc. | HTML5 Apps

Blog

An Introduction to Theming Sencha Touch

December 17, 2010 | David Kaneda

An Introduction to Theming Sencha TouchSencha Touch has introduced a revolutionary new theming system, built on SASS and Compass, that allows you to create versions of our base theme custom tailored to your application and brand. Because Sencha Touch is built on web standards and targets WebKit, developers are free to use the wide variety of CSS3 properties already available to the platform, like border-radius, background gradients, and even more advanced properties like the CSS3 flexible box model. To create a custom variant of the bundled theme that uses SASS and Compass is very straight-forward as well.

A Brief Introduction to SASS & Compass

SASS is a pre-processor which adds new syntax to CSS allowing for things like variables, mixins, nesting, and math/color functions. For example, in SASS we can write:

$blue: #3bbfce;
$margin: 16px;
 
.content-navigation {
    border-color: $blue;
    color: darken($blue, 9%);
}
 
.border {
    padding: $margin / 2;
    margin: $margin / 2;
    border-color: $blue;
}
 

And it will compile to:

.content-navigation {
    border-color: #3bbfce;
    color: #2b9eab;
}
 
.border {
    padding: 8px;
    margin: 8px;
    border-color: #3bbfce;
}
 

To see the wide variety of other features available in SASS, please see http://sass-lang.com/. Compass extends SASS by adding a variety of CSS3 mixins and providing the extension system that Sencha Touch leverages. With Compass, one can include rules like:

$boxheight: 10em;
 
.mybox {
    @include border-radius($boxheight/4);
}
 

Which compiles into:

.mybox {
    -webkit-border-radius: 2.5em;
    -moz-border-radius: 2.5em;
    -o-border-radius: 2.5em;
    -ms-border-radius: 2.5em;
    -khtml-border-radius: 2.5em;
    border-radius: 2.5em;
}
 

You can learn more about the pre-included mixins with Compass and the other tools which it provides here: http://compass-style.org/docs/. I’ve only really touched the surface of what’s possible with these technologies, so I can focus on our use of them in Sencha Touch, but I highly encourage you to briefly look at their respective sites to get a better sense of their capabilities. Now, though, let’s look at setting up a SASS/Compass environment where we can create custom Sencha Touch themes.

Setting Up Custom Stylesheets

First, we’ll need to make sure we have SASS and Compass installed. Because these technologies are based on Ruby, Windows users will need to install Ruby and RubyGems (these come pre-bundled on Macs). Because SASS is bundled with Compass, you can install both with the following Terminal command:

Update 4/18/11: As of Sencha Touch 1.1, we are using the beta version of Compass, and have updated the line below accordingly.

gem install compass --pre

Note: You may need to install using “sudo gem install…” for administrative privileges.

Once everything is installed, we’ll need to create a new directory in our project to house our new SASS stylesheets. I typically use resources/scss (SCSS is the syntax language for SASS, and stands for “Sassy CSS”). Within the directory, we’ll create two files, config.rb and application.scss.

config.rb The config.rb is written in Ruby, and is very straight-forward to set up (so don’t worry if you don’t know Ruby). The file is typically a set-it-and-forget-it:

# Delineate the directory for our SASS/SCSS files (this directory)
sass_path = File.dirname(__FILE__)
 
# Delineate the CSS directory (under resources/css in this demo)
css_path = File.join(sass_path, "..", "css")
 
# Delinate the images directory
images_dir = File.join(sass_path, "..", "img")
 
# Load the sencha-touch framework
load File.join(sass_path, '..', '..', '..', '..', 'resources', 'themes')
 
# Specify the output style/environment
output_style = :compressed
environment = :production
 

If you are debugging your custom stylesheet, you may also want to set your output_style to “:expanded,” which will compile your CSS line-by-line and actually show, with comments, where the rules are being generated in your SCSS. “:compressed,” as shown above, compacts all of your CSS to one line and removes any comments/extraneous spaces — which is ideal for minimizing footprint in production environments.

application.scss The application.scss file is written in SCSS and has the following structure (we’ll go over what some of these terms mean in a moment):

// 1. Variable overrides, example:
// $base-color: #af2584;
 
// 2. Include Sencha Touch styles
@import 'sencha-touch/default/all';
@include sencha-panel;
@include sencha-buttons;
@include sencha-sheet;
@include sencha-picker;
@include sencha-toolbar-forms;
@include sencha-tabs;
@include sencha-toolbar;
@include sencha-carousel;
@include sencha-indexbar;
@include sencha-list;
@include sencha-layout;
@include sencha-form;
@include sencha-loading-spinner;
 
// 3. Define custom styles (can use SASS/Compass), example:
// .mybox {
//     @include border-radius(4px);
// }
 

As you can see, the main gist of this is that we are importing styles from Sencha Touch, component by component. The area above (1) is where we can actually override variables used by the default Sencha Touch theme to change the output when the actually stylesheets are created/included. There are currently about 50 variables available to override, though we’ll just focus on a few key ones in this article.

SASS variables in Sencha Touch allow you to quickly customize themes to match your brand.

Sencha Touch Variables

$base-color Perhaps the easiest way to create a sweeping change in your app’s design, you can change the $base-color to drastically alter the appearance of all components. The screenshots above demonstrate how the UI changes by simply altering the $base-color.

Other global color variables include $alert-color (red by default), $confirm-color (green by default), $active-color (a saturated version of $base-color, blue by default).

$base_gradient Similar to $base-color, $base-gradient allows you to drastically change the appearance of your app by modifying the gradient style of all elements like buttons, toolbars, and tabbars. The four included values for gradients are ‘matte’, ‘bevel’, ‘glossy’, ‘recessed’, and ‘flat’.

Custom Styles & Sencha Touch Mixins

In our application.scss shown above, you will notice there is a specific area (3) for custom styles, after we’ve imported the library stylesheets. This is your area to write your application’s custom CSS, and make use of any mixins provided by Sencha Touch. Some common mixins provided by Sencha Touch allow you to embed extra icons in your application and create custom “ui” styles to apply to buttons, toolbars, or tabbars.

@include pictos-iconmask($name) This allows you to embed a custom icon mask for use in buttons or tabs. There are over 300 icons that you can include in your application, thanks to Drew Wilson’s fine Pictos set. All of the icons are base64 encoded into your CSS to cut down on server requests, which is useful in the mobile context. The icons can be found in the Sencha Touch distribution under resources/themes/images/default/pictos/. To include a new icon, simply pass the name of the icon you want, minus the .png extension:

@include pictos-iconmask(‘wifi’);
 

You can then use it in your application like so:

var btn = new Ext.Button({
    iconMask: true,
    iconCls: 'wifi'
});
 

@include sencha-button-ui($ui-label, $color, $gradient) By default, Sencha Touch comes with a variety of button colors and forms, but sometimes you may want another color option for alternative actions. This mixin creates a button UI with the color/gradient specified in the corresponding variables. In addition, this mixin also generates ‘{your-ui-name}-round’ and ‘{your-ui-name}-small’. The text color and shading will be automatically calculated from the background color. Likewise, there are mixins for sencha-toolbar-ui, and sencha-tabbar-ui.

@include sencha-button-ui('orange', #ff8000, 'glossy');

And then use in your JavaScript:

Sencha Touch buttons
var glossy_orange_btn = new Ext.Button({
    ui: 'orange',
    text: 'Orange'
});
 
var round_glossy_orange_btn = new Ext.Button({
    ui: 'orange-round',
    text: 'Orange Round'
});

Compiling Our Stylesheet & Adding to Our Application

To compile our stylesheet, we simply run the command “compass compile” in the Terminal from within the scss directory. This command will automatically look for the config.rb, and take care of compiling the CSS into the proper directory.

When you add the stylesheet to your HTML file, don’t forget to remove the included sencha-touch.css — as you’re newly compiled stylesheet includes all of the framework styles as well.

Some Sample Stylesheets

Demo #1

demo1
$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-toolbar-forms;
@include sencha-tabs;
@include sencha-toolbar;
@include sencha-carousel;
@include sencha-indexbar;
@include sencha-list;
@include sencha-layout;
@include sencha-form;
@include sencha-loading-spinner;
 

Demo #2

demo2
$body-bg-color: #fbf5e6;
$base-color: #efe1d0;
$active-color: #aa3030;
 
@import 'sencha-touch/default/all';
@include sencha-panel;
@include sencha-buttons;
@include sencha-sheet; 
@include sencha-picker;
@include sencha-toolbar-forms;
@include sencha-tabs;
@include sencha-toolbar;
@include sencha-carousel;
@include sencha-indexbar;
@include sencha-list;
@include sencha-layout;
@include sencha-form;
@include sencha-sheet;
 
body {
    font-family: Georgia;
    color: #5a3d23;
}
 
.x-toolbar .x-toolbar-title {
    color: #5a3d23;
}
 

Demo #3

demo3
$body-bg-color: #000;
 
$base-color: #333;
$base-gradient: 'matte';
$active-color: #B2DF1E;
 
$tabs-dark: $base-color;
$tabs-light: #555;
 
$tabs-bottom-radius: .4em;
$tabs-bottom-gradient: 'bevel';
$tabs-bar-gradient: 'matte';
$tabs-bottom-active-gradient: 'recessed';
 
$toolbar-gradient: 'glossy';
 
@import 'sencha-touch/default/all';
@include sencha-panel;
@include sencha-buttons;
@include sencha-sheet; 
@include sencha-picker;
@include sencha-toolbar-forms;
@include sencha-tabs;
@include sencha-toolbar;
@include sencha-carousel;
@include sencha-indexbar;
@include sencha-list;
@include sencha-layout;
@include sencha-form;
@include sencha-sheet;
 
.x-toolbar .x-toolbar-title {
    color: saturate(lighten($active-color, 10%), 20%);
    text-shadow: rgba(#fff, .8) 0 1px 20px;
}
 
.x-tab-active img {
    background: white none !important;
}
 
.x-tabbar.x-docked-bottom .x-tab {
    &.x-tab-active {
        -webkit-box-shadow: inset rgba(#000, .8) 0 0 5px !important;
    }
}
 

Next Steps & Extended Resources

We’ve really just touched on the power of theming in Sencha Touch, but already, with just a few small changes, we have radically changed the style of the base Sencha Touch theme. For other great examples of custom stylesheets, look at the Kiva and GeoCongress demos bundled with Sencha Touch. Also be sure to look out for my second article on the subject, “Optimizing Sencha Touch Themes,” where I show how we can take a full-fledged application and reduce the included CSS to under 50kb (with base64 encoded icons!).

Please feel free to send me any theme questions on Twitter or post them to the forum and I’ll be happy to respond. Happy styling!

There are 53 responses. Add yours.

Awesome Bob

4 years ago

Boo at Ruby. Loved the rest.

Nirav Mehta

4 years ago

I’ve been keeping away from SASS as I thought it was too complicated - at least their site made me go away. This introduction rekindled that interest. It’s amazing what can be done with this, and I am going to try it out soon.

Did not like the Ruby dependency though.. wink

Shea Frederick

4 years ago

Good stuff - glad to see the themeing process being demystified. Ill have to post a follow up to my own blog post on Theming Sencha Touch after experimenting with the techniques outlined here. Thanks for the post Dave.

Jonathan

4 years ago

Can’t wait ‘till we get this theming with Ext JS 4.0! grin

AwesomeBob

4 years ago

I think I might just work on a PECL extension for SASS so the PHP community can really make use of these new technological innovations.

Andreas

4 years ago

I don’t like the ruby dependancy but the results are awesome.

Anthony Matejcich

4 years ago

yeah the ruby focus is an issue for me but i guess its a willingness to learn! Awsome move though.

Hunter

4 years ago

This is a great tutorial / idea.  I love the simplicity and it means the future is very bright.

It does not however currently reflect the Sencha download packages though.  It would be great to have that be “plug-and-play” with a working sass setup.  Running a sass—watch on the current /resources/sencha-touch.scss (what I am assuming is your “application.scss”) results in an error, even when the config.rb is updated to your example.

Please let me know when this is fixed, as I would love to be able to try this out.

Aaron

4 years ago

Am I the only one having a fail moment here? I can’t get this configured properly. When I compile, it throws me this:


WARNING: Neither sencha-touch/default/all.sass nor .scss found. Using sencha-touch/default/all.css instead.

This behavior is deprecated and will be removed in a future version.
If you really need sencha-touch/default/all.css, import it explicitly.

Roy

4 years ago

Hey everyone—what’s wrong with a Ruby dependency? What ever happened to using the best tool for the job?

Ruby’s text processing and DSL abilities make it an excellent tool for this job.

Thomas

4 years ago

I’m using ubuntu version to run sass, what command should we use in Terminal
i have used compass compile but it just generated another folder .

So i tried compass -compile but it returned some error

Thomas

4 years ago

I have done something like this and it works in ubuntu smile

sudo gem uninstall chriseppstein-compass
sudo gem install compass


and
compass compile sass

elmasse

4 years ago

David, tremendous post! Nice work! Just to head up. Picto include is wrong defined:

@include pictos-iconmask(‘wifi’);

You should put the name of the image without the quotes!

@include pictos-iconmask(wifi);

Guy

4 years ago

Wow
This needs way more cover than a short blog…

Shea Frederick (VinylFox)

4 years ago

@Aaron - you need to adjust the path in config.rb. The line that starts ‘load File.join….’, for instance, I use:

load File.join(sass_path, ‘..’, ‘themes’)

dmassiani

4 years ago

I have try this customization and finally that’s rocks but i have a problem, the message box have bad weight, i can’t touch “ok” button ...
what i doesn’t ?
(sorry for my bad english)

dmassiani

4 years ago

mmm, yeah i have found the problem, i have just included this line :
@include sencha-msgbox;

and my question: where exactly i can read all possible include and variable ?

i love sencha touch and sass.

JavaDeveloper

4 years ago

Oh no! Ruby! I don’t want to install Ruby and learn it for just this. Sencha guys, can you please come up with something that is Ruby independant?

Rob Jones

4 years ago

Great article, very useful for the project I am working on!

Quick question:
You show a few theme properties, but Is there a more comprehensive list of the properties used for theming? I am sure there are a lot, but I bet there’s a subset that would suffice for most themes….

Rob Jones

4 years ago

Can you provide a link to the project files? I am having a hard time creating the layout with the toolbar at the top and the bottomtabs at the bottom (I am more of a designer than a Ext coder)...

chris scott

3 years ago

@JavaDeveloper why not try out jRuby?

Jeremy Voros

3 years ago

Not a javascript or Ruby developer here, but this design framework has been a snap to learn. With this set up I can easily and powerfully change the feel of my app.  $me-color: #impressed;

Thank you.

David Kaneda Sencha Employee

3 years ago

@Jeremy: First off, your SASS-joke has made my day. Second, I’m somewhat in the same boat — this has been my first (very limited) glimpse of Ruby, but for it’s use here, it’s been crazy easy to get up and running.

@Rob: This is definitely on the way.

Chris

3 years ago

For Ruby noobs out there, using Windows, you might want to have a look at Pik: 
https://github.com/vertiginous/pik

For those on Mac / Linux, use RVM (Ruby Version Manager).
http://rvm.beginrescueend.com/

Josh Nursing

3 years ago

Ruby is exactly the scripting tool for the job here, and for those who are saying they don’t want to learn Ruby, well, you don’t have to as mentioned in the text. It’s just a configuration file for setting up your own environment.

Claudio Palladini

3 years ago

Veeeeeeeeeeeeeeeeeeeeeeeeery very very nice….

Imanol

3 years ago

Do somebody mind to put in github or somewhere the source for this demos, i’m trying to do the theming, and understand de sass and compass, but i have problems with the config.rb I think.

here is my error message:
Errno::ENOENT on line 116 of /Library/Ruby/Gems/1.8/gems/compass-0.10.6/lib/compass/compiler.rb: No such file or directory - /Users/tototo/Sites/sencha/pt/resources/sass/scss
Run with—trace to see the full backtrace

shubakk

3 years ago

This introduction seems broken, at least for me (on Ubuntu)
compass compile get me nothing but a compile folder containing some sort of initialization file (ie.css, ...)
compass—watch give me an error (sencha-touch/resources/sass/config.rb: no such file to load—sencha-touch/resources/sass/../themes) as if it doesn’t see the compass_init.rb in the themes directory.

And if i change the following line in the config file :

load File.join(dir, ‘..’, ‘themes’,‘compass_init.rb’)

i get another error :

LoadError on line 31 of /usr/lib/ruby/1.8/rubygems/custom_require.rb: no such file to load—fssm/ext

My gems are up to date : compass (0.10.6), haml (3.0.25)

i don’t understand what’s going on and what to do. does somebody have any idea how to fix this?

Lee Probert

3 years ago

I have Ruby installed and have installed the Compass gem.
When I compile my scss file I get the following error :

undefined method `inline_image_string’ for #<Sass::Script::Functions::EvaluationContext:0x101781110

Am wondering if I need to update Ruby or if the Sencha touch 1.1.0 files are not quite right.

Lee Probert

3 years ago

The theme_images.rb file has a line which is ...

images_path = File.join(File.dirname(__FILE__), “..”, “images”, theme.value)

The images folder has a subfolder called ‘default’ ... could this be the problem?

Lee Probert

3 years ago

More information here : http://www.sencha.com/forum/showthread.php?128059-SASS-Errors-in-Version-1.1

Think I’l revert to 1.0.1 and see if I can get it to work.

Ron

3 years ago

I’m having the same problem as Lee Probert.

Lee Probert

3 years ago

Ron. There’s another thread that answers this question here : http://www.sencha.com/forum/showthread.php?128059-SASS-Errors-in-Version-1.1&p=586976#post586976

$ gem install chunky_png -v 1.1.0
$ gem install compass—pre

Kennwhy

3 years ago

Hi
i’m newbie and i would like to Know if this works on windows??? and the installation process
thanks

Roger Wyatt

3 years ago

@Lee Probert / @Ron
I had the same problem and found some documentation that Sencha is using a different version of Chunky_png gem
Here’s what I did:
gem install chunky_png -v 0.12.0
gem install compass—pre

Then I could compile the CSS and everything is great.

@Kennwhy: Yes, this works on windows. You need to have Ruby installed, but once it’s installed, it works like a champ.

NImish

3 years ago

I am facing the same problem as shubakk
Can someone help me out ?

Dave

3 years ago

Why add Ruby and compass to the mix? To reach a larger audience of end users, it seems to me that it would be best to get away from these things.

Chris Scott

3 years ago

@Dave I think the Ext theme has grown too complex to manage with traditional css.  You could always out-source the design of a custom theme to a 3rd-party who could provide you with the css output generated from a custom-designed compass theme.

Nimish

3 years ago

I got the issue sorted out .. On Ubuntu 10.10 the version of Compass and SASS are lower end either you have to wait for the next release to have them or do it manually. Since I was short on time I tried it out on my Mac Mini . It installed both the requirements with the latest version I had to follow this too http://www.sencha.com/forum/showthread.php?128059-SASS-Errors-in-Version-1.1 to get it working but after that it was working fine smile !
I will also try to figure out on Linux by manually installing the SASS and Compass’s latest versions. Will update once I am done

Alex Graham

3 years ago

Am struggling to create the application.css file.  Have never used Ruby before but have installed it using the one click installer. I believe I do not have to install compass as its already installed with the Ruby install? Have multiple statements when compiling the scss file such as WARNING The linear-gradient mixin is deprecated. The resulting css file is full of non CSS code… Can someone advise where I may be going wrong?  Thanks

Handy Wang

3 years ago

Hi David Kaneda,

Thanks for your great article about Compass+SASS for generating CSS?
However, I must say that there is a wrong code snapshot “@include pictos-iconmask(‘xxxxx’);” with command “compass compile” for compiling?

After I trying, the corrent code should be “@include pictos-iconmask(xxxxx);”?In my application code is “@include pictos-iconmask(settings6);”

So, if you agree with me, pls correct it.

Thanks a lot!

Handy Wang

3 years ago

Hi David Kaneda?

In my development environment of Mac OS 10.6.7, I must install chunky_png-1.1.0 with command “sudo gem install chunky_png -v 1.1.0” before install compass with command “sudo gem install compass—pre”.

So, I just want some body else can get the answer of same problem from here.

thedirector227

3 years ago

Anybody actually look at the Theme CSS for this project (in the Sencha/resources/css folder)?  It’s a giant mess and in no way ‘easy’ to modify and customize…or read for that matter.  Whomever decided that SASS & Compass was a good way to produce “easily customizable” CSS was not thinking about the CSS Savvy designers out there.  Wish you could see the code I’m looking at right b/c this is awful.  ...looks like a massive run-on sentence with 800 character urls for the icons. WTF!?

Why do I need two completely different tools to create a third?  Knowing CSS by itself is way more useful than compiling SASS with Compass. This is ridiculous. 

Sheesh…

p.s. wish i could copy & paste and example url, but it would really mess up this blog. wow

Handy Wang

3 years ago

@thedirector227

I totally agreee with you “Why do I need two completely different tools to create a third?”. I think I needn’t . So , I thought the author of SASS+Compass is ruby fan!

Why did us must complicate the simple issues!

thedirector227

3 years ago

Thanks @HandyWang.  I wonder if there is documentation to show exactly what elements we need to change in order to theme or how about a “Theme Sencha Touch WITHOUT SASS” tutorial?  That would be nice.. 

Can anyone help with this?

Side Note (venting):
I actually designed an built a mock application in 2 hours with html5, css & jquery and it took my programmers (like 8 of them) 3 weeks to finally add the buttons to the sencha software…and they said it still might look funny on an iPad.  ...Mine works great on every platform but only having an issue keeping the lower toolbar attached to the bottom of the screen when turned sideways (on smartphones).  Part of being the boss I guess…  2 hours vs. 3 weeks…c’mon man!

Handy Wang

3 years ago

@thedirector227
  Actually, I can accept the Compass+SASS mode for theming my app, because I was a web app developer for several years ago, but for other C/S developers and some part of B/S developers. So, I think if some body want be a SenchTouch expert, he/she must take so much time to learn SenchaTouch API and Compass+SASS?So I told my colleague SenchaTouch isn’t suitable for us such as agile development team for the learning cost?
  Recently, the SenchTouch make me crazy for that It’s so hard to add some button into List item, and I think there is also some bug for handling tap event for button which is in list item and list item. Because I cant prevent firing the ListItem’s tap event when I tab button which is in list item.
  So, I give up for SenchaTouch and start with JQuery mobile.

Farish

3 years ago

Hi,

I was trying to run the config.rb script but was getting errors. then i used require ‘sass’ and require ‘compass’ in the beginning of the file and that has made the errors disappear. But how do i get a css file as the output? I run ruby config.rb from windows command prompt. it runs for a while and then returns without any message and there is no file produced… Do I need to specify the input and output filenames as additional arguments? I am completely new to ruby, sass and compass! any help would be highly appreciated.

Thanks,
Farish

Farish

3 years ago

In this line:

load File.join(sass_path, ‘..’, ‘..’, ‘..’, ‘..’, ‘resources’, ‘themes’)

I get an error: in ‘load’: no such file to load—./../themes (LoadError) from config.rb

stephanbit

3 years ago

Hi there,

i install ruby (1.9.2p290), sass, compass on win7 and it seems to work. but i facing two problems (i think it depends on the installed versions.) my gem list: chunky_png (1.1.0), compass (0.11.beta.7), haml (3.1.2), sass (3.1.7). When i compile, the outputted css has wired/wrong base64 styles and several warnings: the linear-gradient mixin is deprecated. how can i fix the problems!

amidude

3 years ago

Seriously? How lame is this? I am a front-end developer and will never see the benefit to compiling anything to get straightforward CSS. It is an unnecessary and redundant effort. Why not simply support CSS3 and all us to link to our stylesheets accordingly? I can’t even get a simple answer ANYWHERE on how to invoke a background gradient. Even the Compass tool gives cludgy answers.

Lawrence Paje

3 years ago

Thanks to this post, really help to customize the UI I wanted. I am working on windows and perfectly got the theming using ruby. smile

Ben Judson

3 years ago

For those of you looking to reduce the size of the CSS file, include this in your SCSS file:

$include-default-icons: false;

Since 18 pictos are included by default, and all are encoded into the generated CSS file, this adds a lot of extra weight. Just add the icons you need manually as described in the article—I was able to cut the size of the CSS file almost in half just by adding this line, and then manually including the 6 icons I actually wanted.

Comments are Gravatar enabled. Your email address will not be shown.

Commenting is not available in this channel entry.