View Full Version : Mastering the Compass/SASS Setup with Sencha Touch

21 Mar 2011, 11:31 PM

I was plagued by a sea of problems setting up SASS to work with Sencha Touch. I read through posts/documentation, referenced samples, and searched to the end of the web and back without ever finding a solid understanding of the setup or the errors I was experiencing. And I'm a seasoned veteran of web design, having been designing/coding sites for well over a decade; so this is well with the realm of my expertise. That said, Ruby, Compass, and Sencha Touch are all new to me.

I wanted to post a clear and concise explanation of how to create a fool-proof setup for using SASS with Sencha Touch. My hope is that others experiencing my pains might be able to find this post and avoid the treacherous path I traveled to get here. So it's clear, though, this is not intended to rake the Sencha folks over the coals. I simply couldn't find solutions to my problems and discovered that there are countless others in the same boat. My absolute intent is to help the Sencha community.

And with that, let's get started…


In these forums, in the Sencha blog, and in various corners of the web there are lots of different references to how the .scss/.css files can/should be set up. In the end, it doesn't matter so long as your SCSS, CSS, and Sencha-Touch theme directories are properly referenced in your config.rb file. But that's where a lot of the confusion resides because the docs/posts don't marry to the Sencha Touch files you download.


The first thing you won't understand if you aren't familiar with Ruby is how the config.rb file works. Each instance of '..' is a call to a parent directory, and each subsequent named directory is a call to children directories.

So if you have a file in /parent/child/child/ and want to reference a file in /parent/ you would use '..','..'. If you wanted reference a file in /parent/other_child/ you would use '..','..','other_child'.

Once you have that under control, the config.rb file begins to make a lot of sense. The problem here, however, is that nothing I read implies you need to have a solid understanding of the Ruby file structure in order to get this set up. I didn't even find a reference of this in Compass or SASS documentation.

Now let's make it absolutely clear what each required line references and then clear up how this differs from what's downloaded with Sencha.

// Delineates location of the config.rb file which should be in the same directory as your SCSS file(s)
sass_path = File.dirname(__FILE__)

// Points to the location of the CSS file(s) you'll call from your HTML document
css_path = File.join(sass_path, '..', 'css')

// Points to the images directory used by the Sencha Touch theme
images_dir = File.join(sass_path, '..', 'themes', 'images', 'default')

// Points to the Sencha Touch theme
load File.join(sass_path, '..', 'themes')

// Denotes how the CSS files are compiled by Compass
output_style = :compressed
environment = :production

If you compare the paths in config.rb code above to my directory structure (below) you'll notice they pair up perfectly:


But this is only because I modified the paths based on how the directories are set up with the Sencha Touch download. In the docs/posts referencing this, there are two critical mismatches:

images_dir = File.join(sass_path, "..", "img")

The default directory setup in the download has the images housed in /resources/themes/images/default/. So if you're looking for /resources/img/ out of the box you'll misfire.

load File.join(sass_path, '..', '..', '..', '..', 'resources', 'themes')

The default directory setup in the download has the theme housed in /resources/themes/. But from the config file the directory "resources" never needs to be in the join path.


All the docs/samples/downloads have your app's SCSS file importing the Sencha Touch theme CSS like this:

@import 'sencha-touch/default/all';

Now if you've been using CSS for over a decade like me, you don't need any documentation about how to import one style sheet into another. However, it's when you're unsure about how Ruby or Compass come into play that muddies the waters. What's more, everything in the "resources" directory is prepared by Sencha Touch so you'd assume this line would be work out of the box.

As it turns out, Ruby/Compass don't have anything to do with this path and it's not properly written by default. Though this is somewhat confusing because the path links to all.css instead of _all.css, which is how the CSS file is labeled, and because there are references to how Ruby takes care of removing that underscore. In the end a direct CSS import path is all you need to get the them imported. Per my directory structure that I referenced above the path looks like this:

@import '../themes/stylesheets/sencha-touch/default/all';

At this point everything is properly setup and linked. So now it's time to look at the final component: how the Compass commands can be cleared up.


The very first mistake I made was trying to run SASS commands directly. Running sass --watch path/to/scss:path/to/css throws a sea of various errors. So it's important to note that Compass commands are the vital component. And there are really only two you need for the elementary operation of compiling SASS for use with Sencha Touch:

compass compile path/to/scss (batch compiles on command)
compass watch path/to/scss (compiles in real time as changes are saved)

But even if the commands are familiar to you, you may run into problems with how Compass references paths on your machine.

First, I didn't know is that the root of the Compass compile/watch paths doesn't begin with your /users/ directory. It actually begins at your user directory. (I would imagine the root can be configured, but that's a power-user configuration which wouldn't be obvious to people who don't know Ruby and/or Compass. So I'm referencing a default installation/configuration.)

Second, you can't reference an actual SCSS file. Compass watches/compiles directories of style sheets all at once. So you need to point to a directory, not a file.

So instead of running:

compass watch /users/markwyner/project/resources/sass/myapp.scss

I needed to run:

compass watch project/resources/sass/

This was absolutely critical and made all the difference in getting this working. I can't stress that enough. I SSH into web servers and databases all the time, but this default root wasn't consistent with what I typically experience. So this really threw me off and likely throws off others as well.


Here's a summary of what I've outlined:

Ruby paths single-quote and comma-separate each change in a directory. So Ruby's '..','..','themes' translates to "../../themes/" in HTML or CSS
If you use the default directory structure for the theme downloaded with Sencha Touch 1.0.1a your config.rb file should reference theme images as images_dir = File.join(sass_path, "..", "img") and CSS load File.join(sass_path, '..', '..', '..', '..', 'resources', 'themes')
Your SCSS file should directly import the theme's CSS files without the underscore in the file name: @import '../themes/stylesheets/sencha-touch/default/all';
Run Compass commands rather than SASS commands, ensure the root for your compile/watch path is correct, and compile/watch your entire SCSS directory rather than a single SCSS file

I hope this helps anyone troubled by the SASS setup with Sencha Touch. I wish I would have had this post available to me a few weeks back. It would have saved me a lot of time.


23 Mar 2011, 12:27 AM
Thank you !
Very much !

Can't look into it now, but I'm bookmarking.

23 Mar 2011, 7:39 AM
You're welcome very much.

25 Mar 2011, 2:49 AM
Thanks Alot! Finally beginning to understand this. Tho I only got this working in with 1.0.1a but still had the error with 1.1.0.

Thanks alot for the help!

25 Mar 2011, 9:46 AM
Yeah, 1.1 is definitely out of sync. I'm going to submit a bug.

17 Apr 2011, 7:21 AM
It would be great to have an easy step-by-step instruction guide on how to install and configure the SASS and Compass on a Mac or PC. I have been searching from posting to posting, in blogs and websites trying to find the download links of SASS and Compass. It doesn't make any sense to me that Sencha is being an advocate of using SASS and how easy it is to modify css themes and not provide the links and instructions to download the components required. I have been wasting tons of hours in the internet looking on how I should configure this to work and I still haven't been able to do so. An instructional video would be even better.

20 May 2011, 10:28 AM
I'm having an issue with this line, seems it can't find:

@import '../themes/stylesheets/sencha-touch/default/all';my structure:

c:\xampp\htdocs\mobile\app\www\assets\themes\stylesheets\sencha-touch\default\my config.rb located in scss folder:

# 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, "..", "assets", "css")

# Delinate the images directory
images_dir = File.join(sass_path, "..", "assets","image")

# Load the sencha-touch framework
load File.join(sass_path, '..', 'assets', 'themes')

# Specify the output style/environment
output_style = :compressed
environment = :productionapplication.scss located in scss folder:

@import '../themes/stylesheets/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-list-paging;
@include sencha-list-pullrefresh;
@include sencha-layout;
@include sencha-form;
@include sencha-msgbox;
@include sencha-loading-spinner;I dont understand where the path should be relative to? I've tried using absolute path, tried relative to 3-4 different directors and I still getting a:

error application.scss <Line 1: File to import not found or unreadable: ../themes/stylesheets/sencha-touch/default/all.
Load Paths:
C:/... (etc. etc.)
C:/... (etc. etc.)
Sass::SyntaxError on line ["1"] of C: File to import not found or unreadable: ../themes/stylesheets/sencha-touch/default/all.
Load Paths:
C:/... (etc. etc.)
C:/... (etc. etc.)
If someone could lead me in the right direction or help me out I would GREATLY appreciate it, im tearin my hair out here... lol :((

EDIT: Figured out what the issue with and will be writing up a nice tutorial for all the other frustrated developers out there! Look for the link shortly!

21 Nov 2011, 1:43 PM
What xpous said.
When I started my working life about 20 years ago, they came up with this new fangled idea called "graphical user interfaces", which replaced command line interfaces. If whoever wrote sass and compass wants to get more traction with it, perhaps some kind of install script or GUI to make it Just Work would be well worth the ROI.

9 Jan 2012, 3:16 AM
that was exactly whar i needed!!!

one thing to mention is that i got stuck with thus Compass error:
"You must compile individual stylesheets from the project directory "

I figure it out by creating a new project and work by your instructions there...(copying all sencha's file to the new project and back)

10 Jan 2012, 1:08 AM
Was suffering with the problem for a few hours - I was sass --watch sencha-touch.sass:sencha-touch.css instead of doing the whole folder, stupid me.

Thanks a bunch!

14 Mar 2012, 6:44 AM
Hmm, I don't get it. I have everything set up correctly but when i compile I only get the errer message "Nothing to compile. If you're trying to start a new project, you have left off the directory argument."

I cd into the actual sass directory and the do compass compile. Is that wrong to do? :-/

19 Apr 2012, 6:14 AM

you are the effin man! thank u so much for posting this because the worst part of styling sencha touch is just getting everything set up and running.

19 Apr 2012, 8:11 AM
Thanks, dgotty. So glad it helped.

10 Jun 2012, 2:55 PM
Thank you for this post - Had ExtJS setup but was struggling to get Touch theming working - This post helped immensely


2 Jul 2012, 1:34 AM
Hi all,

I was getting this error, when I run the code..

please see the attach file... and reply me asap.

12 Jul 2012, 5:27 AM

You need to open app.scss and put the correct file path within the very first @import. Read the first post of this thread for details.

9 Aug 2012, 8:57 AM
When using touch to generate your starting directory

@import '../sdk/resources/themes/stylesheets/sencha-touch/default/all';

ronan quillevere
21 Aug 2012, 4:56 AM
We made up a very simple tutorial to setup sass and compass on windows 7. Maybe It can help someone here.

http://one2teamdev.blogspot.fr/2012/08/sass-for-sencha-touch-2-windows-7.html (http://one2teamdev.blogspot.fr/2012/08/sass-for-sencha-touch-2-windows-7.html)

18 Oct 2012, 1:00 PM
For those windows users who might have gotten tripped up - be sure to use forward slashes and not backwards ones. Once I did that, ST 2.1 RC1 worked out of the box without any of the changes mentioned in this thread. I didn't have to fiddle with anything (other than previously installing ruby/sass/etc), just do:

compass compile project/resources/sass/

25 Oct 2012, 8:13 AM
I've been struggling with this SASS stuff the last few days. I've gone and set up my project just like how the guide says to and everything compiles with compass but my icons don't seem to show up, but my custom colour for buttons does work.

One thing I've noticed is in my sencha-touch.css is this:

/* line 38, C:/Users/rvoth/Sencha/ClaimApp/assets/resources/sass/../themes/stylesheets/sencha-touch/default/core/../_mixins.scss */
.x-tab img.home, .x-button img.x-icon-mask.home {
-webkit-mask-image: theme_image("default", "pictos/home.png");

In another example, I've seen that webkit-mask-image line have url() and then an already base64 encoded string there.

My config.rb looks like this:

# Delineates location of the config.rb file which should be in the same directory as your SCSS file(s)
sass_path = File.dirname(__FILE__)

# Points to the location of the CSS file(s) you'll call from your HTML document
css_path = File.join(sass_path, '..', 'css')

# Points to the images directory used by the Sencha Touch theme
images_dir = File.join(sass_path, '..', 'themes', 'images', 'default')

# Points to the Sencha Touch theme
load File.join(sass_path, '..', 'themes')

# Denotes how the CSS files are compiled by Compass
output_style = :compressed
environment = :production

My sencha-touch.scss:

@import '../themes/stylesheets/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-list-paging;
@include sencha-list-pullrefresh;
@include sencha-layout;
@include sencha-carousel;
@include sencha-form;
@include sencha-msgbox;
@include sencha-loading-spinner;

@include pictos-iconmask('add');
@include pictos-iconmask('team');
@include pictos-iconmask('compose');
@include pictos-iconmask('info');
@include pictos-iconmask('star');
@include pictos-iconmask('more');
@include pictos-iconmask('user');
@include pictos-iconmask('home');

Here's an image of my folder structure: http://i.imgur.com/KBkOQ.png

Everything looks right to me. The only thing that I can possibly think of is that we're using sencha-touch-1.1.1, would it possibly have something to do with not being version 2?

Edit: Figured this out myself. If anybody did what I did, make sure you're using the .css files from the /css/ folder and not the /stylesheets/ folder (if you have one in your /resources/ folder. Apparently that was added in by accident.

10 Nov 2012, 9:33 PM
hi.. tis is really nice i was suffering a lot for 3 days for an error but after reading tis thing i found out thx!!!

17 Jan 2013, 2:46 PM
you've saved a few days for me!

Greg Arnott
24 Mar 2013, 2:21 PM
I've inherited an interesting project. ST2.0 project built with Architect.

This project was upgraded to 2.1 using the inbuilt functionality of the new Architect.

What this left me with was the original /sdk/resources, /touch/resources, /resources and interestingly another folder ../resources (yes, in parent of app folder) that had another /touch/ folder just for good measure of confusion.

Architect had scattered the working config into a chaotic mess. Found out the old project aliased the styling build from the parent resource folder into the app resources to help with build speeds.

Likewise, I've 15 years in (mostly) front-end development working with majority of frameworks and backends. Untangling this project was becoming a nightmare. This post was a ray of enlightenment and the final piece to solving the gordian knot.

Many thanks.

Greg Arnott
24 Mar 2013, 3:18 PM
How you've altered the import pathing for the sencha touch "compass extension" (http://compass-style.org/help/tutorials/extensions/)

@import 'sencha-touch/default/all';

Firstly, consider this path from the config.rb:

// Points to the Sencha Touch theme
load File.join(sass_path, '..', 'themes')

Within this directory one finds a file compass_init.rb.

# This file registers the sencha-touch framework with compass
# It's a magic name that compass knows how to find.
dir = File.dirname(__FILE__)
require File.join(dir, 'lib', 'theme_images.rb')

# Include compass-recipes
require File.join(File.dirname(__FILE__), 'vendor', 'compass-recipes', 'config')

Compass::BrowserSupport.add_support('repeating-linear-gradient', 'webkit', 'moz', 'o', 'ms')
Compass::Frameworks.register 'sencha-touch', dir

The important points:

"sencha-touch" becomes a registered framework extension for this project.
images you've hard referenced via your config.rb file are originally included by this compass_init.rb and its referenced /themes/lib/theme_images.rb file.
using as a framework extension makes "@import 'sencha-touch/default/all';" also work, and not require modification.
@markwyner's original post is very helpful for understanding the development structure of the compass/sass element of touch. One should read the linked page at the top of my message on compass extensions as well as compass configuration (http://compass-style.org/help/tutorials/configuration-reference/) before making multiple changes to their config.rb file.

24 Mar 2013, 11:14 PM

when I use the command compass compile It get the error

Line 23 of _button.scss: Undefined variable: "$base-gradient".

I have defined the variable "$base-gradient" in scss file.

17 Nov 2015, 7:16 AM
http://imgupp.com/img/1442154980.jpg (http://imgupp.com/1442154980.html)