Ember.js Tools & Resources 2 — Official Docs & Starter Kit

Documentation

Official docs (all on the website) include the API docs, the giant "documentation" page, and the guides. They are all inconsistent and out-of-date to varying degrees due to the rapidly-changing nature of the project. This will likely be addressed as part of the upcoming 1.0 release.

API Docs

http://emberjs.com/api/

The API docs currently featured on the website in the navbar are the "edge" docs, generated from the master branch of the repository.  As of this post, they were last generated 2012-09-13.

http://docs.emberjs.com/

These are the API docs generated from the latest "stable" release, 1.0-pre.

The docs are automatically generated from the inline documentation in the actual library files using YUIdoc. You can learn more about that by checking out the source for the Ember website.

The "Documentation" Page

http://emberjs.com/documentation/

The page linked to by the word "DOCS" in the website's navbar is a giant, monolithic, all-encompassing guide to Ember.js, including Handlebars but not Ember-Data.

Guides

http://emberjs.com/guides/

Each guide attempts to cover a specific topic in more detail. There are four linked from the main page so far:

• Ember MVC
• Understanding the Ember.js view layer
• Ember Application Structure
• Asynchronous Behavior in Ember

However, if you look at the source for the website, you'll find two more that are likely not linked to because they're not considered ready for public consumption:

• Ember Data Record Lifecycle
• Getting Started with Ember.js and Ruby on Rails

Handlebars.js

The docs for Handlebars.js are basically the home page of the website, with some additional bits found in the README.

Starter Kit

https://github.com/emberjs/starter-kit

The Starter Kit is basically the HTML5 Boilerplate template from initializr.com with a "Hello World" Ember.js app added to it, including local copies of all core libraries and dependencies.

Looking at the source (specifically index.html), I find a couple of interesting points worth noting...

Protocol-Relative URLs

Notice the lack of "http" or "https" at the front of this URL:

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js">
</script>

This is called a protocol-relative URL, meaning it will use whatever protocol (http or https) the page was loaded with, which avoids annoying browser warnings. Since learning about this technique in the process of studying Ember, I've started using it for all of my externally-linked resources.

Local Library Fallback

The line immediately following the jQuery script tag is this:

<script>
  window.jQuery ||
    document.write('<script src="js/libs/jquery-1.7.2.min.js"><\/script>')
</script>

This checks if the jQuery object is defined (which would be the case if the externally-hosted jQuery library had been loaded successfully), and if not, attempts to load the local version instead. Apparently, when you load a web page from your local filesystem (obvious from the "file:///" in your address bar), as a security precaution, browsers will not let the page fetch external javascript.

Next up: Community!