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

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 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:

• getting_started/
  • sc_config
  • apps/
    • TodosOne/
      • sc_config
      • core.js
      • main.js
      • theme.js
      • statechart.js
      • controllers/
      • fixtures/
      • views/
      • states/
        • ready_state.js
      • resources/
        • _theme.css
        • loading.ejs
        • main_page.js
        • main_page.css

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

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.

Chapters

1. Introduction

2. Installation

3. Creating A New SproutCore Application

4. Explanation

5. Installing the SproutCore framework

6. Viewing Your Application

7. Making Changes

8. Troubleshooting

9. Changelog