Mastering the Compass/SASS Setup with Sencha Touch
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.
If you compare the paths in config.rb code above to my directory structure (below) you'll notice they pair up perfectly:
// 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
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:
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.
images_dir = File.join(sass_path, "..", "img")
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.
load File.join(sass_path, '..', '..', '..', '..', 'resources', 'themes')
SCSS @IMPORT PATH
All the docs/samples/downloads have your app's SCSS file importing the Sencha Touch theme CSS like this:
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:
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.
PROPERLY REFERENCING PATHS WHEN RUNNING COMPASS COMMANDS
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:
But even if the commands are familiar to you, you may run into problems with how Compass references paths on your machine.
compass compile path/to/scss (batch compiles on command)
compass watch path/to/scss (compiles in real time as changes are saved)
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:
I needed to run:
compass watch /users/markwyner/project/resources/sass/myapp.scss
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.
compass watch project/resources/sass/
SUMMARY OF CRITICAL POINTS
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.
Can anyone from the Sencha team provide an easy step-by-step instruction guide?
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.