Skip to content
This repository

Ember.js - A JavaScript framework for creating ambitious web applications

Merge pull request #4739 from machty/omg-query-params-are-done

[BUGFIX beta] Sync router.js, get rid of derelict async hook
latest commit b54cfff914
Alex Matchneer machty authored April 17, 2014
Octocat-spinner-32 benchmarks Get benchmarks running again, using external URLs December 22, 2013
Octocat-spinner-32 bin Update for publishing to bower with Travis. March 28, 2014
Octocat-spinner-32 docs [BUGFIX beta] Update the yuidoc paths to the new packages_es6 directory. April 10, 2014
Octocat-spinner-32 generators [DOC beta] Update copyright year. January 01, 2014
Octocat-spinner-32 lib Simplify rubygems version string. October 17, 2013
Octocat-spinner-32 packages [BUGFIX feature] Assert rootURL has trailing slash when used with Aut… April 14, 2014
Octocat-spinner-32 packages_es6 [BUGFIX beta] Sync router.js, get rid of derelict async hook April 17, 2014
Octocat-spinner-32 scripts Improved File Size script April 21, 2012
Octocat-spinner-32 tests Add automated testing for prod/min builds. January 30, 2014
Octocat-spinner-32 .gitignore [beta] Publish channel builds to bower. March 24, 2014
Octocat-spinner-32 .gitmodules Update gitsubmodules urls to public repos. January 07, 2013
Octocat-spinner-32 .jshintrc set esnext so es6 module syntax validates April 15, 2014
Octocat-spinner-32 .travis.yml [beta] Publish channel builds to bower. March 24, 2014
Octocat-spinner-32 Assetfile ES6 ember-handlebars & ember-handlebars-compiler: 4. March 17, 2014
Octocat-spinner-32 CHANGELOG.md Remove dup changelog entry. April 01, 2014
Octocat-spinner-32 CONTRIBUTING.md [DOC beta] Fixed some typos. March 05, 2014
Octocat-spinner-32 FEATURES.md [FEATURE ember-routing-inherits-parent-model] Remove feature flags. March 30, 2014
Octocat-spinner-32 Gemfile Support HANDLEBARS_PATH for Gemfile November 05, 2013
Octocat-spinner-32 Gemfile.lock Post release version bump. April 01, 2014
Octocat-spinner-32 LICENSE [DOC beta] Update copyright year. January 01, 2014
Octocat-spinner-32 README.md fix readme inconsistencies April 10, 2014
Octocat-spinner-32 Rakefile Ensure the correct key is used for fetching components/ember. March 28, 2014
Octocat-spinner-32 VERSION Post release version bump. April 01, 2014
Octocat-spinner-32 config.ru Remove bundled jQuery June 14, 2013
Octocat-spinner-32 ember-dev.yml Add automated testing for prod/min builds. January 30, 2014
Octocat-spinner-32 ember-source.gemspec [BUGFIX beta] Support Handlebars ~> 1.0. February 06, 2014
Octocat-spinner-32 ember.json Version bump - v1.0.0 August 31, 2013
Octocat-spinner-32 features.json [FEATURE ember-routing-inherits-parent-model] Remove feature flags. March 30, 2014
Octocat-spinner-32 package.json license type April 09, 2014
README.md

Ember.js Build Status Code Climate

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.

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

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

Bindings

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.

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 will always flow correctly from layer to layer.

Computed Properties

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

MyApp.President = Ember.Object.extend({
  firstName: 'Barack',
  lastName: 'Obama',

  fullName: function() {
    return this.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 with bindings, just like any other property.

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:

MyApp.President = Ember.Object.extend({
  firstName: 'Barack',
  lastName: 'Obama',

  fullName: function() {
    return this.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 update bindings that connect to a computed property.

Auto-updating Templates

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:

<script type="text/x-handlebars">
  The President of the United States is {{MyApp.president.fullName}}.
</script>

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.

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.

Getting Started

For new users, we recommend downloading the Ember.js Starter Kit, which includes everything you need to get started.

Building Ember.js

  1. Ensure that you have a recent Ruby (>= 1.9.3). There are many resources that can help; one of the best is rvm.
  2. Ensure that Bundler is installed (gem install bundler).
  3. Ensure that Node.js is installed.
  4. Run bundle install to install the necessary ruby gems.
  5. Run npm install.
  6. Run rake dist to build Ember.js. The builds will be placed in the dist/ directory.

Contribution

See CONTRIBUTING.md

How to Run Unit Tests

  1. Follow the setup steps listed above under Building Ember.js.

  2. To start the development server, run rackup.

  3. Then visit: http://localhost:9292/?package=PACKAGE_NAME. Replace PACKAGE_NAME with the name of the package you want to run. For example:

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

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

You can also pass jquery=VERSION in the test URL to test different versions of jQuery. Default is 1.9.0.

From the CLI

  1. Install phantomjs from http://phantomjs.org

  2. Run rake test to run a basic test suite or run rake test[all] to run a more comprehensive suite.

  3. (Mac OS X Only) Run rake ember:autotest to automatically re-run tests when any files are changed.

Building API Docs

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

NOTE: Requires node.js to generate.

See http://emberjs.com/ for annotated introductory documentation.

Setup Additional Repos

To preview or build the API documentation, you will need to setup the website and data repos in addition to this repo.

  • Clone https://github.com/emberjs/website.git at the same level as the main Ember repo.

  • Clone https://github.com/emberjs/data.git at the same level as the main Ember repo. Make sure to follow the setup steps in the Ember Data repo, which includes installing npm modules.

Preview API documentation

Build API documentation

  • From the website repo, run bundle exec rake build

  • The website, along with documentation will be built into the build directory

Something went wrong with that request. Please try again.