Repository files navigation

Ember.js is a JavaScript framework that does all of the heavy liftingthat you'd normally have to do by hand. There are tasks that are commonto every web app; Ember.js does those things for you, so you can focuson building killer features and UI.

These are the three features that make Ember.js a joy to use:

1. Bindings
2. Computed properties
3. Auto-updating templates

Use bindings to keep properties between two different objects in sync.You just declare a binding once, and Ember.js will make sure changes getpropagated in either direction.

Here's how you create a binding between two objects:

MyApp.president=Ember.Object.create({name:"Barack Obama"});MyApp.country=Ember.Object.create({// Ending a property with 'Binding' tells Ember.js to// create a binding to the presidentName property.presidentNameBinding:'MyApp.president.name'});// Later, after Ember has resolved bindings...MyApp.country.get('presidentName');// "Barack Obama"

Bindings allow you to architect your application using the MVC(Model-View-Controller) pattern, then rest easy knowing that data willalways flow correctly from layer to layer.

Computed properties allow you to treat a function like a property:

MyApp.President=Ember.Object.extend({firstName:"Barack",lastName:"Obama",fullName:function(){returnthis.get('firstName')+' '+this.get('lastName');// Call this flag to mark the function as a property}.property()});MyApp.president=MyApp.President.create();MyApp.president.get('fullName');// "Barack Obama"

Treating a function like a property is useful because they can work withbindings, just like any other property.

Many computed properties have dependencies on other properties. Forexample, in the above example, thefullName property depends onfirstName andlastName to determine its value. You can tell Ember.jsabout these dependencies like this:

MyApp.President=Ember.Object.extend({firstName:"Barack",lastName:"Obama",fullName:function(){returnthis.get('firstName')+' '+this.get('lastName');// Tell Ember.js that this computed property depends on firstName// and lastName}.property('firstName','lastName')});

Make sure you list these dependencies so Ember.js knows when to updatebindings that connect to a computed property.

Ember.js uses Handlebars, a semantic templating library. To take datafrom your JavaScript application and put it into the DOM, create a<script> tag and put it into your HTML, wherever you'd like the valueto appear:

<scripttype="text/x-handlebars">ThePresidentoftheUnitedStatesis{{MyApp.president.fullName}}.</script>

Here's the best part: templates are bindings-aware. That means that ifyou ever change the value of the property that you told us to display,we'll update it for you automatically. And because you've specifieddependencies, changes tothose properties are reflected as well.

Hopefully you can see how all three of these powerful tools worktogether: start with some primitive properties, then start building upmore sophisticated properties and their dependencies using computedproperties. Once you've described the data, you only have to sayhow it gets displayed once, and Ember.js takes care of the rest. Itdoesn't matter how the underlying data changes, whether from an XHRrequest or the user performing an action; your user interface alwaysstays up-to-date. This eliminates entire categories of edge cases thatdevelopers struggle with every day.

For new users, we recommend downloading theEmber.js StarterKit, which includeseverything you need to get started.

NOTE: Due to the rename, these instructions may be in flux

1. Runbundle install to fetch the necessary ruby gems.
2. Runrake dist to build Ember.js. Two builds will be placed in thedist/ directory.

• ember.js andember.min.js - unminified and minified builds of Ember.js

If you are building under Linux, you will need a JavaScript runtime forminification, for which we recommend installing nodejs. Alternativelyyou may have luck with another of the runtimes supported byexecjs.

SeeCONTRIBUTING.md

1. Install Ruby 1.9.3+. There are many resources on the web can help;one of the best isrvm.

2. Install Bundler:gem install bundler

3. Runbundle inside the project root to install the gem dependencies.

1. To start the development server, runrackup.

2. Then visit:http://localhost:9292/?package=PACKAGE_NAME. ReplacePACKAGE_NAME with the name of the package you want to run. Forexample:

• Ember.js Runtime
• Ember.js Views
• Ember.js Handlebars

To run multiple packages, you can separate them with commas. You can runall the tests using theall package:

http://localhost:9292/?package=all

You can also passjquery=VERSION in the test URL to test differentversions of jQuery. Default is 1.9.0.

1. Install phantomjs fromhttp://phantomjs.org

2. Runrake test to run a basic test suite or runrake test[all] torun a more comprehensive suite.

3. (Mac OS X Only) Runrake autotest to automatically re-run testswhen any files are changed.

The Ember.js API Docs provide a detailed collection of methods, classes,and viewable source code.

NOTE: Requires node.js to generate.

Seehttp://emberjs.com/ for annotated introductory documentation.

• Clonehttps://github.com/emberjs/website.git at the same level as themain Ember repo.

• From the website repo, runrake preview

• The docs will be available athttp://localhost:4567/api

• From the website repo, runrake build

• The website, along with documentation will be built into thebuilddirectory