Colin Codes

Using Chance to Build SproutCore Themes

For some people, developing themes is just about the worst thing about working with SproutCore (not that it’s hard, but everything else is easy!). Thankfully, Alex Iskander has developed a new program in Ruby to help making theming a little easier. What’s in it for you? It’s got automatic support for spriting (and slicing). Awesome. He’s also using it to develop a new version of the Ace theme. Double awesome.

To get started using Chance, you’re going to need to install some Ruby packages. First, you’l need the imagemagick extension. This is easily installed using MacPorts if you’re on a Mac. It’s as easy as

sudo port install imagemagick

This library has many dependencies so you might want to grab a coffee. After that’s complete, you’ll lastly need to install rmagick:

sudo gem install rmagick

After this, you should be ready to rock. Using Terminal, cd into your project directory and if you don’t have a themes folder yet, run

mkdir -p themes/my_theme && cd themes/my_theme

Next, we’ll get the Chance source. It’s hosted on Josh Holt’s github account. Run

git clone git://github.com/joshholt/Chance chance

Finally, done with the setup. Now you’re ready to start adding your CSS code. If you want a fantastic reference theme, there’s no better place to start than the new Ace repository on Github.

What Chance will do is read whatever is in your themes/my_theme/src directory and generate the themes/my_theme/resources directory that is read by SproutCore’s buildtools when building your application.

Say you want to a custom toolbar background. You might save your file to themes/my_theme/src/toolbars/my_toolbar/toolbar.png. Now, create a CSS file in the same directory (perhaps call it toolbar.css, but that’s up to you). We’ll provide the following declaration:

@view(my-toolbar) {

    background: sprite(toolbar.png repeat-x [0,1]);

}

We see two non-native CSS directives here so let’s explain what they accomplish. The @view() directive will take whatever is provided to it and generate the following class definition:

.sc-theme .sc-view.my-toolbar

This could be a little different (I’ll touch on this a little further down). Chance also provides for a sprite() directive inside the background declaration, which is really its bread and butter. We can provide sprite with just a filename, and it’ll add it to the sprited image (ie. instead of loading tens or hundreds of images, Chance will combine these images into only a couple images maximum, which will significantly lower the number of HTTP requests your application needs to make). We can also provide sprite() with a repeat parameter, which will let it know whether we want for this image to be repeat-x, or repeat-y (by not providing either, repeat-none is implied).

The third parameter provided above is really where the voodoo comes in. Instead of having to manually slice images, we can provide Chance with parameters to slice from within the image. When will this come in handy? Well, for instance, say you have a button image, but the middle needs to resize to fit larger content. Normally, you would need to slice the images in Photoshop, which is a major pain in the ass if you need to edit the design later. This is pretty easily handled with Chance using CSS (no Photoshop monkey work for us, we’re SproutCore developers dammit!):

@view(my-custom-button) .button-left {

    background: sprite(“button.png” [0,6]);

}

@view(my-custom-button) .button-middle {

    background: sprite(“button.png” repeat-x [6,1]);

}

@view(my-custom-button) .button-right {

    background: sprite(“button.png” [-6]);

}

Let’s digest this. In the first CSS declaration, we’re defining a slice on the x-axis from the 0’th pixel (the first) to the 6th. This might be because we’ve got some rounded corners that extend 6 pixels into our image. In the second declaration, we’re defining a repeating background starting from the 6th pixel and extending 1 pixel (in the image) which will be repeated over and over in our view, to fit the content. The third and last declaration defines the display for the right side of the button. Notice the number is negative, this means Chance will build it from right-to-left, rather than the normal left-to-right.

So now we’re ready to build our theme. In the root of our theme (themes/my_theme) simply type

chance/chance.rb

and then check the resources folder to see what Chance did for us.

There are some changes coming up in the SproutCore view layer that will make theming much, much better and more powerful. Chance allows us to provide theme names to attach to every class declared using the @view() directive. If we run

chance/chance.rb app.theme

We’ll get the following output:

.sc-theme .sc-view.my-custom-view.app.theme {

   …

}

Personally, until the newest code being developed by Alex is pushed to the main repository, I’m holding off on adding a theme name. Once that code is being used, the theme names will automatically be added to our views and we won’t need to do this by hand. In the meantime, not providing a name helps me avoid adding the theme names to my views by hand. As this new code is developed and added into the master branch, I’ll be adding new tutorials about how you can use theme extending and renderers to further badass your SproutCore app.