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, find us on IRC at #sproutcore or leave a message on Gitter!
2 - Installation
To install the SproutCore development environment you need to have NodeJS and NPM installed. The latest version of NodeJS currently supported by this environment is 9.x.
Please visit the Installation Page and 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
create a SproutCore project:
$ cd ~/development/sproutcore $ sproutcore init getting_started Your project has been successfully created! $ 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 App TodosOne generated
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/TodosOne directory, you will find the sc_config for the TodosOne application. Just like the project (getting_started) has a sc_config, each application or framework that you create should also have a sc_config 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. The default assumes you are using the Statechart framework (which we will discuss in Part 2). main.js simply initializes the statechart, which you will see if you open up main.js right now.
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.ejs 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 - Installing the SproutCore framework
$ sproutcore install sproutcore frameworks
This installs the SproutCore framework inside the frameworks folder of your project.
6 - 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 serve
If you are attempting to run multiple copies of **sproutcore serve** 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/TodosOne. If all goes well, you should see "Welcome to Sproutcore!" in the middle of the screen.
7 - 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.
8 - 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.
"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/TodosOne.
"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.
9 - Changelog
- March 1, 2011: initial version by [Tom Dale](credits.html#tomdale and Yehuda Katz
- 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
- January 17, 2019: Change to NPM build tools.