This page will take you on a tour of how you might build a SproutCore app from scratch all the way through  deployment.  The purpose of this is to give you a sense of how a typical SproutCore app flows.  This page won't explain the technical details of the steps.

1. Create an app using sc-init
   1. Built-in generators from the build tools automatically setup your project, add unit tests and help enforce good coding guidelines.

2. Define your model

   1. Design your schema based on the types of records you might need to exchange with the server.

   2. Use sc-gen to add new model records

   3. Define the property types and relationships on your records.  

   4. Define fixtures to give you some sample data to work with

3. Trying it for the first time

   1. During development, you can set your app by running sc-server.  

   2. sc-server is a simple web server that will dynamically compile your app as needed.  This way you can change some files and hit refresh in your browser to see your app running immediately.  Even though you never explicitly compiled your app, it will actually run in the browser just like it will when you go to production.

   3. sc-server can also proxy certain URLs to another backend server.  

      1. Often you will develop by visiting sc-server to load your app and then have sc-server proxy to a development server for your backend so you can test with real data.

   4. You can start to play with your model by starting sc-server and then visiting http://localhost:4020/your_app

   5. Open the JavaScript console and try creating records, manipulating them, etc.

   6. We suggest using Safari/Webkit and the WebKit Inspector.  SC has special features designed for these dev tools.

4. Design your views

   1. Views are configured in a Page object.  A default main_page.js is added to your english.lproj folder.  You can add other .lproj folders for localization later in the process.

   2. When you design views, you can set properties and layout.

   3. Eventually we will have a drag-and-drop UI designer that will generate a page object for you.

5. Add custom views

   1. If you need to create views with custom logic in them; or maybe add a new type of control, you can add a custom view.

   2. Use sc-gen to add the view.  

   3. Also adds unit tests.  You should write unit tests for your views to make sure they can work independently of your application.  This makes them reusable for future work.

   4. You can name custom views in your page design just like any other view.  This will work in the drag-and-drop UI designer as well.

6. Add controllers and bindings

   1. A controller acts as an anchor to your application.  

      1. You set its "content" property to point to a model object or to another controller and then you use "bindings" to connect properties on the controller to properties on your views. 

      2. The controller will then relay changes in your model to your views.

      3. Your views will change their own properties in response to user actions.  The controllers will relay those property changes to your model, and so on.

   2. You add controllers to your app using sc-gen.  Then add bindings to your view design and to the controller objects themselves

   3. At this point you will be able to see your fixture data in your UI, make changes to it, and watch all of your business logic work.

7. Add Responders

   1. Controllers will relay data changes, but another part of your app involves handling high-level state changes.  For example, your UI may display certain views when the user's data is still loading; other views when the user has no data and needs to add some; and yet other views when there is data visible and ready to edit.

   2. You can implement this part of your app "free-hand" by simply writing code on controllers or on objects you create yourself.  Or you can use the SproutCore Responder system.

   3. Responder objects respond to "Actions" sent by your user interface and then reconfigure your application.  You can model them by designing "statecharts".

   4. Responders are a newer part of the framework that have the potential to eliminate one of the last remaining sources of "spaghetti" code in your applicaton, but many developers still just freestyle this part of the app in a way that makes sense to them.

8. Add a DataSource

   1. Now that your app is basically functioning, you can hook your app to  the server. 

   2. You can use any server backend you like.  The technology does not matter.  

   3. You write a DataSource class that interfaces with your server and your Model objects.  SproutCore will automatically call your data source whenever it needs to fetch data from the server or commit changes back to the server.  You can also push data from the server at any time.

   4. You add a data source and implement the callback methods to talk to your server.  

      1. If a JS library already exists that can talk to your server, you could write your data source as a wrapper around that library

      2. If you need to write this from scratch, SC.Request provides an easy way to do Ajax without needing to use another library like jQuery or Prototype

   5. Data source is another great place to add unit tests.

9. Adding localizations

   1. If you plan to launch with multiple languages, you can add a new language using sc-gen.

   2. Your app has a default language (usually english) and one or more target languages.  When building for a target language, the build tools will use all the files in your default language .lproj directory.  Any files with the same name in the target language .lproj will be used instead.

   3. All new projects come with a strings.js file.  This is where you put strings you want localized.  Usually you will add one strings.js file per .lproj directory.

   4. In your code,you can localize any string by calling the .loc() method on it.  This will lookup the string in the localizated strings.js file and use it if available.

   5. Once you build your lproj directories, you can usually send your strings.js file off to someone to have it localized.

   6. You can also add a localization for each of your view designs, allowing you to override specific settings (especially the layout) for each view.

10. Testing

    1. You now have all of the pieces of your app in place.  

    2. You will probably want to test it on lots of different browsers. 

       1. This is where unit tests come in.  

       2. SproutCore's unit test runner makes it easy to run your unit tests on different browsers.

       3. You can actually write unit tests that will launch you app, perform actions, and verify the results.  This is a great way to make sure your app will run properly all the time.

       4. Bigger projects may integrate the tests with Selenium to automate this testing process.

11. Deploying

    1. When you are ready to deploy your app, all you need to do is run sc-build.  

    2. sc-build generates a bundle of HTML, JS, and CSS inside a directory with a MD5 hash code as a build number.

       1. The hash code is based on the contents of the files, so changing your files will change the hash code.

    3. When you deploy your app, you just need to copy the entire contents of the tmp/build directory to a static web server.  

    4. Your web server should be configured to serve everything EXCEPT for the index.html file with a 1-year expiration header.  This will allow your assets to be cached "permanently" on browsers once they load them.

    5. Since the index.html file references the resources it needs by build number, deploying a new version of your app will automatically load the new assets.

    6. Once you've copied your files out, you should symlink the build directory for the app you want to load to the actual URL you want the user to visit to load your app.  

       1. Example:  if you want ppl to visit your app at http://myapp.com/appname and your built project has a directory called static/appname/123efab45aeb29c3de4, then you should symlink /appname -> /static/appname/123efab45aeb29c3de4.

       2. You can actually have multiple built versions of your app deployed this way since each one will have a different build number.  Just create a different symlink to each version you want to load.

12. Congrats!  You've built and deployed a commercial-grade cloud application using SproutCore

--

This graphic was supplied by Erich Ocean about how he teaches the dev process.  We should integrate this into the above explanation.  Note that statechart discussion here is supported by SC.Responder code in the public SproutCore.  There are also some statechart libraries floating around: