Getting Started: Part 1
Welcome to SproutCore! This guide will get you up-and-running as quickly as possible with SproutCore. For this individual guide, you will:
- Install SproutCore on your machine.
- Use the SproutCore tools to generate a basic starting application.
- Run the SproutCore development server to test your application.
- Modify the application to ensure that changes are visible.
1 - Introduction
The introductory "Getting Started" guides pages are step-by-step treatments of concepts needed to make a full SproutCore application.
This first "Getting Started" guide will ensure that you have the latest version of Sproutcore installed and configured properly. If you run into any issues or bumps along the way, please reach out on the mailing list or find us on IRC at #sproutcore!
2 - Installation
There are two basic ways to install SproutCore.
- The Package Installers
- Using RubyGems
The installation method you choose should be based upon your current platform and your experience with Ruby. The installers are currently only available for Windows and Mac. Linux and other platforms should use the RubyGems method.
Additionally, if your machine is already setup for development in Ruby, you may find it more convenient to forgo the package installers, and use RubyGems so that you can always get the latest version by typing the following:
gem update sproutcore
So, before you move on, please visit the Installation Page and either download the appropriate package, or follow the guide for your platform.
Great! Now that SproutCore is installed, we can move forward and get our first app up-and-running!
3 - Creating A New SproutCore Application
When you are first learning any new language or framework, it is generally a good idea to create a separate directory to store all of your code. So, in some area of your hard drive where you develop software, make a sproutcore directory.
$ mkdir -p ~/development/sproutcore
The dollar sign ($) in the code above and below represents the command line prompt and should not be typed when executing the commands. Lines without a prompt generally show you the output of the previous command.
This directory can serve as a place for all things SproutCore. Change directory to ~/development/sproutcore, then create a SproutCore project:
$ cd ~/development/sproutcore $ sproutcore gen project getting_started ~ Created directory at getting_started ~ Created file at getting_started/Buildfile ~ Created file at getting_started/README Your project is now ready to use! $ cd getting_started
Now you have a getting_started project directory, ~/development/sproutcore/getting_started. We will build several SproutCore apps in this project space, but for now, we'll just create a basic "Hello World" style application to ensure that everything is installed and working properly.
Create the app in the getting_started project directory:
$ sproutcore gen app TodosOne ~ Created directory at apps ~ Created directory at apps/todos_one ~ Created file at apps/todos_one/Buildfile ~ Created file at apps/todos_one/core.js ~ Created file at apps/todos_one/main.js ~ Created directory at apps/todos_one/resources ~ Created file at apps/todos_one/resources/_theme.css ~ Created file at apps/todos_one/resources/loading.rhtml ~ Created file at apps/todos_one/resources/main_page.js ~ Created file at apps/todos_one/theme.js Your application target is now ready to use!
Your directory structure should now look like the following:
4 - Explanation
When you are building a web application in SproutCore, it is common to have a multitude of mini-applications in order to separate out the logic into manageable parts. For instance, Apple's iCloud application has apps for e-mail, contacts and finding your friends.
This is why there is an apps/ directory inside of the getting_started project directory. It allows you to easily separate distinct applications.
Inside the apps/todos_one directory, you will find the Buildfile for the TodosOne application. Just like the project (getting_started) has a Buildfile, each application or framework that you create should also have a Buildfile which specifies it's requirements as well as any build-options that you may want to change, such as whether or not to minify and compact the code.
The core.js file is the first file that gets loaded, and is where the actual application is defined. This is also where you usually define any global constants that the application might use (which should be very few), or any configuration that external libraries might require.
The main.js file is usually very basic. It starts the application. If you are using the Statechart framework (which we will discuss in Part 2), main.js would simply initialize the statechart. If you open up main.js right now, you'll see that it appends the main view to the screen.
The resources folder contains things like images, stylesheets and views.
Inside the resources folder, the _theme.css file defines that directory's CSS theme. This allows you to define different themes for each directory.
The resources/loading.rhtml file defines the HTML that your users see before SproutCore has fully loaded and handed control over to the application. For now, it displays a simple loading message.
Lastly, the resources/main_page.js file describes the actual user interface of the application. Open this file now and take a look. Depending upon how complex the app becomes, you may decide to have just the mainPage and mainPane, or you may decide you want to break it out a bit more by having a loadingPane, loggedInPane, loggedOutPane, etc. Most applications have at least a few panes, and possibly a few pages.
5 - Viewing Your Application
So, we have our SproutCore TodosOne application built, and we understand the basic layout of the files. Let's see what it looks like in the browser!
Inside the project directory type the following command:
$ sproutcore server
If you are attempting to run multiple copies of sproutcore server at the same time, you will probably see an error about the port already being in use. If so, just re-run the command and add --port 4030 so the second instance will not use the default 4020 port.
Using your favorite web browser, visit http://localhost:4020/todos_one. If all goes well, you should see "Welcome to Sproutcore!" in the middle of the screen.
6 - Making Changes
Open up resources/main_page.js and change the "Welcome to SproutCore!" line to say "SproutCore is Awesome!". Save the file and refresh the page in your web browser. If the message updates properly, you're ready to move on to Getting Started: Part 2 of the tutorial.
7 - Troubleshooting
As with any unfamiliar framework, you may hit a few snags on the way. Below we list some of the common pitfalls that users have discovered, with solutions for getting past them.
"Error: Handlebars is not defined Source File: ..." - If you have previously installed SproutCore 1.6 using the installer, you may see this error. If so, please make sure to un-install SproutCore 1.6 first and then re-install 1.8.
"RuntimeError at /todos_one html_builder could not find a layout file for ..." - This error usually means that sproutcore server could not find SproutCore where it thought it should exist. Make sure that you've properly installed the latest version of SproutCore; and if you are using RubyGems, try closing and re-opening the terminal to ensure that paths are properly set.
"Browser says 'No matching target'" - This is generally caused if you misspelled the name of the application in the URL. Make sure that you properly typed it, and that you used underscores instead of spaces. For example: http://localhost/todos_one.
"ERROR: missing } after property list ..." - This error is usually thrown if you added a property somewhere, but forgot to put a comma at the end. Look at the line in the error, and then look above it to see if there is a comma missing.
8 - Changelog
- March 1, 2011: initial version by Tom Dale
- March 2, 2011: fixed formmating and added paths to filenames by Topher Fangio and Peter Wagenet
- March 22, 2011: cleaned up demo based on new features by Yehuda Katz
- April 11, 2011: consistently use view classes and extend, update to reflect better Handlebars integration by Yehuda Katz and Tom Dale
- May 6, 2011: clarifications, minor inconsistency fixes, updated CSS for older browsers, plus new mobile section by Tyler Keating
- May 9, 2011: update for recent changes in SproutCore 1.6 by Tom Dale and Yehuda Katz
- March 6, 2012: rewrite for SproutCore 1.8 by the 1.8 release sprint team, including the following who did much work on this task: Tim Evans, Topher Fangio and Jeff Pittman
- March 12, 2012: added new error and fixed italics in the troubleshooting section by Topher Fangio
- July 30, 2013: converted to Markdown format for DocPad guides by Eric Theise
- July 30, 2013: fix issues with formatting and updated Changelog by Topher Fangio