Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 127 lines (83 sloc) 5.898 kb
f813d13 @wycats Rename Amber to Ember
wycats authored
1 # Ember.js
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
2
f813d13 @wycats Rename Amber to Ember
wycats authored
3 Ember.js (formerly SproutCore 2.0) 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; Ember.js does those things for you, so you can focus on building killer features and UI.
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
4
f813d13 @wycats Rename Amber to Ember
wycats authored
5 These are the three features that make Ember.js a joy to use:
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
6
7 1. Bindings
8 2. Computed properties
9 3. Auto-updating templates
10
f813d13 @wycats Rename Amber to Ember
wycats authored
11 Ember.js has strong roots in SproutCore; you can read more about its evolution in [the Ember.js launch announcement](http://yehudakatz.com/2011/12/08/announcing-amber-js/).
194bfa2 @purp Change the name and some elementary bits.
purp authored
12
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
13 ## Bindings
14
f813d13 @wycats Rename Amber to Ember
wycats authored
15 Use bindings to keep properties between two different objects in sync. You just declare a binding once, and Ember.js will make sure changes get propagated in either direction.
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
16
17 Here's how you create a binding between two objects:
18
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
19 ```javascript
20 MyApp.president = Ember.Object.create({
21 name: "Barack Obama"
22 });
23
8618e23 @nwjsmith Fix mistake made in renamespacing
nwjsmith authored
24 MyApp.country = Ember.Object.create({
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
25 // Ending a property with 'Binding' tells Ember.js to
26 // create a binding to the presidentName property.
27 presidentNameBinding: 'MyApp.president.name'
28 });
29
30 MyApp.country.get('presidentName');
31 // "Barack Obama"
32 ```
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
33 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.
34
35 ## Computed Properties
36
37 Computed properties allow you to treat a function like a property:
38
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
39 ``` javascript
40 MyApp.president = Ember.Object.create({
41 firstName: "Barack",
42 lastName: "Obama",
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
43
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
44 fullName: function() {
45 return this.get('firstName') + ' ' + this.get('lastName');
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
46
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
47 // Call this flag to mark the function as a property
48 }.property()
49 });
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
50
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
51 MyApp.president.get('fullName');
52 // "Barack Obama"
53 ```
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
54
55 Treating a function like a property is useful because they can work with bindings, just like any other property.
56
f813d13 @wycats Rename Amber to Ember
wycats authored
57 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 Ember.js about these dependencies like this:
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
58
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
59 ``` javascript
60 MyApp.president = Ember.Object.create({
61 firstName: "Barack",
62 lastName: "Obama",
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
63
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
64 fullName: function() {
65 return this.get('firstName') + ' ' + this.get('lastName');
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
66
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
67 // Tell Ember.js that this computed property depends on firstName
68 // and lastName
69 }.property('firstName', 'lastName')
70 });
71 ```
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
72
f813d13 @wycats Rename Amber to Ember
wycats authored
73 Make sure you list these dependencies so Ember.js knows when to update bindings that connect to a computed property.
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
74
75 ## Auto-updating Templates
76
f813d13 @wycats Rename Amber to Ember
wycats authored
77 Ember.js 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:
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
78
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
79 ``` html
80 <script type="text/x-handlebars">
81 The President of the United States is {{MyApp.president.fullName}}.
82 </script>
83 ```
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
84
85 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.
86
f813d13 @wycats Rename Amber to Ember
wycats authored
87 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 Ember.js 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.
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
88
89 # Getting Started
90
f813d13 @wycats Rename Amber to Ember
wycats authored
91 For new users, we recommend downloading the [Ember.js Starter Kit](https://github.com/emberjs/starter-kit/downloads), which includes everything you need to get started.
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
92
f813d13 @wycats Rename Amber to Ember
wycats authored
93 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. You can also [browse or fork the code on Github](https://github.com/emberjs/todos).
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
94
f813d13 @wycats Rename Amber to Ember
wycats authored
95 [Guides are available](http://guides.sproutcore20.com/) for Ember.js. If you find an error, please [fork the guides on GitHub](https://github.com/sproutcore/sproutguides/tree/v2.0) and submit a pull request. (Note that Ember.js guides are on the `v2.0` branch.)
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
96
f813d13 @wycats Rename Amber to Ember
wycats authored
97 # Building Ember.js
22df75f Vendor ruby dependencies to ease build process for those uncomfortabl…
tomhuda authored
98
f813d13 @wycats Rename Amber to Ember
wycats authored
99 NOTE: Due to the rename, these instructions may be in flux
100
101 1. Run `rake` to build Ember.js. Two builds will be placed in the `dist/` directory.
102 * `ember.js` and `ember.min.js` - unminified and minified
103 builds of Ember.js
22df75f Vendor ruby dependencies to ease build process for those uncomfortabl…
tomhuda authored
104
105 If you are building under Linux, you will need a JavaScript runtime for
106 minification. You can either install nodejs or `gem install
107 therubyracer`.
108
b96e4c2 @charlesjolley Add read me with basic testing info.
charlesjolley authored
109 # How to Run Unit Tests
110
375f5a9 @ebryn Update readme with RakePipeline-based instructions.
ebryn authored
111 1. Install Ruby 1.9.2+. There are many resources on the web can help; one of the best is [rvm](http://rvm.beginrescueend.com/).
231f4b1 Fix the 'How to Run Unit Tests' part in the README.md file. Fix issue…
Gimi Liang authored
112
375f5a9 @ebryn Update readme with RakePipeline-based instructions.
ebryn authored
113 2. Install Bundler: `gem install bundler`
231f4b1 Fix the 'How to Run Unit Tests' part in the README.md file. Fix issue…
Gimi Liang authored
114
375f5a9 @ebryn Update readme with RakePipeline-based instructions.
ebryn authored
115 3. Run `bundle` inside the project root to install the gem dependencies.
231f4b1 Fix the 'How to Run Unit Tests' part in the README.md file. Fix issue…
Gimi Liang authored
116
375f5a9 @ebryn Update readme with RakePipeline-based instructions.
ebryn authored
117 4. To start the development server, run `bundle exec rackup`.
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
118
375f5a9 @ebryn Update readme with RakePipeline-based instructions.
ebryn authored
119 5. Then visit: `http://localhost:9292/tests/index.html?package=PACKAGE_NAME`. Replace `PACKAGE_NAME` with the name of the package you want to run. For example:
b96e4c2 @charlesjolley Add read me with basic testing info.
charlesjolley authored
120
c0018e2 @wagenet Renamed files and updated a few more references
wagenet authored
121 * [Ember.js Runtime](http://localhost:9292/tests/index.html?package=ember-runtime)
122 * [Ember.js Views](http://localhost:9292/tests/index.html?package=ember-views)
123 * [Ember.js Handlebars](http://localhost:9292/tests/index.html?package=ember-handlebars)
ed0487d Update README for bpm
Tom Dale authored
124
375f5a9 @ebryn Update readme with RakePipeline-based instructions.
ebryn authored
125 To run multiple packages, you can separate them with commas. You can run all the tests using the `all` package:
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
126
375f5a9 @ebryn Update readme with RakePipeline-based instructions.
ebryn authored
127 [http://localhost:9292/tests/index.html?package=all](http://localhost:9292/tests/index.html?package=all)
Something went wrong with that request. Please try again.