Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 167 lines (106 sloc) 6.408 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
025cf24 @wagenet Update README.md
wagenet authored
3 Ember.js 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
11 ## Bindings
12
f813d13 @wycats Rename Amber to Ember
wycats authored
13 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
14
15 Here's how you create a binding between two objects:
16
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
17 ```javascript
18 MyApp.president = Ember.Object.create({
19 name: "Barack Obama"
20 });
21
8618e23 @nwjsmith Fix mistake made in renamespacing
nwjsmith authored
22 MyApp.country = Ember.Object.create({
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
23 // Ending a property with 'Binding' tells Ember.js to
24 // create a binding to the presidentName property.
25 presidentNameBinding: 'MyApp.president.name'
26 });
27
fb169cb @wagenet Added a note that binding resolution takes time
wagenet authored
28 // Later, after Ember has resolved bindings...
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
29 MyApp.country.get('presidentName');
30 // "Barack Obama"
31 ```
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
32 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.
33
34 ## Computed Properties
35
36 Computed properties allow you to treat a function like a property:
37
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
38 ``` javascript
7c2151d @andyhmltn Edited the README.md to match the depreciation of computed properties…
andyhmltn authored
39 MyApp.President = Ember.Object.extend({
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
40 firstName: "Barack",
41 lastName: "Obama",
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
42
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
43 fullName: function() {
44 return this.get('firstName') + ' ' + this.get('lastName');
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
45
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
46 // Call this flag to mark the function as a property
47 }.property()
48 });
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
49
7c2151d @andyhmltn Edited the README.md to match the depreciation of computed properties…
andyhmltn authored
50 MyApp.president = MyApp.President.create();
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
7c2151d @andyhmltn Edited the README.md to match the depreciation of computed properties…
andyhmltn authored
60 MyApp.President = Ember.Object.extend({
e99d62c Resolve merge conflict to add syntax highlighting to readme
Tom Dale authored
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 # Building Ember.js
22df75f Vendor ruby dependencies to ease build process for those uncomfortabl…
tomhuda authored
94
f813d13 @wycats Rename Amber to Ember
wycats authored
95 NOTE: Due to the rename, these instructions may be in flux
96
c1fcf4f @scribu Add `bundle install` step
scribu authored
97 1. Run `bundle install` to fetch the necessary ruby gems.
98 2. Run `rake dist` to build Ember.js. Two builds will be placed in the `dist/` directory.
f813d13 @wycats Rename Amber to Ember
wycats authored
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 uncomfortabl…
tomhuda authored
101
102 If you are building under Linux, you will need a JavaScript runtime for
778f5a0 @regularfry Remove reference to therubyracer from README.md
regularfry authored
103 minification, for which we recommend installing nodejs. Alternatively
104 you may have luck with another of the runtimes supported by
105 [execjs](https://github.com/sstephenson/execjs).
22df75f Vendor ruby dependencies to ease build process for those uncomfortabl…
tomhuda authored
106
b96e4c2 @charlesjolley Add read me with basic testing info.
charlesjolley authored
107 # How to Run Unit Tests
108
fa68e11 @wagenet Updated testing docs
wagenet authored
109 ## Setup
110
a6e933e Fix RVM website URL.
Mike Andrzejewski authored
111 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…
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
fa68e11 @wagenet Updated testing docs
wagenet authored
117 ## In Your Browser
118
119 1. To start the development server, run `rackup`.
ce15182 Update README to do a better job of explaining what SproutCore is.
Tom Dale authored
120
fb1b0c1 @bradfol Update Readme unit test urls
bradfol authored
121 2. Then visit: `http://localhost:9292/?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
122
fb1b0c1 @bradfol Update Readme unit test urls
bradfol authored
123 * [Ember.js Runtime](http://localhost:9292/?package=ember-runtime)
124 * [Ember.js Views](http://localhost:9292/?package=ember-views)
125 * [Ember.js Handlebars](http://localhost:9292/?package=ember-handlebars)
ed0487d Update README for bpm
Tom Dale authored
126
375f5a9 @ebryn Update readme with RakePipeline-based instructions.
ebryn authored
127 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
128
fb1b0c1 @bradfol Update Readme unit test urls
bradfol authored
129 <http://localhost:9292/?package=all>
5fcedff @wagenet Updated dependencies and tests to jQuery 1.7.1
wagenet authored
130
f1d54fb @crofty Support jQuery 1.9.0
crofty authored
131 You can also pass `jquery=VERSION` in the test URL to test different versions of jQuery. Default is 1.9.0.
0f236a6 @wagenet Updated doc generation
wagenet authored
132
fa68e11 @wagenet Updated testing docs
wagenet authored
133 ## From the CLI
134
135 1. Install phantomjs from http://phantomjs.org
136
137 2. Run `rake test` to run a basic test suite or run `rake test[all]` to
138 run a more comprehensive suite.
139
140 3. (Mac OS X Only) Run `rake autotest` to automatically re-run tests
141 when any files are changed.
142
0f236a6 @wagenet Updated doc generation
wagenet authored
143 # Building API Docs
144
870cbba @trevor small README changes
trevor authored
145 The Ember.js API Docs provide a detailed collection of methods, classes, and viewable source code.
0f236a6 @wagenet Updated doc generation
wagenet authored
146
870cbba @trevor small README changes
trevor authored
147 NOTE: Requires node.js to generate.
0f236a6 @wagenet Updated doc generation
wagenet authored
148
870cbba @trevor small README changes
trevor authored
149 See <http://emberjs.com/> for annotated introductory documentation.
150
3caf403 @estoner README typo fix
estoner authored
151 ## Preview API documentation
870cbba @trevor small README changes
trevor authored
152
0c0b720 @wagenet Update instructions for building API docs - Fixes #1398
wagenet authored
153 * Clone https://github.com/emberjs/website.git at the same level as the
154 main Ember repo.
870cbba @trevor small README changes
trevor authored
155
0c0b720 @wagenet Update instructions for building API docs - Fixes #1398
wagenet authored
156 * From the website repo, run `rake preview`
157
158 * The docs will be available at <http://localhost:4567/api>
870cbba @trevor small README changes
trevor authored
159
160
161 ## Build API documentation
162
0c0b720 @wagenet Update instructions for building API docs - Fixes #1398
wagenet authored
163 * From the website repo, run `rake build`
870cbba @trevor small README changes
trevor authored
164
0c0b720 @wagenet Update instructions for building API docs - Fixes #1398
wagenet authored
165 * The website, along with documentation will be built into the `build`
166 directory
Something went wrong with that request. Please try again.