Sproutcore: WTF Am I Downloading?
There’s always been a little confusion over what exactly you’re downloading when you get Sproutcore.
Sproutcore Abbot
Abbot is the name for the new-ish build tools that compile Sproutcore 1.0 projects. It includes all of our favourites, like sc-gen, sc-server, and sc-build. When you do
gem install sproutcore
what you’re actually downloading is the Abbot build tools.
Then How Do I Get Sproutcore?
The Sproutcore Javascript framework is included with the Abbot build tools. This is why when sc-init’ing a project, you don’t need to do anything as far as downloading the JS framework to access the Sproutcore code.
How Do I Stay Up To Date With The Framework?
Using the most recent revisions to the JS framework that is on Github is really simple. As I mentioned in the last post, you cd into your project directory and run
mkdir -p frameworks && cd frameworks
git clone git://github.com/sproutit/sproutcore.git
This will get you the most recent master branch in a “frameworks” directory. The Abbot build tools are smart enough to use this copy of the JS framework, rather than the one it downloaded in the gem install process.
It’s worth mentioning now that we’ve made a lot of progress towards Sproutcore 1.1, and the code lives in the Quilmes branch. If you’d like to use that latest awesome sauce, you can create a git tracking branch like so
cd your_project/frameworks/sproutcore
git fetch
git checkout -b quilmes origin/quilmes
Staying Updated with Abbot
Abbot doesn’t move nearly as fast as the JS framework (at least, not anymore) but there are still occasional fixes that get implemented that are nice to have around, instead of waiting for new gem releases. If you’re in your project directory, cd out and checkout abbot by doing:
cd ../
git clone git://github.com/sproutit/sproutcore-abbot.git abbot
This will create a folder “abbot” in the same directory housing your project. Then when you want to run sc-server, say, from inside of your project directory, you just run
../abbot/bin/sc-server
And voila, you’re using the most recent revisions to Abbot.
Hopefully this alleviates some confusion over what exactly Abbot is and how it is different from Sproutcore the JS framework.
Including a Framework with Your Project
Including external code in your project is very important in saving time and headaches with Sproutcore. In this post, I’ll quickly go over how to add Sproutcore UI to a project.
sc-init MyProject && cd my_project
Now that you’ve got a generated Sproutcore, we’re going to create the frameworks folder.
mkdir frameworks && cd frameworks
Now we’re in the frameworks directory. The Abbot build tools are cool enough to know that anything in here should be included in the build process (once we add the framework to the Buildfile). First things first, let’s download the Sproutcore UI package using git:
git clone git://github.com/etgryphon/sproutcore-ui.git scui
This will create an scui folder inside of your frameworks folder that contains that latest code. Now, open Buildfile in the project’s root directory, and you’ll see
config :all, :required => :sproutcore
I like to keep my requirements explicit (ie, don’t use :all). Instead, add this line after what’s there:
config :my_project, :required => [:sproutcore, :scui]
You should now be able to use the Sproutcore UI code inside of your app.
Bonus
For those of you that don’t know this, you can actually add Sproutcore to your frameworks directory, and it will override the one that came with Abbot. This is especially handy if you want to follow the master or quilmes branches at the Sproutcore git repository, instead of using the already stale 1.0 release.
Sproutcore and Flot
Quick note for fellow dummies. When you’re trying to use Flot with SproutCore, do the following:
layerDidChange: function() {
this.set('layerNeedsUpdate', YES);
}.observes('layer'),
updateLayer: function() {
sc_super();
var layer = this.get('layer');
if (layer) $.plot(layer, this.get('data'));
}
Initially I was trying to use updateLayer as per this thread on the SproutCore Google group. The problems with width/height being 0 on the element come from trying to run the plot function before the end of the current RunLoop. Setting layerNeedsUpdate to YES steps around this, as updateLayerIfNeeded is run at the end of the current RunLoop.
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.
