Permalink
Browse files

Update README to do a better job of explaining what SproutCore is.

  • Loading branch information...
1 parent 55aeb97 commit ce15182c19fe481cda0042653f84b037150e4ef3 Tom Dale committed Jun 23, 2011
Showing with 89 additions and 2 deletions.
  1. +89 −2 README.md
View
@@ -1,3 +1,90 @@
+# SproutCore
+
+SproutCore is a JavaScript framework that does all of the heavy lifting that you'd normally have to do by hand. There are tasks that are common to every web app; SproutCore does those things for you, so you can focus on building killer features and UI.
+
+These are the three features that make SproutCore a joy to use:
+
+1. Bindings
+2. Computed properties
+3. Auto-updating templates
+
+## Bindings
+
+Use bindings to keep properties between two different objects in sync. You just declare a binding once, and SproutCore will make sure changes get propagated in either direction.
+
+Here's how you create a binding between two objects:
+
+ MyApp.president = SC.Object.create({
+ name: "Barack Obama"
+ });
+
+ MyApp.country = SC.Object.create({
+ // Ending a property with 'Binding' tells SproutCore to
+ // create a binding to the presidentName property.
+ presidentNameBinding: 'MyApp.president.name'
+ });
+
+ MyApp.country.get('presidentName');
+ // "Barack Obama"
+
+Bindings allow you to architect your application using the MVC (Model-View-Controller) pattern, then rest easy knowing that data will always flow correctly from layer to layer.
+
+## Computed Properties
+
+Computed properties allow you to treat a function like a property:
+
+ MyApp.president = SC.Object.create({
+ firstName: "Barack",
+ lastName: "Obama",
+
+ fullName: function() {
+ return this.get('firstName') + ' ' + this.get('lastName');
+
+ // Call this flag to mark the function as a property
+ }.property()
+ });
+
+ MyApp.president.get('fullName');
+ // "Barack Obama"
+
+Treating a function like a property is useful because they can work with bindings, just like any other property.
+
+Many computed properties have dependencies on other properties. For example, in the above example, the `fullName` property depends on `firstName` and `lastName` to determine its value. You can tell SproutCore about these dependencies like this:
+
+ MyApp.president = SC.Object.create({
+ firstName: "Barack",
+ lastName: "Obama",
+
+ fullName: function() {
+ return this.get('firstName') + ' ' + this.get('lastName');
+
+ // Tell SproutCore that this computed property depends on firstName
+ // and lastName
+ }.property('firstName', 'lastName')
+ });
+
+Make sure you list these dependencies so SproutCore knows when to update bindings that connect to a computed property.
+
+## Auto-updating Templates
+
+SproutCore uses Handlebars, a semantic templating library. To take data from your JavaScript application and put it into the DOM, create a `<script>` tag and put it into your HTML, wherever you'd like the value to appear:
+
+ <script type="text/html">
+ The President of the United States is {{MyApp.president.fullName}}.
+ </script>
+
+Here's the best part: templates are bindings-aware. That means that if you ever change the value of the property that you told us to display, we'll update it for you automatically. And because you've specified dependencies, changes to *those* properties are reflected as well.
+
+Hopefully you can see how all three of these powerful tools work together: start with some primitive properties, then start building up more sophisticated properties and their dependencies using computed properties. Once you've described the data, you only have to say how it gets displayed once, and SproutCore takes care of the rest. It doesn't matter how the underlying data changes, whether from an XHR request or the user performing an action; your user interface always stays up-to-date. This eliminates entire categories of edge cases that developers struggle with every day.
+
+# Getting Started
+
+For new users, we recommend downloading the [SproutCore Starter Kit](https://github.com/sproutcore/starter-kit/downloads), which includes everything you need to get started.
+
+We also recommend that you check out the [annotated Todos example](http://annotated-todos.strobeapp.com/), which shows you the best practices for architecting an MVC-based web application.
+
+To learn more about what we're up to, follow [@sproutcore on Twitter](http://twitter.com/sproutcore), [subscribe to the blog](http://blog.sproutcore.com), or [read the original SproutCore 2.0 announcement](http://blog.sproutcore.com/announcing-sproutcore-2-0/).
+
# How to Run Unit Tests
1. Install Ruby and Rubygems. There are many resources on the web can help you to do so, one of the best ways may be [rvm](http://rvm.beginrescueend.com/).
@@ -11,14 +98,14 @@
cd sproutcore20
spaderun update
spaderun preview
-
+
4. Then visit: http://localhost:4020/tests.html?package=PACKAGE_NAME. Replace 'PACKAGE_NAME' with the name of the package you want to run. For example:
* [SproutCore Runtime](http://localhost:4020/tests.html?package=sproutcore-runtime)
* [SproutCore Views](http://localhost:4020/tests.html?package=sproutcore-views)
* [SproutCore DataStore](http://localhost:4020/tests.html?package=sproutcore-datastore)
* [SproutCore Handlebars](http://localhost:4020/tests.html?package=sproutcore-handlebars)
-
+
# Adding New Packages
Be sure you include the new package as a dependency in the global `package.json` and run `spaderun update`.

0 comments on commit ce15182

Please sign in to comment.