madhatted.com - Code

Content-Kit is now Mobiledoc Kit

2015-11-16T17:38:00Z

Today we’re releasing Mobiledoc Kit 0.6.0.

Previously, we’ve used the name Content-Kit Editor to describe this package. As we implemented the goals laid out in the post Content-Kit: Programmatic Editing, it became clear the codebase was diverging from being an editor in the sense that most users would expect it to be. For example, it no longer sports a toolbar or much UI.

Renaming the editor project “Mobiledoc Kit” achieves two goals:

The new name ties this package closer to the Mobiledoc format, which we think is the most significant differentiator of our efforts.
By naming the project a “kit”, we open the door to editors being implemented on top of Mobiledoc Kit. For example, we’re also releasing Ember Mobiledoc Editor 0.2.0 today. This editor has the toolbar and UX features you would expect from something calling itself an editor.

This release also coincides with the first large-scale rollout of Mobiledoc at Bustle’s new website Romper. Over 750 articles have been published, and dozens more a day are being written with a CMS based on Ember Mobiledoc Editor.

Since 0.4.0 in August, Mobiledoc and the kit have introduced several notable improvements. Let’s take a look.

Programmatic Editing

As proposed in the last blog post on Mobiledoc, we’ve implemented several editing APIs that allow consumers to modify posts and build custom user interfaces. We’ve also dropped nearly all UI from the Mobiledoc Kit project, and re-implemented most of it in the Ember Mobiledoc Editor

Several lifecycle hooks have been added to the editor, which allows toolbars and other custom UX to be implemented.

Ember Mobiledoc Editor

The Ember Mobiledoc Editor includes components for rendering an editor and customizing the UI. For example, this template would render an editor and toolbar:

{{#mobiledoc-editor mobiledoc=someDoc cards=(myCards) as |editor|}}
  {{#mobiledoc-section-button editor=editor for="h2"}}
    Headline
  {{/mobiledoc-section-button}}
  {{#mobiledoc-markup-button editor=editor for="strong"}}
    Bold
  {{/mobiledoc-markup-button}}
{{/mobiledoc-editor}}

Additionally, the Ember editor includes support for card display and editor modes being written as Ember components. This makes building new cards trivial, requiring very little knowledge of Mobiledoc Kit and zero knowledge of its internals.

Cut, Copy, Paste

Earlier versions of Mobiledoc Kit had limited or no support for pasting content. 0.6.0 adds battle-tested support for several scenarios:

Pasting between any two Mobiledoc Kit instances is supported for text and card content. For example given the “Selfie Card” demo at bustle.github.io/mobiledoc-kit/demo, you could snap a selfie, copy that part of the post, then paste it into any other kit instance supporting that card. The copying of a card payload is lossless, and the card is still editable.
Using the HTML output of Google Docs as a baseline, we’ve implemented support for pasting copied webpages into Mobiledoc Kit. Among the challenges for a complete pasting solution is how to handle non-text items. We’ve added hooks to the HTML parser that allow images to be converted into cards, and will work on making a public API for parser hooks in the next release. For now you can see the cardParsers option and calling code.
Copying from Mobiledoc Kit and pasting into any HTML parsing editor is also supported. The copied content is rendered specifically for that copy attempt, and, for example, will contain the display version of a card even if that card is in edit mode.

Better Card Cursors

In August, cursors in Mobiledoc Kit would skip over cards. Cards themselves had no before or after cursors. Amongst other limitations, this meant there was no way to have a cursor after a card that was the last section in a post.

0.6.0 improved cursor interaction with cards, making them behave much more like you would expect from any other editor. For example:

The “Image Card” demo at at bustle.github.io/mobiledoc-kit/demo is a good place to experiment with these changes.

Improved Webpack Support

We’ve seen some interest in Mobiledoc from webpack and React users. These tools expect our packaging to be slightly different than how we’ve been doing it so far.

Webpack is a build tool that supports modules imported via CommonJS. Mobiledoc Kit and the various renderers did not originally have CommonJS builds enabled, but they do now.

Webpack treats dependencies in NPM’s package.json file as dependencies for the browser. This means we cannot have any build-time dependencies listed in package.json, a strategy that is unfortunately incompatible with these packages being Ember addons. Consequently, we’ve spun out a separate addon for each of our renderers.

mobiledoc-dom-renderer and ember-mobiledoc-dom-renderer
mobiledoc-html-renderer and ember-mobiledoc-html-renderer
Finally we’ve introduced the mobiledoc-text-renderer and ember-mobiledoc-text-renderer, which we’re using for creating searchable versions of Mobiledoc posts for AWS ElasticSearch

More interest from webpack users is exciting, and we’re happy to better support their tooling.

Other Changes

Options for what kinds of markup can be created have been expanded to include underline, subscript, superscript, and strikethrough. Thanks to @vitosamson for this addition!

Card payloads can now be saved without toggling the card back to display mode. See Available hooks in the card documentation for more details.

For a more detailed summary of changes in the recent few releases, see the Mobiledoc Kit CHANGELOG.md.

What’s Coming

We have several projects underway today that are expected to land soon:

@rlivsey is working on support for “Atoms” in Mobiledoc and Mobiledoc Kit. This may be a breaking change in the Mobiledoc format, and necessitate a version bump and migration script for current Mobiledocs. You can follow his work on PR #226.
Parsing hooks must be formalized into a public API. We’re tracking this on Issue #229.
To mature and encourage a card ecosystem, we’ve begun an exploration of how to improve card packaging and card APIs. See Issue #228 for an in-depth discussion and some proposed changes.
We’ve regressed on support for IE, and are tracking progress to improve it in Issue #212.

Big thanks to Bustle Labs for continued sponsorship of our work on Mobiledoc. We’re having a great time with their smart and fun team here in NYC. Bustle is looking for senior software engineers and senior UX designers to join their crew.

Announcing Torii 0.6.0

2015-09-25T14:59:00Z

Torii is an authentication library for Ember.js. Much of the motivation behind Torii is introduced in this blog post from last summer. Unlike the popular Devise gem for Rails, Torii attempts to do little by default. Instead, it focuses on providing useful primitives and a conventional authentication lifecycle.

Over the past year Torii has grown popular. We’ve started to learn what patterns work across many apps and which ones should be avoided.

Torii 0.6.0, with amazing help from many contributors, formalizes several of these best practices into features. These include:

OAuth 2.0 state support, securing applications from CSRF attack
Exposing torii and the opt-in session support as Ember services
Adding a test helper for stubbing session state
Introducing support for flagging routes as “authenticated” in Ember’s router DSL

Lastly we’ve worked quite hard to ensure Torii 0.6.0 is still compatible with Ember.js 1.12, and supports all versions up to the current 2.1 betas without raising deprecations. This makes Torii 0.6.x a good version to use when migrating to Ember 2.x.

In Torii 0.7.0 we’re aiming to ship two big changes: Porting Torii into a traditional Ember-CLI addon (this will likely mean the removal of Torii’s “globals” mode support), and an iframe flow the provides an alternative to the popups we use for OAuth today.

But let’s take a look at these 0.6.0 features in detail.

OAuth 2.0 “state”

OAuth 2.0 recommends “state” to protect against CSRF attacks. Support for clients is optional, and the impact of CSRF varies from workflow to workflow in OAuth2. Some support from the provider is required, however many providers already support state.

The delightful @alisdair added transparent support for OAuth2 state to Torii in 0.6.0. This grants existing users improved protection against CSRF attacks on their authentication system. Current users of Torii only need to upgrade to 0.6.0, everything else is done by the library. See #217 for more details.

Using Ember Services

Torii is fairly “mature”, and by that I mean it predates some APIs we take for granted in Ember today. One of these is Ember’s excellent service and lazy dependency injection system. Before 0.6.0, accessing Torii or the opt-in session service from a component was clumsy at best.

In 0.6.0, simply use Ember.inject.service:

// app/components/open-facebook-auth.js
import Ember from 'ember';

export default Ember.Component.extend({
  torii: Ember.inject.service('torii'),
  click() {
    this.get('torii').open('facebook-oauth2').then((result) => {
      this.sendAction('didOpenAuth', result);
    });
  }
});

To opt-in to Torii’s session management, you must configure a service name via sessionServiceName in config/environment.js. That configured name, say “session”, is also available as a service name.

Please note that this change introduces a small breaking change in Torii: The torii:main factory has been renamed service:torii, and the configured session service name will also be prefixed by service:, for example service:session. Both services are still injected on routes and controllers, as in previous versions of Torii.

Thanks to @pzuraq for implementing this change.

New Testing Helper

Users of Torii’s opt-in session management need a way to stub authenticated states for testing. We still recommend mocking AJAX responses for testing sign-in and session restoration, however for testing unrelated features this is a slow and cumbersome method to mock signed-in state.

0.6.0 introduces test helpers for Torii, specifically stubValidSession. Thanks to our friend @jagthedrummer for implementing this.

Authenticated Route DSL

Ember’s nested routes present an ideal platform for flagging part of an app as requiring authentication. Usually this is done with a mixin, and toggling a flag on the route class. We’ve found that a difficult to use API. When first getting into a codebase, this important detail is buried.

Torii 0.6.0 features a powerful new way to require authentication for a route. For example, given a codebase opted-in to Torii’s session management:

// app/router.js
import Ember from 'ember';

Router.map(function(){
  this.route('about');
  this.route('sign-in');
  this.authenticatedRoute('dashboard', {}, function(){
    this.route('settings');
  });
});

When any route in this application is visited, checkLogin will be called on the application route with a default behavior of silently checking for a session named application. Attempts to access the dashboard without a session will trigger an accessDenied action on the route. Implementing accessDenied with an appropriate redirect is left to the developer.

Read more about this API in the Torii readme, and thanks to @tarasm for completing a tricky implementation process!

Content-Kit: Programmatic Editing

2015-08-25T14:03:00Z

Last month, I blogged about the initial release of Content-Kit. Content-Kit is a WYSIWYG editing library for the web, built with Bustle Labs. Instead of saving edited posts as HTML, Content-Kit saves posts as an easy-to-render Mobiledoc format. Since that post, we’ve been talking to some other parties interested in our early alpha-quality work.

Some of the feedback we got from developers looking into Content-Kit is:

The content they publish includes rich fragments that can take advantage of Mobiledoc’s cards API. This is often more important to them than real-time editing, for instance.
Their previous experiences with the quirks of Content Editable have made them eager to explore other alternatives.
They demand customization of the UI. Not only of button style and placement, but of inline experiences. One use-case was to allow Markdown-ish content entry (using ** to start bold markup), another was to display a drop-down of user handles when @ is entered.
At times, they want to limit how and what a user can edit in a post.

Our original suspicion was that Content-Kit needed to ship with an out-of-the-box ready-to-use UI in order to gain adoption. After these discussions it is clear no users are particularly excited about a stock user-interface, and most are very excited about increased programmatic control over the editor.

This marks a slight change in direction for Content-Kit. We plan to port much of the existing Content-Kit interface to an Ember Addon. Content-Kit itself should slowly lose UI features, and gain APIs for programmatic editing of a post.

Last week we started working with these new assumptions, and began fleshing out APIs. Let’s take a look.

Post Editing API

Content-Kit maintains a representation of the current post in what we call the “post abstract”. When a post changes, we need to re-render the editing surface and position the cursor correctly. For example, when a user hits “enter”, several operations to the post may take place. A few markers may be split, possibly some may be deleted, and a new section may be created.

Rendering speed is extremely important for an editing surface. We want to update the UI as quickly as the user taps a key. Fast typists hit about 325 characters per minute, which means a max render budget of 184ms to update the screen before rendering falls behind. To make the UX feel smooth, 100ms is a good target budget for most UI responsiveness. With editing and typing interfaces, we should likely be even faster.

Content-Kit must provide an editing API that allows flexibility, but flush the changed post abstract to DOM only once.

To do this, we have the user batch all editing operations in a run method. This in turn flushes work queues after any methods are called. For example, this code removes the section under the cursor and replaces it with a card section:

let {headSection: sectionWithCursor} = editor.cursor.offsets;
editor.run(postEditor => {
  let cardSection = editor.builder.createCardSection('fancy-card' {payload: 'data'});
  postEditor.insertSectionBefore(cardSection, sectionWithCursor.next);
  postEditor.removeSection(sectionWithCursor);
});

Note that only code mutating the post must use the postEditor and run method. Fetching cursor position, for example, is not a mutating call and thus can happen at any time.

Further initial documentation on the post editing API can be found in the README and editor/post.js file.

Content-Kit Lifecycle Hooks

Some kinds of UI require notification when the post abstract is changed, or when the editing surface is re-rendered. For example, to display a list of usernames after @ is typed the input to Content-Kit must be observed.

One strategy we considered was to punt this responsibility to native browser event handling. Force developers to respond to key and mouse events themselves when wrapping Content-Kit. However we think this approach would be error prone and likely cause poor performance if the resulting handler needed to call run to make its own updates.

In #84 we propose three lifecycle hooks:

didUpdatePost is called before post changes are rendered. This allows it to make changes with the postEditor, which it is passed, before rendering. You could use this hook to implement text commands, for example converting ** into a bold marker to emulate Markdown syntax.
willRender is called at the start of rendering, when the post is guaranteed updated but the DOM has not been changed.
didRender is called after rendering, when the post and DOM are synchronized.

For example, didRender could be used to silently save the post after each successful change:

1234	editor.didRender(() => { let mobiledoc = editor.serialize(); savePostDebounced(mobiledoc);});

These hooks will ship with Content-Kit this week. To accompany them, we also plan iteration APIs for sections and markers (and possibly the tree of the post abstract). These combined will provide a rich API to build features like validation on top of.

Disabling Input

Limiting what users may input into a post (what cards, what markup) can be achieved by limiting their UI options. Content-Kit will continue to push that concern to UI implementations, like the Ember Addon, and to API consumers.

However, Content-Kit must offer a way to suspend text editing capability itself to enable the strictest limitations on content. At Bustle, we’re using non-user-editable Content-Kit instances to organize content based entirely on cards.

In #82, two methods on the editor were introduced:

editor.disableInput() - disallow edits via the cursor
editor.enableInput() - resume standard text editing behaviors

Extracting the UI

Content-Kit currently offers a rough user interface largely modeled on the excellent work of medium. We’ve found that many developers are not interested in using the provided interface. Even with customization APIs, there was not enough flexibility to cover all use-cases.

The above APIs are intended to power external UI libraries wrapping Content-Kit.

With Bustle, we will be prototyping a new UI implementation based on Ember components.

A UI library based on Ember will be more customizable and flexible than what we could reasonably build in plain JavaScript
An Ember library will also allow cards to be implemented as Ember components, making new content experiences easier and faster to implement, as well as easily tested.
Building this library forces us to “dogfood” the public API for Content-Kit, making it more robust and well-considered.

An Ember Addon will be released in early September. We already have an internal prototype, and are using it to shape the public APIs in Content-Kit as we flesh it out.

Despite the selection of Ember for our improved Content-Kit UI, we encourage the use of Content-Kit with other interface frameworks. You can find us in the Gitter chat if you want to kick around ideas.

Big thanks to Bustle Labs for continued sponsorship of our work on Content-Kit. We’re having a great summer working with their smart and fun team here in NYC. Bustle is looking for senior software engineers and senior UX designers to join their crew.

Announcing Content-Kit and Mobiledoc

2015-07-31T15:53:00Z

Bustle Labs is the tech team behind the editorial staff at Bustle, a fantastic feminist and women’s interest site. Early last year they started work on a WYSIWYG editing surface called Content-Kit. 201 Created has been helping to bring Content-Kit to completion this summer.

Content-Kit is a completely new approach to post and article editing.

It makes limited use of Content Editable, the siren-song of doomed web editor technologies.
Content-Kit is designed for rich content. We call these sections of an article “cards,” and implementing a new one doesn’t require an understanding of Content-Kit internals. Adding a new card take an afternoon, not several days.
Posts are serialized to a JSON payload called Mobiledoc instead of to HTML. Mobiledoc can be rendered for the web, mobile web, or, in theory, on any platform. Mobiledoc is portable and fast.

You can try pre-1.0 Content-Kit right now, or check out the 100% MIT licensed Content-Kit source code. The Mobiledoc DOM renderer and Mobiledoc HTML renderer are available.

Let’s talk about Content-Kit and Mobiledoc, and what remains for them to hit 1.0.

Cards

The implementation details of Content-Kit, or any WYSIWYG editor, are incredibly interesting. But before diving into that discussion, I want to talk about the most important feature of Content-Kit and Mobiledoc.

Modern article or post content has moved beyond text. madhatted.com is pretty simple, but a post on Bustle, Verge, or the NYTimes could easily contain several different kinds of sections. For example:

A full-bleed image and title.
An introductory paragraph of text.
A chart providing context for the article.
Several paragraphs of text.
A slideshow of a few photographs.

Many web editors render the final version of this content into HTML when persisting. Consequently, adding new kinds of sections means wrestling with complex editor internals. Content-Kit’s cards API is designed to alleviate this burden.

Persisting a rendered version of an article also limits the post from being improved or rendered differently in another environment. For Bustle, there are three main rendering targets to consider. On each, we can support a different level of interactivity.

Desktop Web Mobile Web Mobile iOS

Full bleed image	Full bleed image	Full bleed image
Text as HTML	Text as HTML	Text as HTML (rendered in web view)
Interactive SVG Chart	Static SVG Chart	Image linking to full-screen native interactive
Inline slideshow	Image with a click opening a full-screen slideshow

Additionally, the implementation of a slideshow will change over time. Coupling the DOM to any particular version means painful data-migrations are needed for old content.

Content presentation that varies at runtime demands a new persistence format. We’ve created one named Mobiledoc.

Mobiledoc stores post or article content as data, not DOM. For example this Mobiledoc has a headline, chart, and body of text:

{
  version: "0.1",                          ---- Versioning information
  sections: [[],[
    [1, "h2", [                            ----
      [[], 0, "Understanding Content-Kit"]    | Text section wrapped in an h2
    ]],                                    ----
    [10, "slideshow", [                    ----
      "pic2.jpg",                             | Slideshow card, with an array
      "pic3.jpg"                              | payload of images
    ]],                                    ----
    [1, "p", [                             ----
      [[], 0, "What a nice, short post"]      | Text section wrapped in a p
    ]]                                     ----
  ]]
}

Importantly, Mobiledoc says nothing about how cards are edited or rendered. Instead, the editor or rendering runtime must be passed a handler conforming to the card API. For example, passing a slideshow display to the DOM renderer:

var SlideshowCard = {
  name: 'slideshow',
  display: {
    setup(element, options, env, payload) {
      var img = $('<img style="cursor:pointer">');
      var index = 0;
      img.
        attr('src', payload[index]).
        appendTo(element).
        click(function(){
          index++;
          if (!payload[index]) {
            index = 0;
          }
          img.attr('src', payload[index]);
        });
    }
  }
};

var renderer = new MobiledocDOMRenderer();
renderer.render(mobiledoc, $('.post')[0], cards: {
  slideshow: slideshow
});

Mobiledoc renderers require cards to expose a setup hook for display cases. Additionally, when a card is passed to an editor instance an edit hook must be fulfilled. There is an optional teardown hook, and the env object will include triggers to moving between edit and preview. One of these, save, accepts the argument of a data payload to be stored in the Mobiledoc. In our example above, this was the URLs array.

By allowing cards to be implemented at runtime, they can adapt or be swapped out to meet the needs of a given environment. By delegating only the editing and display logic to cards (not core parsing and rendering), Bustle developers can focus on building or enhancing the rich content tools they want to provide to the content team. They are liberated to create rich content experiences with Ember, React, or any other UI library that suits their needs.

We’re excited by the potential of cards and Mobiledoc. Combined with something like Ember or React components, adding new editing and rich display experiences is a snap.

Feel free to follow up by reading some example cards in our demo, the documentation on cards and mobiledoc specs, or continue on to learn about the design decisions behind Content-Kit and Mobiledoc.

Moving away from Content Editable

The pains and limits of using HTML5 Content Editable are well understood by developers building text editing interfaces. The best editing experiences (we love Atom from Github, and Google Docs) avoid Content Editable APIs entirely.

The difficult nature of Content Editable is that it conflates the previewed display of a document with its serialized and persisted form, using DOM for both. Often additional capability (runtime-defined behavior) is awkwardly embedded into DOM, or the natural flexibility of using the DOM to store content (including browser quirks and security issues) must be reined in.

To build a great editing experience, it is clear we need to limit how much Content Editable is used or, ideally, avoid it entirely. By capturing events before they reach the default Content Editable behaviors, Content-Kit currently takes a hybrid approach. In the upcoming weeks, we plan to migrate further away from reliance on Content Editable.

Content-Kit has an internal tree representing a document. The tree looks roughly like:

Posts correspond to an entire article or document. Sections represent top level data. For example, a headline tag would be a section, as would a paragraph tag. A card is also a section. Sections are ordered peers. Content-Kit has additional special section types that could likely become cards, but they also seem common enough to include as built-ins.

In the Content-Kit editing surface, each section has a matching DOM node. Markers do not map to single DOM node, but to a text node with opened and closed tags at its boundaries. Regardless of the depth of DOM nodes being represented by markers, they remain a shallow list.

Content-Kit maintains the mapping of text nodes to markers. When an event happens inside a given DOM node, we can trace which marker is being referenced (if any) by checking that map. With markers and DOM, a simplified graph of Content-Kit’s internal post looks like (white-space added for sanity):

There are three markers in the text section:

The first marker opens no tags, closes no tags, and has the text content of “A fantastic, “.
The second marker opens a bold and italic tag, closes the italic tag, and has the text of “reliable”.
The third marker opens no tags, closes the bold tag, and has the text “editor.”.

This structuring of markup is wonderfully efficient to render, and takes less space than the corresponding HTML for an article payload. For example, here is the same article as above persisted into Mobiledoc:

{
  version: "0.1",              ---- Versioning information
  sections: [[                 ----
    ["b"],                        |
    ["i"]                         | Markup types. Referenced by markers.
  ],[                          ----
    [1, "p", [                 ----
      [[], 0, "A fantastic, "]    | Markup section with a p tag. Markers
      [[0,1], 1, "reliable"],     | consist of a three markers.
      [[], 1, " editor."]         |
    ]]                         ----
  ]]
}

Content-Kit stills allows most text editing events to change the Content Editable DOM. During the input event, targeted subsets of the post content are re-parsed into the abstract post. In the future, keystrokes will be captured and the post can be updated directly, then rerendered. For some kinds of event data, like pressing the enter key, we already do this.

Content-Kit’s rendering system is directly inspired by the architecture of Ember’s Glimmer rendering engine. Render nodes are created during rendering, and manage the relationship of post content to the DOM. They track dirty state, allowing us to quickly render only the part of a post that has changed.

Getting to Content-Kit 1.0

We plan to bring Content-Kit to a 1.0 release in the next few weeks. This will mean the API for cards is stable, the UI is fairly polished and feature complete, and that we’ve integrated the editor into some internal Bustle tools.

The most painful parts of Content Editable will be avoided by 1.0, though we may retain it for very narrow functionality (entering text). Using event capture, making changes directly to the abstract tree and rerendering the post will replace most formatting commands.

Content-Kit is a flexible and powerful editor, and Mobiledoc paired with a generic cards API makes a great publishing tool. If you’re publishing for the web and interested in working with us to advance rich content, please say hello.

Big thanks to Bustle Labs for making Content-Kit and the related libraries open source. We’re having a great summer working with their smart and fun team here in NYC. Bustle is looking for senior software engineers and senior UX designers to join their crew.

Previewing Ember 2.0 on Canary

2015-05-14T00:17:00Z

Ember.js 2.0 is right around the corner. Lots of the discussion around 2.0 has focused rather narrowly on specific features, but there has been little reflection (since the RFC) on what 2.0 apps will look like as a whole. I definitely recommend you read Yehuda’s transition blog post though, as it really lays out the nitty gritty.

Meanwhile, Angular 2.0 is entering alpha this summer. You may have noticed several talks on how to write an Angular 2.0 app from scratch. Many of the active members of the Ember community maintain large 1.x applications, and thus we tend to focus less on “from scratch” and more on how to manage the migration forward.

Thinking about apps “from scratch” is still useful for existing users though. It reminds us where the framework is going, and why we invest time in upgrades and learning new APIs. It also helps us be better teachers to new users of the framework at work and in the community.

Ember.js Canary is not Ember 2.0, but it is already a significant departure from what an earlier 1.x app might have looked like. Let’s use it to get a preview of the Ember to come.

Using Ember-CLI with Canary

I’m going to quickly show you how to build an idiomatic app with Ember.js Canary. Canary is the cutting edge of Ember.js, and though it is not the “2.0” release it definitely a close approximation.

Ember-CLI is a fantastic tool, and has revolutionized how Ember applications are developed. Using Ember-CLI is, at this point, required for a modern Ember app. To install Ember-CLI:

You will need to install Node.js 0.12. I often use a tool called nvm on a new computer.
You will need to install NPM, the Node Package Manager. This should come with your Node.js installation. I’ve found that old versions of NPM can be problematic, and encourage you to make sure you are on a recent release by running npm install -g npm.
You should install or update your bower installation: npm install -g bower.

If you already have these tools, then you’re all set. Just run:

npm install -g ember-cli@0.2.5

Now we can create a new application with the command:

ember new todo-list

To approximate Ember 2.0, we need to install Ember.js Canary and enable a few feature flags. These are not steps a new developer would usually take, but bear with me. cd into the application directory, then install Ember.js and Ember-Data Canary:

bower install components/ember#canary components/ember-data#canary --save
# You may be prompted to resolve the version of Ember and/or Ember-Data.
# If so choose the one labelled "canary" and use "!". Usually you type
# "!1" and hit enter.

Feature flags are only available when using Ember Canary builds. Flags enable certain code-paths in the framework, often at load time. To approximate 2.0, we want to add these lines to config/environment.js:

// config/environment.js
module.exports = function(environment) {
  var ENV = {
    // ...
    EmberENV: {
      FEATURES: { // Here we enable some experimental features:
        'ember-routing-htmlbars-improved-actions': true,
        'ember-views-component-block-info': true,
        'ember-htmlbars-component-generation': true
      }
    },
    // ...
  };
  return ENV;
};

The full list of available experimental features can be found in the FEATURES.md and features.json file. You can read more about feature flags in the guides.

Lastly, we want to use the new “pods” directory layout for Ember apps. Edit the .ember-cli file and add the "usePods": true option:

// .ember-cli
{
  "disableAnalytics": false,
  "usePods": true
}

And with that, we’re ready to start coding. Boot up the Ember-CLI server with the following command:

ember serve

And visit http://localhost:4200. You should see “Welcome to Ember.js” in your browser.

Creating Routes and Links

We’re going to build the most boring app we could write. I’ll guide you through writing a very simple todos application, but if you’ve used Ember a simple app will let you focus on what the idiomatic style is for a new codebase. If you’re new to Ember, there is plenty to learn.

First we need a URL for our items (/items). Easy enough, Ember-CLI will generate the needed files for us:

ember generate route items

And we want to add a link to /items from the / page. To start, generate an index template:

ember generate template index

Index templates behave much like index.html files on a webserver: They are the default route (and template) served if you are not visiting a specific sub-route.

Edit the index template and add a link:

12	{{! app/index/template.hbs }}{{link-to 'Items' 'items'}}

If you reload the / URL in the browser, you will see a link to the “Items”. If you click the link, you will be taken to /items and the link will disappear. Ember pages are nested inside outlets, and if you open the app/templates/application.hbs file you will find an outlet helper there.

Changing the URL of an Ember application changes which route is mounted on an outlet. The index route is the default route for /, and thus is a sibling of the /items route. If you change the url from /items back to /, the app/index/template.hbs file will be loaded back into the outlet. As sibling routes, index and items will share the outlet. Only one can be rendered at a time.

Install the Ember Inspector (Chrome, Firefox). After installation, open the developer tools (command-option i) and click the “Ember” tab. Under “Routes” you can see the available routes and note that the bold one changes as you navigate.

The inspector is a fantastic debugging tool. If you click “$E” near any object, that object will be send to the console (as $E) where you can investigate its state.

Note: The “View Tree” section in the inspector is likely broken due to updates with Ember’s new Glimmer rendering engine. It should be fixed in the next release.

Using an Ember.js Addon and Defining an Ember-Data Model

To keep our todo list across page refreshes, we will need to store it somewhere. Ember-Data provides ways to save data to a server out of the box, but not to save data to IndexDB (or the alternatives). Thankfully, there is an addon that makes using Mozilla’s localForage library a breeze.

Addons are a little more than simply a library for your Ember application to use. They can add code to the application runtime, but can also add or change the build pipeline itself. For example, the compiler that turns Ember templates into JavaScript objects before sending them to the browser is itself an addon.

The addon we want is the ember-localforage-adapter. Installing it is easy:

ember install ember-localforage-adapter

After installation you must restart the ember serve server.

Next we will need to configure an adapter for the application. Adapters tell Ember-Data how to save model data after serialization (the process of converting a record into a payload for persistence). The “application” adapter is a special default adapter- it applies to any and all models we define.

Create an application adapter and export the localforage adapter:

ember generate adapter application

1234	// app/application/adapter.jsimport LFAdapter from 'ember-localforage-adapter/adapters/localforage';export default LFAdapter;

And next define the model for “item”:

ember generate model item

// app/item/model.js
import DS from 'ember-data';

export default DS.Model.extend({
  task: DS.attr('string'),
  isDone: DS.attr('boolean')
});

At this point, return to the inspector and click the “Data” section. Note that there is a model type of “item” now, although there are no records to be found. Later you can return to this section and see changes to the data.

Using Components and Actions

Most routes in an Ember application can be thought of as having a “subject”. This object represents the focus of the user’s interaction for that route. We call this subject the “model” of that route.

For the items page, our subject is a list of items. Edit the items route to return the items in our Ember-Data store:

// app/items/route.js
import Ember from "ember";

export default Ember.Route.extend({
  model() {
    return this.get('store').find('item');
  }
});

However we need to display the list. Additionally, we will want to input new tasks. To do this edit the items template:

{{! app/items/template.hbs }}
<div>
  <input-task on-enter={{action 'createTask'}} />
</div>
<ul>
  {{#each model as |item|}}
    <li>
      <input type="checkbox" checked={{item.isDone}} {{action 'toggleIsDone' item on="change"}}>
      <span>{{item.task}}</span>
    </li>
  {{/each}}
</ul>

There are three interesting bits to this template:

<input-task on-enter={{action 'createTask'}}>

This code calls an Ember component responsible for where new tasks are entered. When the user hits enter, the action “createTask” will be called. The code calling the action (the input task component) decides what arguments will be passed.

{{#each model as |item|}}

The each helper iterates over an array of entries. In this case, it iterates over the items returned from the model hook and yields the inner block of with the variable item. In Ember we call item or any other value between the | characters a block param.

<input checked={{item.isDone}} {{action 'toggleIsDone' item on="change"}}>

There are two curly sections on this this line. First, the property “checked” is bound to whatever item.isDone is. Second, the {{action helper attaches an event listener for change events on the input tag. For each event triggered, the toggleIsDone action will be called with the item passed as an argument.

In total, there are two actions used in this template. Lets write the handlers for these actions: createTask and toggleIsDone.

ember generate controller items

// app/items/controller.js
import Ember from "ember";

export default Ember.Controller.extend({
  actions: {
    createTask(task) {
      const item = this.get('store').createRecord('item', {
        task,
        isDone: false
      });
      item.save();
    },
    toggleIsDone(item) {
      item.toggleProperty('isDone');
      item.save();
    }
  }
});

Next lets implement the input-task component. Ember components are heavily inspired by the web component standards, but differ where we feel the specs are lacking. A great example of this is block params (the as |item| syntax). Nothing like block params exists for web components, but we find them supremely useful in real-world applications.

To create a component, start with the generator:

ember generate component input-task

We want to create an input tag, and when the user hits enter submit the task. Like most new parts of an Ember app, we should start with the template:

12	{{! app/components/input-task/template.hbs }}{{input value=value insert-newline=(action 'submit')}}

The component’s JavaScript must manage the value value, the submit action, and call the passed in createTask action when appropriate. Here is the implementation:

// app/components/input-task/component.js
import Ember from "ember";

export default Ember.Component.extend({
  tagName: '', // don't create a tag for this component
  actions: {
    submit(value) { // insert-newline is called with the input's value
      this.attrs['on-enter'](value); // call the on-enter action
      this.set('value', ''); // reset the input value
    }
  }
});

That should be everything wired up. Load up your browser and take a look. Note the changes to the data in the inspector, and that the records persist across page reloads.

Writing an Acceptance Test

The Ember community takes testing pretty seriously. As we’ve been generating different parts of the todo application, we’ve also generated tests. To run these tests with Chrome run this command:

ember test --launch Chrome

There is also a server option, and by default the test runner will try to use PhantomJS to run the suite without a browser booting. See ember test --help for details on those options.

The tests generated so far are all unit tests. Ember also supports acceptance tests. These allow you to test an application as driven by the user. To generate an acceptance test run:

ember generate acceptance-test items

And add our test to the generated file:

// tests/acceptance/items-test.js
import Ember from 'ember';
import {
  module,
  test
} from 'qunit';
import startApp from 'todo-list/tests/helpers/start-app';

const ENTER_KEYCODE = 13;
var application;

module('Acceptance: Todos', {
  beforeEach: function() {
    application = startApp();
  },

  afterEach: function() {
    Ember.run(application, 'destroy');
  }
});

test('visits /, navigates to items, adds an item', function(assert) {
  visit('/');
  click('a:contains(Items)');

  andThen(function() {
    assert.equal(currentURL(), '/items', 'url is correct');
  });

  fillIn('input[type=text]', 'New Task');
  keyEvent('input[type=text]', 'keyup', ENTER_KEYCODE);

  andThen(function() {
    const input = find('input[type=text]');
    assert.equal(input.val(), '', 'input has been reset');
    const task = find('span:contains(New Task)');
    assert.equal(task.length, 1, 'task is on the page');
  });
});

Ember’s acceptance test harness provides several “async helpers” such as visit, click and the form manipulations. The andThen helper allows us to ensure any asynchronous behavior such as fetching records from a persistence layer or animating the UI are complete before making assertions.

Where to Go Next

This small app touched a pretty wide expanse of Ember’s API. Some of the features we touched were cutting edge, but most are part of Ember.js 1.12. Here are some further resources on the topics covered:

Ember-CLI
- Getting Started
Ember Addons
Ember-CLI w/ pods
- Organize Your Ember App with Pods
- ember-cli docs
ES6 Modules
- in Ember-CLI
- detailed into to ES6 modules
Ember-Data
- guide
- ember-localforage-adapter
Routing
- guide
link-to helper
- guide
- docs
Ember Inspector
Actions
Components
- docs
- guide
Input helper
- guide
- docs
Async Test Helpers
- docs
- guide
- Demystifying Ember Async Testing blog post

We’ve also been able to build a pretty neat interaction in under 60 lines of code (+ under 40 in the test), and the result is a codebase no Ember developer should have trouble working with.

There are still a lot of details to work out for Ember 2.0, and you’re bound to hear lots of discussion about those topics in the next few weeks. Even short of landing those details, the ecosystem as a whole is incredibly improved. All these pieces working in harmony speaks to the diligence and continued effort from the community.

Whether you use Ember already or are looking at it for the first time, I hope this gave you some fresh perspective. Getting started with the framework has never been easier.

Ember Community Survey Results, 2015

2015-03-06T20:34:00Z

With over 900 responses, I’m very pleased to announce the results of the unofficial Ember.js Community Survey are now available:

201-created.com/ember-community-survey-2015

We’ve summarized the responses in about ten headlines, but I encourage readers to follow their curiosity with the full data-set linked at the bottom of the results page.

I would like to thank Brian Runnells (@ClimbingNarc) for his effort running this survey and engaging the community. It would not have been possible without his dedication and hard work.

Take a look! And thank you for participating!

Aligning Ember.js with Web Standards

2015-03-06T20:06:00Z

This March I was delighted to present at EmberConf 2015, after a great data-layer talk by Dan Gebhardt (@dgeb) and before a heartwarming community talk by Jamie White (@jgwhite).

My own presentation was on web standards- How they are changing, and what it means for Ember.js and Ember applications.

While researching for this talk, I used several excellent resources written and organized by other developers. If you are interested in learning more about ES2015 (ES6) features, the standards process, or JavaScript in general I highly suggest these links:

Alex Rauschmayer’s blog 2ality, especially:
The unofficial HTML version of the ECMAScript Language Specification
Rick Waldron’s (@rwaldron) notes from TC39 meetings
The TC39 Ecma262 repo, which contains a list of current ES proposals under discussion
The TC39 Process document
Not born to die, a blog post about Babel (formerly 6to5) by James Kyle (@thejameskyle)
What is a Polyfill? by Remy Sharp (@rem)
The ECMAScript compatibility table, including browser and transpiler implementations.

As with any talk about the current state of the world, parts of it quickly start becoming out of date.

I draw a pretty simplistic line between working groups and standards committees in my talk. For the point of narrative and understanding how we (the web) got here it is illustrative, but these are very rapidly changing organizations with intertwined and political relationships. I encourage you to review the meeting notes, charters, and process documents of a group if you want a good understanding of exactly what they bring to our complex, modern web.
As of ng-conf, it looks like several decorator/annotation proposals being discussed by TC39 may have been resolved. The syntax would be:

@attr('gearsCount')
@attr('wheelsCount')
class Car {
  constructor(gearsCount) {
    this.gearsCount = gearsCount;
  }

  @dependsOn('gearsCount')
  get isModern() {
    return this.gearsCount > 3;
  }
}

var car = new Car(3);
car.isModern; // false

Decorators before the class apply to the class, and before descriptors (properties) apply to the following property.

Emblem 0.5.0

2015-02-27T23:46:00Z

Emblem is an alternative Ember.js template syntax created by Alex Matchneer @machty. Due to some internal compiling to the Handlebars AST (abstract syntax tree), keeping Emblem up to date and backward compatible has been difficult. When Emblem was initially authored, the Handlebars AST was pitched as a stable API to write other applications against. This has not held up over time.

There is another path. With sponsorship from our friends at Vestorly and guidance from Alex, 201 Created set aside a few days to rewrite Emblem as a template printer. As a “printer”, Emblem no longer outputs compiled and executable templates. Instead, it generates Ember template strings. Since Ember template syntax is protected by semantic versioning, Emblem is now compatible with many versions of Ember regardless of the template engine (Handlebars 1.3, Handlebars 2.0, HTMLBars).

For example, an Emblem template used with Ember 1.10 will be built in these steps. First, the template:

/ app/templates/index.emblem
h1 Howdy Friend!

div
  marquee-banner | Emblem makes life easy!

Is compiled into an Ember template:

12	{{! app/templates/index.hbs }}<h1>Howdy Friend!</h1><div>{{#marquee-banner}}Emblem makes life easy!{{/marquee-banner}}</div>

This raw template is compiled by the build pipeline into an executable template. The printing step isolates Emblem from the Ember template compile step, allowing that to be based on whatever version of Ember the application uses.

We also gain a great new feature from this conversion: Developers considering Emblem, but intimidated by the risk of “lock-in” can rest easy. With a little bit of additional work into pretty-printing Emblem should soon have an easy off ramp for those wanting to return to a more traditional syntax: Just save the Ember templates!

Several issues remain open after this spike. We’ve opened a 0.5.1 Milestone to track them.

We’ve had a fascinating time implementing the new printer and we’re looking forward to sharing more details in a forthcoming blog post.

Upgrading to Emblem 0.5.0 with Ember-CLI

If you currently use Emblem and want to upgrade (say, for 1.10 support and HTMLBars? ;-), follow these steps:

Uninstall the broccoli-emblem-compiler or any other Emblem compiler you may be using.
Install the ember-cli-emblem-hbs-printer.

You can quickly install the printer with:

ember install:addon ember-cli-emblem-hbs-printer

That’s it! Your Emblem templates will be compiled like any other .hbs file in your codebase.

A demo application can be found at 201-created/ember-cli-emblem-example.

Many thanks to Vestorly for their sponsorship of 201 Created’s time on Emblem. If you’re a frontend developer looking for a new opportunity, Vestorly is tackling new and interesting Ember.js challenges every day. Check them out.

Ember Community Survey, 2015

2015-02-04T19:33:00Z

Update: We’re happy to announce that results of the 2015 survey are available!

The 2015 Community Survey closed on February 20th. Thank you for participating!

–

Calling all Ember users!

In 2014 Ember.js was a rapidly changing framework. The community and Ember Core Team tackled hard problems, many of which felt self-evident. We struck out in a new direction with Ember-CLI, created a bustling addon ecosystem, completed most of the grunt work on HTMLBars, and made huge strides in Ember-Data and API standardization.

As Ember gains adoption, we should take a moment to check our assumptions about who is using the framework and how. A little reflection on what happens in the wild can keep us honest and focused.

With this aim, I’m pleased to announce the unofficial Ember Community Survey!

Submit your Ember Community Survey answers here

Completing the survey should take about ten minutes. We will be accepting submissions until February 20th.

Please help us spread the word by sharing:

201-created.com/ember-community-survey-2015

on your social network feeds, at meetups, and around your office and other communities.

With your answers (all anonymous), we will create some visuals and write up our insights before EmberConf 2015 (March 3-4th). If you have any immediate questions, feel free to email us at survey@201-created.com.

Thanks to @climbingnarc for his continued help organizing this project with 201-created.com.

Ember Community Survey - 2015 Preview

2015-01-28T16:06:00Z

Update: We’re happy to announce that results of the 2015 survey are available!

Say hello to Brian Runnells (@climbingnarc). Brian is an Ember developer working with my consulting company 201 Created on a new project over February and March. He leads a double life as developer and rock climbing blogger. We’re lucky to be working with him, and happy to have him introduce the Ember Community Survey. -Matt

Who is currently developing applications with Ember.js?

What tools are those developers using to build their apps?

What kind of apps are they building?

2015 is an incredible time to be an Ember.js developer. Not only does the framework continue to gain momentum, but there are many features on the horizon. With this, however, comes many questions, like those above. So, when 201 Created began seeking people to help construct a survey for Ember developers, I was excited to take advantage of that opportunity.

Together, we have created a number of questions related to both your personal use of and professional work with Ember. Our goal is to ask the necessary questions about how and why developers are using Ember in order to better inform both the the community at large and the Ember Core Team. These responses will allow us to identify what is going well, where more work needs to be done, and what directions our community is moving in.

As the goal is to have results compiled by March’s EmberConf (tickets are sold out, but hope to see you there!), this survey will be finalized and put out for responses in early February. At this time, we are looking for any feedback you may have regarding the topics and questions we have produced thus far.

Find the survey questions here and share your feedback as a comment. Google provides some documentation about commenting that is good to review if you haven’t used the feature before. You can also contact us directly via survey@201-created.com.

Scalable Vector Ember

2014-11-24T16:23:00Z

Fresh from emberGarten in Toronto I bring you the latest on SVG in Ember.js, metal-views, and HTMLBars:

In Ember.js 1.8, we’ve added full support for SVG. This means you can author templates of SVG and make SVG-element components. Demo here, and code here. Zero graphic design skills were involved in the making of this demo, but you get the point!

SVG is slowly rising in usage as IE8 finally drops from the list of commonly supported browsers. To fully support SVG in Ember templates, 1.8 tackled a few tough challenges:

Switching namespaces and element creation methods. Ember transparently swaps into the SVG namespace, and even swaps back out to HTML for foreignObject tags.
Track contextual elements. In 1.8, each executed template is a string which must be converted into DOM with innerHTML. To properly support components and nested templates inside an SVG inline document, we’ve created a system to track the contextual (parent) element of a given template. This also helps us implement fixes for broken DOM APIs, and handle complex edge cases in the spec such as optionally omitted start tags (like tbody).

But the big story of metal views, and HTMLBars, is the slow migration of Ember from a string based rendering pipeline to a DOM based one.

pre-1.8 Ember templates returned strings, and the rendering pipeline assembled strings. This is akin to how a server-side framework would generate HTML.
In 1.8-1.9, Ember templates are strings individually converted to DOM, then folded into a DOM based rendering tree.
In 1.10+, Ember will introduce the DOM based HTMLBars templating engine. This completes our migration from string composition to DOM.

The nominal goals of this transition are to introduce new syntaxes (<li class="{{someClass}}">) and improve performance (less strings means less GC pressure).

DOM based rendering opens up an additional and less discussed frontier- That of interoperability with other DOM based rendering engines such as those in Angular, React, Mithril, and Polymer. None of these tools output strings, all expect to be attached to a DOM node and yield to a DOM node. By kicking HTML strings to the curb and embracing the DOM, we’ve created the possibility of using the best rendering strategy for a given part of an app.

SVG support is nothing more than a proving ground for how this kind of integration can work. Our next steps are to ship HTMLBars, then work on making Ember’s conventional path a competitively performing one for all common cases.

My Ember.js consulting firm 201 Created has helped 15+ companies get up to speed. We’re eager to work on SVG projects, and available for hire in January.

Contribute to Ember.js 2.0. No coding required.

2014-11-05T17:54:00Z

Ember’s path to a 2.0 release has been announced in an RFC. Our ambition is not simply to have 2.0 be a great framework, but for every 1.x codebase to make the transition forward with us.

There is a lot of code to be written. Contributing code to Ember.js, especially if you are new to open source development, is a rewarding and skills-building experience. The project maintains a high bar for technical contribution, and fixing a bug often involves a healthy dose of new knowledge. Additionally, there is a mature process for adding new features and bug fixes that should serve as an inspiration to your development process elsewhere.

If you have the time and will, adding code to Ember.js is an opportunity to collaborate with wonderful and extremely smart people.

“the time” is what keeps most developers from contributing to open source. There are businesses to build, families to raise, and always another Tolkien movie coming out.

But you don’t need to contribute code to help Ember.js reach its 2.0 goals. Here are five great ways to be a part of the process.

Test your app on beta releases

When opening a Github issue for a bug, it is important to note which channel of Ember.js the bug is in:

“canary” is the master branch of Ember.js. Every six weeks it forks to create the new Beta.
“beta” builds are released every week for six weeks, then graduate to release.
“release” builds are released every six weeks.

This cycle means that every six weeks, a release candidate of Ember.js is forked. Between the first beta release and the graduation of that release to release, we need feedback from real-world applications to discover bugs. We think of this process as a train. Beta forks, bug fixes land, and after six weeks that branch is release worthy.

While code is in beta, much of the coding community’s focus is there. If a bug is undiscovered in beta and graduates into release, fixing it takes time away from the new beta and canary branches. Bugs in release, and in point releases (like 1.7.1 or 1.8.1), make the train jerk around.

Testing your application with beta builds ensures quality releases on a steady schedule. Once or twice every six weeks, update to beta and report bad behavior on Github. With Ember-CLI this is as easy as:

bower install --save ember#beta

Or install a specific version:

bower install --save ember#1.9.0-beta.1

As part of installation you may be prompted by Bower to manually pick a specific version of Ember. After installation, you may need to restart your server. Like any change to bower dependencies, stay a little suspicious. Deleting the bower_components/ folder and doing a fresh bower install may be warranted.

You can also download builds from the website. Even ten minutes of beta review every six weeks is incredibly helpful. You don’t need to ship beta builds to production to generate meaningful feedback.

Catch and update old patterns in the documentation

As Ember.js 2.0 comes closer, more documentation at emberjs.com will be updated to match Ember-CLI’s conventions. Documentation has gone from a sore spot to a point of pride with Ember, but it is impossible for any single person to ensure all guides and API docs are up to date.

If you see something, PR something. The source of Ember’s guides (and the rest of the website) is on github. The API documentation is part of Ember’s own code. Making and previewing changes to the website is easy. Click the fork button, then start the preview server:

1234	git clone git@github.com:my-github-account/website.gitcd website/bundlebundle exec middleman

And you’re off! PRs for something as small as a grammar or spelling correction are welcome, but most valuable is catching old or non-idiomatic recommendations and updating them.

Talk about your own solutions

Each user of Ember solves unique challenges. Sharing your solution to an interesting problem is a valuable way to contribute to our community, be it through a blog post, meetup talk, or video. Getting your business or personal name out there is a bonus!

When writing about a topic for the first time, consider sharing your content on IRC or elsewhere for feedback. I’m always happy to review a post myself!

If you write or otherwise share something, make sure it gets out there for other developers to see. Consider submitting it to one of these Ember resources:

Ember Weekly is the oldest Ember.js newsletter, and reaches many developers.
Ember Watch maintains a Twitter account and webpage with many resources.

Or to any general JavaScript resource.

If you don’t have a place to publish, you can always consider posting at Ember’s active discourse forum.

Help others

Discourse, StackOverflow, and the IRC chatrooms are where new developers go to ask questions. Walking someone though an new concept, or triaging what might be a bug is a good way to welcome new users to the community. Getting bugs to Github and clarifying concepts is incredibly helpful, and gives new users a great introduction.

The community hangs in three chatrooms on IRC:

#emberjs is for general guidance, and it linked to from the Ember webpage.
#emberjs-dev is for internals discussion and more advanced topics.
#ember-cli is where contributors and maintainers of ember-cli tend to hang.

Share your thoughts on RFCs

Last but not least, and not for the rushed or faint of heart, is to review and comment on RFCs. Ember RFCs are documents prepared by the community and core team for discussion and feedback.

Feedback on an RFC should be specific, ideally taking into account your experiences with the problem addressed by the RFC. It should be researched and considered. We hope that discussion on RFCs moves a proposal forward until it is evident that it should be rejected or implemented, so “+1” comments should be avoided.

Understanding the issues raised by an RFC can be challenging and may not be a quick task, but it is important discussion that shapes the future of the framework.

I’m excited to do my part in making Ember’s 2.0 goals a reality. See you at EmberConf to celebrate!

Want to ensure your team is ready for 2.0? Or sponsor development to land features sooner? My consulting business 201 Created is looking for new projects this January!

Testing Ember.js Apps: Managing Dependencies

2014-08-29T11:50:00Z

Fresh via EmberFest:

Ember has an amazing testing story built upon the fundamentals of encapsulation and OO programming central to the framework. Despite this, every web application will be dependent upon and need to interact with native and network APIs that are hostile: Unreliable, slow, under-documented, and not to be trusted. The challenge in testing Ember applications lies with how to handle these external entities.

In this talk, we distinguish the domain of an application from its implementation dependencies. The dependency is contained such that it avoids leaking into application code, unit tests, and acceptance tests.

As a addendum exercise, lets consider how to wrap animation frames in a service that can be mocked.

First, consider a component that schedules the animation:

// in ember-cli, app/components/animate-in.js
App.AnimateInComponent = Ember.Component.extend({
  
  animateIn: function(){
    var element = this.$();
    var position = -100;
    element.css({
      'margin-left': ''+position+'px'
    });
    function animate(){
      position++;
      element.css('margin-left', ''+position+'px');  
      if (position !== 0) {
        window.requestAnimationFrame(animate);
      }
    }
    window.requestAnimationFrame(animate);
  }.on('didInsertElement', 'click')
  
});

Though functional, this component is leaking knowledge about a browser API (requestAnimationFrame) and is difficult to disable or isolate in tests. If in the animation a component property was modified, it might also require the addition of an explicit runloop.

Lets create a service to contain the request animation API and make it easier to mock in tests. A service in Ember.js has two parts, the service itself:

// in ember-cli, app/services/animation.js
App.AnimationService = Ember.Object.extend({
  init: function(){
    this.frames = [];
  },
  scheduleFrame: function(frame){
    this.frames.push(frame);
    Ember.run.scheduleOnce('afterRender', this, this.scheduleAnimationFrame);
  },
  scheduleAnimationFrame: function(){
    window.requestAnimationFrame(Ember.run.bind(this, this._animateFrame));
  },
  _animateFrame: function(){
    var framesLength = this.frames.length;
    while (framesLength--) {
      var frame = this.frames.shift();
      frame();
    }
    if (this.frames.length) {
      Ember.run.scheduleOnce('afterRender', this, this.scheduleAnimationFrame);
    }
  }
});

And an initializer. In this example, I’m using the globals style of Ember. In ember-cli this would look different (again, see the slides):

123	// in ember-cli, app/initializers/animation.jsApp.register('service:animation', App.AnimationService);App.inject('component', 'animation', 'service:animation');

And now the component itself can be refactored to use this service:

// in ember-cli, app/components/animate-in.js
App.AnimateInComponent = Ember.Component.extend({
  
  animateIn: function(){
    var element = this.$();
    var animation = this.animation;
    var position = -100;
    element.css({
      'margin-left': ''+position+'px'
    });
    function animate(){
      position++;
      element.css('margin-left', ''+position+'px');  
      if (position !== 0) {
        animation.scheduleFrame(animate);
      }
    }
    animation.scheduleFrame(animate);
  }.on('didInsertElement', 'click')
  
});

A unit test for this component could now easily assert that animation begins, without needing to reference the native requestAnimationFrame itself.

// in ember-cli, tests/components/animate-in-test.js
moduleForComponent('component:animate-in');

test('schedules an animation', function(){
  expect(1);
  var component = this.subject({
    scheduleFrame: function(){
      ok(true, 'animation was scheduled!');
    }
  });

  this.append();
});

Additionally, other components can now push frames to our service, conserving how many animation frames the browser needs to manage. This is a great example of how striving to move our technology dependency into a module apart from our domain code can improve the architecture of an application.

Try out the example codebase in this JSBin.

If you joined us in Barcelona, thank you for being part of a great Ember conference. Let me know if you have any thoughts or comments, and hope to see you again!

Authentication for Single Page Apps

2014-06-17T15:27:00Z

This week Vestorly, a client of my consulting partnership 201 Created, is sharing Torii.

Torii is a set of abstractions for handling authentication and session management in Ember.js applications. The name comes from a traditional Japanese gate whose design you likely recognize:

Let’s discuss how we build authentication for single page applications, and how we can build it better.

API based Authentication

People prefer the tools they know. Authentication can be a non-trivial challenge for any app, so most developers have tools and techniques they trust for building traditional (page-by-page) auth flows. When building a single page app, it is not surprising that they reach for those same server-side authentication solutions.

But those solutions fit poorly.

We want to see more applications expose authorization and authentication as first-class concepts via the API. In the case of authentication, especially when a user could sign in via any of several services, we’ve found “authorization objects” useful. These provide a first-class model that can be passed to other APIs, and simplify the client-side logic and error handling requirements.

Javascript applications can implement a clean, simple user experience for OAuth2 in the browser, one without user redirects or acrobatics to keep track of state.

Raise your hand if you’ve worked on a single page application (whatever the framework or anti-framework) that had an authentication flow like this:

This authentication system lives outside the JavaScript application entirely. The user-experience is choppy and slow, and the code difficult to maintain.

To improve this, make authentication a first-class part of your API and JavaScript application:

Pushing authorization and authentication concerns into the JavaScript app makes managing errors and state simpler. It makes refactoring code easier, results in a better user experience, and creates opportunities for composition.

When your application needs to authenticate against 3rd party services (Facebook, LinkedIn, Salesforce.com, Twitter etc.), splitting authorization and authentication into distinct API concerns becomes the best next step.

An RPC auth API

“Its OK @mixonic,” you may tweet, “we have a /session endpoint that accepts POST to create a session. We’re way ahead of you!”

Let’s take a look:

Auth API v1
POST /api/session	This API endpoint is responsible for creating a session. It accepts a username/password combination, and returns either a session object with an access token or an error that the credentials are incorrect.

Simple. If your application only supports username/password access, this may be sufficient. Let’s add support for social login:

Auth API v2
POST /api/session	This API endpoint is responsible for creating a session. It accepts a username/password combination, and attempts to authenticate that user. It returns either a session object and a `Set-Cookie` header, or returns an error that the credentials are incorrect.
GET /oauth2/facebookHandler	This endpoint accepts the redirect from Facebook as completion of an OAuth2 exchange. It validates the authorization code from Facebook, then authenticates that account as a user. It either redirects back to the application with a `Set-Cookie` header or renders an error into the page for the JavaScript application to read. The error might be regarding the invalidity of the OAuth2 exchange, or the invalidity of these credentials for signing in a user.

Uh oh. This has gotten messy.

There is one endpoint, /oauth2/facebookHandler, that is not part of the API proper. It is not in the /api namespace, and it doesn’t response like an API endpoint. Instead it uses redirects and rendering data into the page to push state into the browser.

The session logic has changed in two ways: First, we’re forced to use cookies for authentication, which adds overhead to all requests and is a less portable way to authorize requests. Second, the logic for creating a session is in two places.

These complications are why authentication and session management are often implemented as middleware. Middleware are filters for an HTTP stack. They get to handle all requests made to an application. Rack is an example of a middleware stack in Ruby, and Devise is an example of an authentication implementation using middleware.

The crafty developer might say “Ahha! I can create an API endpoint for handling the Facebook OAuth2 code, and signing in! It could be the same endpoint even! Thus I can avoid the overhead and complexity of middleware!”

Most OAuth2 flows are flexible enough to have all their user-interactive portions implemented in JavaScript. Facebook Connect is a good example of this. The crafty developer is crafty indeed.

Let’s see what she came up with:

Auth API v3

POST /api/session

This API endpoint is responsible for creating a session. It accepts a username/password combination, or an OAuth2 code and service name. If a username/password combination is submitted, it attempts to authenticat a user to match that account. If a code/service combination is submitted, it attempts to validate the code, then attempts to authenticate a user to match that account. It returns either a session object with an access token, or an error that the OAuth2 code is invalid, or an error that the user could not be authenticated.

This is where most apps end up. They meander into building a session API that is more like an RPC request than RESTful action. The inputs are inconsistent, the endpoint has the responsibility to do a large number of things (OAuth2 verification, username/password verification), and the possible error states are numerous.

But there is a way out.

A RESTful auth API

When an API endpoint becomes cluttered with too many responsibilities, it stops being expressive of a domain object. The URLs of an API (e.g., /api/session) should be expressive of a domain object (e.g., the “session”). RESTful API design allows domain objects to be composable. Composable objects can be combined to achieve the same ends as procedural API calls, and are flexible enough to meet other goals as well.

If the concept of “session” is cluttered, then the API is lacking. It fails to express “session” in a composable manner. By extracting a new domain object from the API, “session” can be repaired.

Let’s try an approach that separates authorization from session creation:

Auth API v4
POST /api/socialAuthorization	This API endpoint is responsible for creating a social authorization. It accepts an OAuth2 code and service name. It validates the code, and either returns a social authorization object or returns an error.
POST /api/session	This endpoint is responsible for creating a session. It accepts a username/password combination, or a social authorization object. It returns a session object, or an error that the credentials are incorrect.

The concerns of OAuth2 authorization and session creation are isolated. As a bonus, we have a social authorization object that can be passed not only to the session API, but also to other APIs. Consider the common scenario where an existing user wants to link his or her account to social accounts in order to make logins easier, or to enable some integration with their social networks:

Auth API v5
POST /api/socialAuthorization	This API endpoint is responsible for creating a social authorization. It accepts an OAuth2 code and service name. It validates the code, and either returns a social authorization object or returns an error.
POST /api/session	This endpoint is responsible for creating a session. It accepts a username/password combination or a social authorization object. It returns either a session object, or an error that the credentials are incorrect.
POST /api/me/connectedAccounts	This endpoint is responsible for connecting social accounts to an existing user account. It accepts a social authorization object, and returns either a connected account object or an error.

Note that the new endpoint accepts the social authorization object. The JavaScript client can take advantage of composability to combine these endpoints in novel ways. Handling errors at any single step of a complex interaction is trivial.

“But the crafty developer!” I hear you cry, “How was she handling OAuth2 without server-side redirects?!”

OAuth2 Without Redirects

A redirect endpoint (as in v2 of the API above) is not the ideal way to handle authorization for a couple of reasons:

JavaScript applications need to restore a special state when loading after the redirect.
A redirection-based interface isn’t portable to other API consumers.
It is slow and provides poor UX.

Thankfully, a popup can encapsulate OAuth exchanges without reloading the JavaScript application. OAuth2 can be consumed without a server-side redirect handler, and though OAuth 1.0 would requires a handler we can slim down its responsiblities and complexity.

Let’s re-imagine how to create authorization from Facebook’s OAuth2 API, using the “code” flow”:

After submitting credentials to Facebook, the browser is redirected to a page that loads the JavaScript application. The application stalls while loading, and submits the URL containing the authorization code back to the parent window.

This is where Torii comes in. For Ember.js applications, we’ve given you a way to build and consume these flows easily.

Authorization Objects and Torii

Torii encourages you to work with composable, RESTful APIs by isolating authorization (through providers) from authentication (through adapters).

Torii is composed of just three primitives, and just three possible actions.

Providers

In Torii, a provider is anything that can return authorization. For example, all of Facebook, Twitter, and my own API can be providers returning authorization. Furthermore, we talk about providers as specific authorization implementations. Both “Auth via Facebook Connect SDK” and “Auth via Facebook’s OAuth2 Authorization Code flow” are providers.

An idiomatic provider can execute only a single action:

open – create a new authorization

We’ve provided several ready-to-go providers, but writing your own should be easy. Additionally, though I don’t believe there are idiomatic usages for `fetch` and `close` on a provider, those actions are also supported.

Sessions

A session manager is responsible for maintaining the authentication state of a user. A session tracks if a user is authenticated or un-authenticated, and who the currently authenticated user is. The session knows nothing about how a user became authenticated, just whether or not they are currently authenticated.

The session manager can execute the following actions:

open – create a new session
fetch – retrieve and validate an existing session
close - destroy an existing session

Adapters

A Torii adapter maps the interface expected by the session manager onto your specific API.

We’ve chosen to leave the implementation of this to developers. Often Ember applications are built on existing APIs, and we believe the client-side code should be flexible enough to adapt to what exists.

Adapters can execute the following actions:

open – create a new session using an authorization
fetch – retrieve and validate an existing session
close – destroy an existing session

Providers in Torii are composable. They return authorization objects (often OAuth2 codes). Those objects could be passed to a connected account creation API, or to a session creation API. If you use the Torii session manager, they are passed to the adapter for your app, which can manage the exchange of authorization for a session object and/or current user.

Torii powers your JavaScript application’s session so that you only need to implement the exchange of an authorization object for a session object and current user. All the social authorization concerns stay out of your way.

Wrap up

Let me know how your API has solved the authentication challenge, and give Torii a look if your next project will be written in Ember.js.

Much thanks to @solirvine, @joeyAghion, @denik, and @fancyremarker for their time reviewing this post.

Update: Some discussion at Hacker News

Via EmberConf: Performance in Ember Apps

2014-03-28T21:43:00Z

Ember is fast. Ember Core is working hard to make Ember even faster. So why does your app drag?

The performance of a single-page app is impacted by the performance characteristics of its foundational parts: Network, Rendering, and JavaScript. Ember provides tools to manage these cornerstones, but with the tradeoff of introducing its own characteristics.

In this talk, we will use the source of real, shipped Ember apps (and of Ember itself) to diagnose, understand, and improve slow interactions. The Chrome developer tools will help us understand slow code paths and identify opportunities for improvement. Along the way, we will learn how parts of Ember work at the macro and micro level and learn how the framework helps us manage performance challenges in a browser environment.

At EmberConf, I spoke on web application performance and Ember.js. The message of this talk is that application performance is bigger than Ember performance. As authors of many of the more ambitious single-page web applications out there, we need to understand the tools and techniques used in analyzing and bettering the a user’s experience.

The slides above are accompanied by two live-coding sessions:

Debugging a janky animation, part #1 and part #2
Conserving property change notifications, part #1 and part #2
- Initial implementation of populating and displaying an array
- Optimized implementation

I also mentioned several tools in the slides and videos:

I used Google Chrome (stable, v33) on OSX for all my examples.
gfxCardStatus for pinning a mac to a specific graphics card
Slowy for emulating high-latency networks (alternatively Charles Proxy or Network Link Conditioner)

Additionally there are a few documentation resources I strongly encourage you to read:

The documentation for the Chrome developer tools, including:
How to use multiple Chrome users
Ilya Grigorik’s excellent Browser Networking book. I believe this can be read online, but if you are a professional developer the money will be well spent.
Iilya’s recent talk on Speed, Performance, and Human Perception

Let me know if you have feedback on the presentation, and thanks to those who attended. In such a short talk it would have been difficult to comprehensively cover all the possible performance hangups in an Ember application, so instead these slides focus on giving you a new and better understanding of the tools available for gathering data, analyzing issues, and asserting the success of a change. With some practice, you will be using them every day.

Thanks to everyone at EmberConf for a fantastic week!

Correction: setProperties does not cause observers to coalesce

In my presentation at EmberConf, I stated that setting multiple properties with setProperties would cause an observer to only fire once. This is incorrect. The observer will fire for each property changed. See an illustration of the behavior in this jsbin. Thanks to @krisselden for the catch.