Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 166 lines (104 sloc) 6.474 kb
ffef82e @pangratz add image of current travis ci build status
pangratz authored
1 # Ember.js [![Build Status](https://secure.travis-ci.org/emberjs/ember.js.png?branch=master)](http://travis-ci.org/emberjs/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
fb169cb @wagenet Added a note that binding resolution takes time
wagenet authored
30 // Later, after Ember has resolved bindings...
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
31 MyApp.country.get('presidentName');
32 // "Barack Obama"
33 ```
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
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
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
40 ``` javascript
41 MyApp.president = Ember.Object.create({
42 firstName: "Barack",
43 lastName: "Obama",
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
44
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
45 fullName: function() {
46 return this.get('firstName') + ' ' + this.get('lastName');
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
47
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
48 // Call this flag to mark the function as a property
49 }.property()
50 });
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
51
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
52 MyApp.president.get('fullName');
53 // "Barack Obama"
54 ```
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
55
56 Treating a function like a property is useful because they can work with bindings, just like any other property.
57
f813d13 @wycats Rename Amber to Ember
wycats authored
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:
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
59
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
60 ``` javascript
61 MyApp.president = Ember.Object.create({
62 firstName: "Barack",
63 lastName: "Obama",
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
64
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
65 fullName: function() {
66 return this.get('firstName') + ' ' + this.get('lastName');
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
67
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
68 // Tell Ember.js that this computed property depends on firstName
69 // and lastName
70 }.property('firstName', 'lastName')
71 });
72 ```
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
73
f813d13 @wycats Rename Amber to Ember
wycats authored
74 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
75
76 ## Auto-updating Templates
77
f813d13 @wycats Rename Amber to Ember
wycats authored
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:
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
79
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
80 ``` html
81 <script type="text/x-handlebars">
82 The President of the United States is {{MyApp.president.fullName}}.
83 </script>
84 ```
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
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
f813d13 @wycats Rename Amber to Ember
wycats authored
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.
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
89
90 # Getting Started
91
f813d13 @wycats Rename Amber to Ember
wycats authored
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.
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
93
f813d13 @wycats Rename Amber to Ember
wycats authored
94 # Building Ember.js
22df75f Vendor ruby dependencies to ease build process for those uncomfortable w...
tomhuda authored
95
f813d13 @wycats Rename Amber to Ember
wycats authored
96 NOTE: Due to the rename, these instructions may be in flux
97
98 1. Run `rake` to build Ember.js. Two builds will be placed in the `dist/` directory.
99 * `ember.js` and `ember.min.js` - unminified and minified
100 builds of Ember.js
22df75f Vendor ruby dependencies to ease build process for those uncomfortable w...
tomhuda authored
101
102 If you are building under Linux, you will need a JavaScript runtime for
103 minification. You can either install nodejs or `gem install
104 therubyracer`.
105
b96e4c2 @charlesjolley Add read me with basic testing info.
charlesjolley authored
106 # How to Run Unit Tests
107
fa68e11 @wagenet Updated testing docs
wagenet authored
108 ## Setup
109
a6e933e Fix RVM website URL.
Mike Andrzejewski authored
110 1. Install Ruby 1.9.2+. There are many resources on the web can help; one of the best is [rvm](https://rvm.io/).
231f4b1 Fix the 'How to Run Unit Tests' part in the README.md file. Fix issue #4...
Gimi Liang authored
111
375f5a9 @ebryn Update readme with RakePipeline-based instructions.
ebryn authored
112 2. Install Bundler: `gem install bundler`
231f4b1 Fix the 'How to Run Unit Tests' part in the README.md file. Fix issue #4...
Gimi Liang authored
113
375f5a9 @ebryn Update readme with RakePipeline-based instructions.
ebryn authored
114 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 #4...
Gimi Liang authored
115
fa68e11 @wagenet Updated testing docs
wagenet authored
116 ## In Your Browser
117
118 1. To start the development server, run `rackup`.
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
119
fa68e11 @wagenet Updated testing docs
wagenet authored
120 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:
b96e4c2 @charlesjolley Add read me with basic testing info.
charlesjolley authored
121
c0018e2 @wagenet Renamed files and updated a few more references
wagenet authored
122 * [Ember.js Runtime](http://localhost:9292/tests/index.html?package=ember-runtime)
123 * [Ember.js Views](http://localhost:9292/tests/index.html?package=ember-views)
124 * [Ember.js Handlebars](http://localhost:9292/tests/index.html?package=ember-handlebars)
ed0487d Update README for bpm
Tom Dale authored
125
375f5a9 @ebryn Update readme with RakePipeline-based instructions.
ebryn authored
126 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
127
870cbba @trevor small README changes
trevor authored
128 <http://localhost:9292/tests/index.html?package=all>
5fcedff @wagenet Updated dependencies and tests to jQuery 1.7.1
wagenet authored
129
ba8f5e6 @trevor update readme
trevor authored
130 You can also pass `jquery=VERSION` in the test URL to test different versions of jQuery. Default is 1.7.2.
0f236a6 @wagenet Updated doc generation
wagenet authored
131
fa68e11 @wagenet Updated testing docs
wagenet authored
132 ## From the CLI
133
134 1. Install phantomjs from http://phantomjs.org
135
136 2. Run `rake test` to run a basic test suite or run `rake test[all]` to
137 run a more comprehensive suite.
138
139 3. (Mac OS X Only) Run `rake autotest` to automatically re-run tests
140 when any files are changed.
141
0f236a6 @wagenet Updated doc generation
wagenet authored
142 # Building API Docs
143
870cbba @trevor small README changes
trevor authored
144 The Ember.js API Docs provide a detailed collection of methods, classes, and viewable source code.
0f236a6 @wagenet Updated doc generation
wagenet authored
145
870cbba @trevor small README changes
trevor authored
146 NOTE: Requires node.js to generate.
0f236a6 @wagenet Updated doc generation
wagenet authored
147
870cbba @trevor small README changes
trevor authored
148 See <http://emberjs.com/> for annotated introductory documentation.
149
150 ## Preview API documenation
151
0c0b720 @wagenet Update instructions for building API docs - Fixes #1398
wagenet authored
152 * Clone https://github.com/emberjs/website.git at the same level as the
153 main Ember repo.
870cbba @trevor small README changes
trevor authored
154
0c0b720 @wagenet Update instructions for building API docs - Fixes #1398
wagenet authored
155 * From the website repo, run `rake preview`
156
157 * The docs will be available at <http://localhost:4567/api>
870cbba @trevor small README changes
trevor authored
158
159
160 ## Build API documentation
161
0c0b720 @wagenet Update instructions for building API docs - Fixes #1398
wagenet authored
162 * From the website repo, run `rake build`
870cbba @trevor small README changes
trevor authored
163
0c0b720 @wagenet Update instructions for building API docs - Fixes #1398
wagenet authored
164 * The website, along with documentation will be built into the `build`
165 directory
Something went wrong with that request. Please try again.