Skip to content
This repository
Newer
Older
100644 163 lines (102 sloc) 6.646 kb
ffef82e6 » pangratz
2012-01-10 add image of current travis ci build status
1 # Ember.js [![Build Status](https://secure.travis-ci.org/emberjs/ember.js.png?branch=master)](http://travis-ci.org/emberjs/ember.js)
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
2
f813d13a » wycats
2011-12-12 Rename Amber to Ember
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.
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
4
f813d13a » wycats
2011-12-12 Rename Amber to Ember
5 These are the three features that make Ember.js a joy to use:
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
6
7 1. Bindings
8 2. Computed properties
9 3. Auto-updating templates
10
f813d13a » wycats
2011-12-12 Rename Amber to Ember
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/).
194bfa2b » purp
2011-12-08 Change the name and some elementary bits.
12
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
13 ## Bindings
14
f813d13a » wycats
2011-12-12 Rename Amber to Ember
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.
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
16
17 Here's how you create a binding between two objects:
18
e99d62c6 » Tom Dale
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
19 ```javascript
20 MyApp.president = Ember.Object.create({
21 name: "Barack Obama"
22 });
23
8618e230 » nwjsmith
2011-12-13 Fix mistake made in renamespacing
24 MyApp.country = Ember.Object.create({
e99d62c6 » Tom Dale
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
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
fb169cb1 » wagenet
2012-04-16 Added a note that binding resolution takes time
30 // Later, after Ember has resolved bindings...
e99d62c6 » Tom Dale
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
31 MyApp.country.get('presidentName');
32 // "Barack Obama"
33 ```
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
34 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.
35
36 ## Computed Properties
37
38 Computed properties allow you to treat a function like a property:
39
e99d62c6 » Tom Dale
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
40 ``` javascript
41 MyApp.president = Ember.Object.create({
42 firstName: "Barack",
43 lastName: "Obama",
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
44
e99d62c6 » Tom Dale
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
45 fullName: function() {
46 return this.get('firstName') + ' ' + this.get('lastName');
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
47
e99d62c6 » Tom Dale
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
48 // Call this flag to mark the function as a property
49 }.property()
50 });
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
51
e99d62c6 » Tom Dale
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
52 MyApp.president.get('fullName');
53 // "Barack Obama"
54 ```
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
55
56 Treating a function like a property is useful because they can work with bindings, just like any other property.
57
f813d13a » wycats
2011-12-12 Rename Amber to Ember
58 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:
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
59
e99d62c6 » Tom Dale
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
60 ``` javascript
61 MyApp.president = Ember.Object.create({
62 firstName: "Barack",
63 lastName: "Obama",
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
64
e99d62c6 » Tom Dale
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
65 fullName: function() {
66 return this.get('firstName') + ' ' + this.get('lastName');
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
67
e99d62c6 » Tom Dale
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
68 // Tell Ember.js that this computed property depends on firstName
69 // and lastName
70 }.property('firstName', 'lastName')
71 });
72 ```
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
73
f813d13a » wycats
2011-12-12 Rename Amber to Ember
74 Make sure you list these dependencies so Ember.js knows when to update bindings that connect to a computed property.
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
75
76 ## Auto-updating Templates
77
f813d13a » wycats
2011-12-12 Rename Amber to Ember
78 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:
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
79
e99d62c6 » Tom Dale
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
80 ``` html
81 <script type="text/x-handlebars">
82 The President of the United States is {{MyApp.president.fullName}}.
83 </script>
84 ```
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
85
86 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.
87
f813d13a » wycats
2011-12-12 Rename Amber to Ember
88 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.
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
89
90 # Getting Started
91
f813d13a » wycats
2011-12-12 Rename Amber to Ember
92 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.
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
93
f813d13a » wycats
2011-12-12 Rename Amber to Ember
94 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).
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
95
f813d13a » wycats
2011-12-12 Rename Amber to Ember
96 # Building Ember.js
22df75f1 » tomhuda
2011-07-13 Vendor ruby dependencies to ease build process for those uncomfortabl…
97
f813d13a » wycats
2011-12-12 Rename Amber to Ember
98 NOTE: Due to the rename, these instructions may be in flux
99
100 1. Run `rake` to build Ember.js. Two builds will be placed in the `dist/` directory.
101 * `ember.js` and `ember.min.js` - unminified and minified
102 builds of Ember.js
22df75f1 » tomhuda
2011-07-13 Vendor ruby dependencies to ease build process for those uncomfortabl…
103
104 If you are building under Linux, you will need a JavaScript runtime for
105 minification. You can either install nodejs or `gem install
106 therubyracer`.
107
b96e4c22 » charlesjolley
2011-05-17 Add read me with basic testing info.
108 # How to Run Unit Tests
109
fa68e116 » wagenet
2012-03-07 Updated testing docs
110 ## Setup
111
a6e933e5 » Mike Andrzejewski
2012-05-14 Fix RVM website URL.
112 1. Install Ruby 1.9.2+. There are many resources on the web can help; one of the best is [rvm](https://rvm.io/).
231f4b16 » Gimi Liang
2011-05-31 Fix the 'How to Run Unit Tests' part in the README.md file. Fix issue #4
113
375f5a9b » ebryn
2011-12-10 Update readme with RakePipeline-based instructions.
114 2. Install Bundler: `gem install bundler`
231f4b16 » Gimi Liang
2011-05-31 Fix the 'How to Run Unit Tests' part in the README.md file. Fix issue #4
115
375f5a9b » ebryn
2011-12-10 Update readme with RakePipeline-based instructions.
116 3. Run `bundle` inside the project root to install the gem dependencies.
231f4b16 » Gimi Liang
2011-05-31 Fix the 'How to Run Unit Tests' part in the README.md file. Fix issue #4
117
fa68e116 » wagenet
2012-03-07 Updated testing docs
118 ## In Your Browser
119
120 1. To start the development server, run `rackup`.
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
121
fa68e116 » wagenet
2012-03-07 Updated testing docs
122 2. 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:
b96e4c22 » charlesjolley
2011-05-17 Add read me with basic testing info.
123
c0018e2e » wagenet
2011-12-12 Renamed files and updated a few more references
124 * [Ember.js Runtime](http://localhost:9292/tests/index.html?package=ember-runtime)
125 * [Ember.js Views](http://localhost:9292/tests/index.html?package=ember-views)
126 * [Ember.js Handlebars](http://localhost:9292/tests/index.html?package=ember-handlebars)
ed0487de » Tom Dale
2011-07-18 Update README for bpm
127
375f5a9b » ebryn
2011-12-10 Update readme with RakePipeline-based instructions.
128 To run multiple packages, you can separate them with commas. You can run all the tests using the `all` package:
ce15182c » Tom Dale
2011-06-22 Update README to do a better job of explaining what SproutCore is.
129
870cbbae » trevor
2012-03-14 small README changes
130 <http://localhost:9292/tests/index.html?package=all>
5fcedff6 » wagenet
2012-01-11 Updated dependencies and tests to jQuery 1.7.1
131
ba8f5e6f » trevor
2012-04-01 update readme
132 You can also pass `jquery=VERSION` in the test URL to test different versions of jQuery. Default is 1.7.2.
0f236a69 » wagenet
2012-02-02 Updated doc generation
133
fa68e116 » wagenet
2012-03-07 Updated testing docs
134 ## From the CLI
135
136 1. Install phantomjs from http://phantomjs.org
137
138 2. Run `rake test` to run a basic test suite or run `rake test[all]` to
139 run a more comprehensive suite.
140
141 3. (Mac OS X Only) Run `rake autotest` to automatically re-run tests
142 when any files are changed.
143
0f236a69 » wagenet
2012-02-02 Updated doc generation
144 # Building API Docs
145
870cbbae » trevor
2012-03-14 small README changes
146 The Ember.js API Docs provide a detailed collection of methods, classes, and viewable source code.
0f236a69 » wagenet
2012-02-02 Updated doc generation
147
870cbbae » trevor
2012-03-14 small README changes
148 NOTE: Requires node.js to generate.
0f236a69 » wagenet
2012-02-02 Updated doc generation
149
870cbbae » trevor
2012-03-14 small README changes
150 See <http://emberjs.com/> for annotated introductory documentation.
151
152 ## Preview API documenation
153
154 * run `rake docs:preview`
155
156 * The `docs:preview` task will build the documentation and make it available at <http://localhost:9292/index.html>
157
158
159 ## Build API documentation
160
161 * run `rake docs:build`
162
163 * HTML documentation is built in the `docs` directory
Something went wrong with that request. Please try again.