Skip to content
This repository
Newer
Older
100644 201 lines (141 sloc) 6.732 kb
b3875e61 »
2013-10-23 Add Code Climate badge
1 # Ember.js [![Build Status](https://secure.travis-ci.org/emberjs/ember.js.png?branch=master)](http://travis-ci.org/emberjs/ember.js) [![Code Climate](https://codeclimate.com/github/emberjs/ember.js.png)](https://codeclimate.com/github/emberjs/ember.js)
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
2
30ab887d »
2013-04-25 readme paragraph width (for readability)
3 Ember.js is a JavaScript framework that does all of the heavy lifting
4 that you'd normally have to do by hand. There are tasks that are common
5 to every web app; Ember.js does those things for you, so you can focus
6 on building killer features and UI.
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
7
f813d13a »
2011-12-12 Rename Amber to Ember
8 These are the three features that make Ember.js a joy to use:
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
9
10 1. Bindings
11 2. Computed properties
12 3. Auto-updating templates
13
14 ## Bindings
15
30ab887d »
2013-04-25 readme paragraph width (for readability)
16 Use bindings to keep properties between two different objects in sync.
17 You just declare a binding once, and Ember.js will make sure changes get
18 propagated in either direction.
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
19
20 Here's how you create a binding between two objects:
21
e99d62c6 »
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
22 ```javascript
23 MyApp.president = Ember.Object.create({
8bbcbed4 »
2014-04-10 fix readme inconsistencies
24 name: 'Barack Obama'
e99d62c6 »
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
25 });
26
8618e230 »
2011-12-13 Fix mistake made in renamespacing
27 MyApp.country = Ember.Object.create({
e99d62c6 »
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
28 // Ending a property with 'Binding' tells Ember.js to
29 // create a binding to the presidentName property.
30 presidentNameBinding: 'MyApp.president.name'
31 });
32
fb169cb1 »
2012-04-16 Added a note that binding resolution takes time
33 // Later, after Ember has resolved bindings...
e99d62c6 »
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
34 MyApp.country.get('presidentName');
8bbcbed4 »
2014-04-10 fix readme inconsistencies
35 // 'Barack Obama'
e99d62c6 »
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
36 ```
30ab887d »
2013-04-25 readme paragraph width (for readability)
37 Bindings allow you to architect your application using the MVC
38 (Model-View-Controller) pattern, then rest easy knowing that data will
39 always flow correctly from layer to layer.
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
40
41 ## Computed Properties
42
43 Computed properties allow you to treat a function like a property:
44
e99d62c6 »
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
45 ``` javascript
7c2151d1 »
2013-02-14 Edited the README.md to match the depreciation of computed properties…
46 MyApp.President = Ember.Object.extend({
8bbcbed4 »
2014-04-10 fix readme inconsistencies
47 firstName: 'Barack',
48 lastName: 'Obama',
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
49
e99d62c6 »
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
50 fullName: function() {
51 return this.get('firstName') + ' ' + this.get('lastName');
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
52
e99d62c6 »
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
53 // Call this flag to mark the function as a property
54 }.property()
55 });
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
56
7c2151d1 »
2013-02-14 Edited the README.md to match the depreciation of computed properties…
57 MyApp.president = MyApp.President.create();
e99d62c6 »
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
58 MyApp.president.get('fullName');
8bbcbed4 »
2014-04-10 fix readme inconsistencies
59 // 'Barack Obama'
e99d62c6 »
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
60 ```
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
61
30ab887d »
2013-04-25 readme paragraph width (for readability)
62 Treating a function like a property is useful because they can work with
63 bindings, just like any other property.
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
64
30ab887d »
2013-04-25 readme paragraph width (for readability)
65 Many computed properties have dependencies on other properties. For
66 example, in the above example, the `fullName` property depends on
67 `firstName` and `lastName` to determine its value. You can tell Ember.js
68 about these dependencies like this:
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
69
e99d62c6 »
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
70 ``` javascript
7c2151d1 »
2013-02-14 Edited the README.md to match the depreciation of computed properties…
71 MyApp.President = Ember.Object.extend({
8bbcbed4 »
2014-04-10 fix readme inconsistencies
72 firstName: 'Barack',
73 lastName: 'Obama',
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
74
e99d62c6 »
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
75 fullName: function() {
76 return this.get('firstName') + ' ' + this.get('lastName');
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
77
e99d62c6 »
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
78 // Tell Ember.js that this computed property depends on firstName
79 // and lastName
80 }.property('firstName', 'lastName')
81 });
82 ```
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
83
30ab887d »
2013-04-25 readme paragraph width (for readability)
84 Make sure you list these dependencies so Ember.js knows when to update
85 bindings that connect to a computed property.
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
86
87 ## Auto-updating Templates
88
30ab887d »
2013-04-25 readme paragraph width (for readability)
89 Ember.js uses Handlebars, a semantic templating library. To take data
90 from your JavaScript application and put it into the DOM, create a
91 `<script>` tag and put it into your HTML, wherever you'd like the value
92 to appear:
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
93
e99d62c6 »
2011-12-12 Resolve merge conflict to add syntax highlighting to readme
94 ``` html
95 <script type="text/x-handlebars">
96 The President of the United States is {{MyApp.president.fullName}}.
97 </script>
98 ```
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
99
30ab887d »
2013-04-25 readme paragraph width (for readability)
100 Here's the best part: templates are bindings-aware. That means that if
101 you ever change the value of the property that you told us to display,
102 we'll update it for you automatically. And because you've specified
103 dependencies, changes to *those* properties are reflected as well.
104
105 Hopefully you can see how all three of these powerful tools work
106 together: start with some primitive properties, then start building up
107 more sophisticated properties and their dependencies using computed
108 properties. Once you've described the data, you only have to say
109 how it gets displayed once, and Ember.js takes care of the rest. It
110 doesn't matter how the underlying data changes, whether from an XHR
111 request or the user performing an action; your user interface always
112 stays up-to-date. This eliminates entire categories of edge cases that
113 developers struggle with every day.
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
114
115 # Getting Started
116
30ab887d »
2013-04-25 readme paragraph width (for readability)
117 For new users, we recommend downloading the [Ember.js Starter
84858a10 »
2013-05-17 Fix downloads link for starter-kit
118 Kit](https://github.com/emberjs/starter-kit/tags), which includes
30ab887d »
2013-04-25 readme paragraph width (for readability)
119 everything you need to get started.
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
120
f813d13a »
2011-12-12 Rename Amber to Ember
121 # Building Ember.js
22df75f1 »
2011-07-13 Vendor ruby dependencies to ease build process for those uncomfortabl…
122
5f5c6740 »
2013-10-24 [DOC] Add defeatureify to instructions.
123 1. Ensure that you have a recent Ruby (>= 1.9.3). There are many resources that can help;
124 one of the best is [rvm](https://rvm.io/).
125 2. Ensure that [Bundler](http://bundler.io/) is installed (`gem install bundler`).
126 3. Ensure that [Node.js](http://nodejs.org/) is installed.
127 4. Run `bundle install` to install the necessary ruby gems.
43d342e7 »
2013-10-24 Use local npm packages for defeatureify.
128 5. Run `npm install`.
5f5c6740 »
2013-10-24 [DOC] Add defeatureify to instructions.
129 6. Run `rake dist` to build Ember.js. The builds will be placed in the `dist/` directory.
22df75f1 »
2011-07-13 Vendor ruby dependencies to ease build process for those uncomfortabl…
130
36199a83 »
2013-09-01 Contribution section added to README.md
131 # Contribution
132
5a3d1122 »
2013-09-20 Fix link to 'Contributing.md' to include file's name in README
133 [See `CONTRIBUTING.md`](https://github.com/emberjs/ember.js/blob/master/CONTRIBUTING.md)
36199a83 »
2013-09-01 Contribution section added to README.md
134
b96e4c22 »
2011-05-17 Add read me with basic testing info.
135 # How to Run Unit Tests
136
231f4b16 »
2011-05-31 Fix the 'How to Run Unit Tests' part in the README.md file. Fix issue #4
137
5f5c6740 »
2013-10-24 [DOC] Add defeatureify to instructions.
138 1. Follow the setup steps listed above under [Building Ember.js](#building-emberjs).
fa68e116 »
2012-03-07 Updated testing docs
139
5f5c6740 »
2013-10-24 [DOC] Add defeatureify to instructions.
140 2. To start the development server, run `rackup`.
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
141
5f5c6740 »
2013-10-24 [DOC] Add defeatureify to instructions.
142 3. Then visit: `http://localhost:9292/?package=PACKAGE_NAME`. Replace
30ab887d »
2013-04-25 readme paragraph width (for readability)
143 `PACKAGE_NAME` with the name of the package you want to run. For
144 example:
b96e4c22 »
2011-05-17 Add read me with basic testing info.
145
fb1b0c16 »
2013-02-17 Update Readme unit test urls
146 * [Ember.js Runtime](http://localhost:9292/?package=ember-runtime)
147 * [Ember.js Views](http://localhost:9292/?package=ember-views)
148 * [Ember.js Handlebars](http://localhost:9292/?package=ember-handlebars)
ed0487de »
2011-07-18 Update README for bpm
149
30ab887d »
2013-04-25 readme paragraph width (for readability)
150 To run multiple packages, you can separate them with commas. You can run
151 all the tests using the `all` package:
ce15182c »
2011-06-22 Update README to do a better job of explaining what SproutCore is.
152
fb1b0c16 »
2013-02-17 Update Readme unit test urls
153 <http://localhost:9292/?package=all>
5fcedff6 »
2012-01-11 Updated dependencies and tests to jQuery 1.7.1
154
30ab887d »
2013-04-25 readme paragraph width (for readability)
155 You can also pass `jquery=VERSION` in the test URL to test different
156 versions of jQuery. Default is 1.9.0.
0f236a69 »
2012-02-02 Updated doc generation
157
fa68e116 »
2012-03-07 Updated testing docs
158 ## From the CLI
159
160 1. Install phantomjs from http://phantomjs.org
161
162 2. Run `rake test` to run a basic test suite or run `rake test[all]` to
163 run a more comprehensive suite.
164
6da0c7da »
2013-11-19 [DOC] Fix instruction for running autotest.
165 3. (Mac OS X Only) Run `rake ember:autotest` to automatically re-run tests
fa68e116 »
2012-03-07 Updated testing docs
166 when any files are changed.
167
0f236a69 »
2012-02-02 Updated doc generation
168 # Building API Docs
169
30ab887d »
2013-04-25 readme paragraph width (for readability)
170 The Ember.js API Docs provide a detailed collection of methods, classes,
171 and viewable source code.
0f236a69 »
2012-02-02 Updated doc generation
172
870cbbae »
2012-03-14 small README changes
173 NOTE: Requires node.js to generate.
0f236a69 »
2012-02-02 Updated doc generation
174
870cbbae »
2012-03-14 small README changes
175 See <http://emberjs.com/> for annotated introductory documentation.
176
7dd314c3 »
2014-02-10 [DOC] Update steps in README to build API docs
177 ## Setup Additional Repos
178
179 To preview or build the API documentation, you will need to setup
180 the `website` and `data` repos in addition to this repo.
870cbbae »
2012-03-14 small README changes
181
7dd314c3 »
2014-02-10 [DOC] Update steps in README to build API docs
182 * Clone `https://github.com/emberjs/website.git` at the same level as the
0c0b720c »
2012-10-03 Update instructions for building API docs - Fixes #1398
183 main Ember repo.
870cbbae »
2012-03-14 small README changes
184
7dd314c3 »
2014-02-10 [DOC] Update steps in README to build API docs
185 * Clone `https://github.com/emberjs/data.git` at the same level as the main
186 Ember repo. Make sure to follow the setup steps in the Ember Data repo,
187 which includes installing npm modules.
0c0b720c »
2012-10-03 Update instructions for building API docs - Fixes #1398
188
7dd314c3 »
2014-02-10 [DOC] Update steps in README to build API docs
189 ## Preview API documentation
190
191 * From the website repo, run `bundle exec rake preview`
870cbbae »
2012-03-14 small README changes
192
7dd314c3 »
2014-02-10 [DOC] Update steps in README to build API docs
193 * The docs will be available at <http://localhost:4567/api>
870cbbae »
2012-03-14 small README changes
194
195 ## Build API documentation
196
7dd314c3 »
2014-02-10 [DOC] Update steps in README to build API docs
197 * From the website repo, run `bundle exec rake build`
870cbbae »
2012-03-14 small README changes
198
0c0b720c »
2012-10-03 Update instructions for building API docs - Fixes #1398
199 * The website, along with documentation will be built into the `build`
200 directory
Something went wrong with that request. Please try again.