Ceriously... The Blog of Cerebris

Ember.js 2019 Roadmap

2019-06-04T00:00:00Z

The soon-to-be-finalized Octane edition of Ember brings with it a number of modernizations and enhancements that make the framework feel lighter, more tightly tied to "The Platform", and simply more joyful to use. This next year presents a wonderful opportunity to double down on the progress from Octane and continue to modernize Ember itself and the apps we write with the framework.

This post is an answer to the Call for Blog Posts intended to inform Ember's 2019 Roadmap. As a member of the Framework Core Team, I feel that I have a particular responsibility to answer this call. My suggestion this year is to focus on modularity and packaging, both at the framework and application levels. Some aspects are technical, some are related to learning, and some are even related to marketing. All suggestions are made with ❤️ to help Ember continue its positive trajectory! 🚀

Framework Modularity and Packaging

Ember has long been perceived as an all-or-nothing framework, and there's no more obvious manifestation of this perception than the ember-source package. If there's a single change I'd like to see in Ember over the next year, it would be to stop shipping ember-source and move to multiple packages in the @ember scope. This would represent a firm commitment to the public modularization of Ember and allow us to deliver on the promise laid out in the 2017 EmberConf keynote to "npm install your way to Ember". Although, at this point, I would tweak that vision to "npm install Ember your way" so that it's clear that the starting and ending points can both be considered "Ember".

True Package Separation

Ember's JavaScript modules API was released in October 2017 as part of Ember.js 2.16. This release enabled us to stop accessing modules on the Ember global in favor of targeted, @ember-scoped modules, such as @ember/routing and @ember/service.

To take the example from the v2.16 blog post, your component modules could move from this v2.15 version:

  
  import Ember from "ember";

export default Ember.Component.extend({
  session: Ember.inject.service(),
  title: "The Curious Case"
});

To this v2.16 version:

  
  import Component from "@ember/component";
import { inject as service } from "@ember/service";

export default Component.extend({
  session: service(),
  title: "The Curious Case"
});

Even with this great leap forward in DX, these packages were not "true" packages published to npm. And this has not changed - they continue to be synthetic packages fully published in ember-source.

From the outside looking in, it may appear that it's a trivial move to take one more step and just break apart ember-source into packages, which are clearly already defined in a namespaced form. You may retain this belief after looking into Ember's source and seeing those packages already listed in the @ember namespace.

However, as you can probably suspect, there will be more to this process than meets the eye. Much of Ember's source remains in internal modules that represent cross-cutting or not fully factored concerns. Ideally, routing internals would be shipped together with @ember/routing and not contained in a massive @ember/-internals package (which has never been intended to be published as a package at all). The scope of the refactoring needed to do this right is why I believe this belongs on an annual roadmap rather than simply being a switch we can flip at a team meeting.

Let's delve into why I believe that true package separation will be worth the effort.

Align Learning with Packaging

Incremental adoption of capabilities provides an approachable path to learning that keeps control in the hands of the learner. Instead of diving (or being thrown) into the deep end, developers should be able to dip their toes into Ember, gradually acclimate, and then decide how much further they want to go.

Ember should be taught as a component-first framework that doesn't require routing, controllers, data, or much of anything else to get started.

I can easily imagine the guides incorporating this approach through phrases such as:

Routing is an important part of multi-page web applications. You can introduce routing into your Ember application by running: npm install @ember/routing.

The guides could go on to explain that installing @ember/routing will bring in other packages as dependencies, such as @ember/controllers. This will clarify the role of controllers as a bridge between routes and components. By teaching that Ember's core capabilities can be provided via core @ember-scoped packages, we are both telling and showing that Ember is modular.

Minimize Dependencies, Maximize Appeal

Historically, Ember has chosen to include capabilities by default that meet roughly 80% of the needs of web applications. However, if we apply this logic to every capability, there will be a further diminishing percentage for which this applies. After all, 80% x 80% x 80% x 80% < 50%.

Let's look at a couple examples.

While I strongly believe that Ember Data should be designed to meet the data needs of 80% of web applications, I don't think it should be included in the default blueprint. It would be much less surprising for developers new to Ember to begin using fetch and then "upgrade" to Ember Data when they feel the need.

Similarly, while I believe that Ember's router may meet the routing needs of well over 80% of web applications, I also don't believe that @ember/routing should be included in the default blueprint. But doesn't every "real app" need routing? I would say that's the kind of question that leads to selection bias and missed opportunities.

If we want to break the stereotype that Ember is only suitable for desktop applications with traditional routing needs that communicate primarily with REST APIs, then we should stop shipping a default blueprint that reflects that use case so well.

Experiments at Every Level

One of the benefits to package modularization is that it will open experiments at every layer of the framework.

Someone will build a lightweight router for simple widgets. Someone else will build a stack-based router driven by state pushed from the server (see Alex Matchneer's ember-rideshare thought experiment).

Wouldn't it be better to continue to add features into @ember/routing so that it can do it all? I certainly believe in the power of shared abstractions, but these take a long time to get right. And you can never figure out The Right Abstraction™️ based upon a sample size of one.

I need to be clear that there's no doubt that one of Ember's primary strengths are its strong conventions. I'm sure that I'm not the only one who enjoys the comfort and productivity that comes from being able to drop into any Ember app and find my way around without guidance. So I'm in no way proposing that we abandon the important tenet of "convention over configuration". Rather, I strongly believe that any fragmentations that appear in the community due to experimentation will be driven by divergences in actual needs. This has been proven out in the spaces that already support experimentation. Plenty of Ember developers use JSON:API, while many others use GraphQL. Ember developers work on desktop apps and mobile web apps, browser and native. We have a pretty big tent, and I think it will get bigger and better through more openness and experimentation.

The Pitch

I personally believe that the "batteries included" marketing pitch is a bit off. I'd prefer something that sounds less like we're sending you the kitchen sink whether you want it or not. In my opinion, a better pitch would emphasize that, between Ember's core packages and its ecosystem of addons, a massive matrix of capabilities is available to choose from depending upon your needs. Perhaps "Ember has an answer". Or "The composable framework".

Application Modularity and Packaging

I consider Ember's developer experience to be second-to-none. We are spoiled by Ember CLI, its generators, blueprints, test framework, and ecosystem of addons. Yet there are some aspects of building Ember applications that could no doubt be improved.

New File System

William Faulkner wrote that "In writing, you must kill all your darlings". And I would say that, in software, we are surprisingly gleeful about killing our own code. The reason for our glee is that we always believe we are replacing it with something better or (best of all) no code at all.

Thus, it is with a light heart that I bid adieau to Module Unification, an RFC that I toiled mightily upon after first joining the Core Team. The reasons I am untroubled by this are outlined by Tom Dale in his Update on Module Unification. Simply put, the acceptance of template imports removes swaths of use cases that drove the original RFC's design.

I believe that we now have the opportunity to shape a "New File Layout" that is simpler and clearer than the one proposed as Module Unification. Hopefully, we can take the best aspects of that design that are still relevant and move forward quickly. A shared project structure is one of Ember's strongest conventions, and I consider its evolution to be one of our highest priorities.

DI is Dead, Long Live DI

The role of dependency injection ("DI") in Ember did not also die with the introduction of template imports. Rather, we are trimming the sails and bit and not using DI where it is not needed. In other words, we should not add dynamic degrees of freedom in places where simple static dependencies will do. We've come to a pretty strong consensus that dynamism is not needed when resolving components and helpers, and in fact causes more harm than good.

I believe that DI remains a powerful tool for Ember that could be improved. I think the time is right to re-evaluate where and how it is used.

Embroider

Last but not least, this is undoubtedly the year of Embroider! 🎉

Ed Faulkner (no relation to William, AFAIK) has been working tirelessly on this modern rethink of Ember's build system. Embroider introduces a pipeline that includes a packaging step that can be fulfilled by any industry standard tool - Webpack, Rollup, or Parcel. This unlocks automatic npm imports, tree-shaking, and lazy-loading of segments of your application.

I'm thankful for all the modernizations and simplications Embroider will bring. Personally, I'm most looking forward to finally deleting all the custom build processing and lazy-loading code written for ember-engines.

Summary

Octane brought a number of massive ergonomic improvements to the day-to-day developer experience within individual modules, from Glimmer templates and components to native classes. Now it's time for us to focus on how we structure and bind and package those modules, both at the framework and application levels.

What's New in JSONAPI::Resources

2019-03-12T00:00:00Z

I haven't blogged about JSONAPI::Resources ("JR") since it was introduced over four years ago. Communication on our blog has unfortunately taken a backseat to many other objectives, including new features for JR, work on a soon-to-be-released product (why we started this in the first place), and consulting to keep the lights on. However, I'd like to get back to communicating here on a more regular basis.

Growth and maturity

Since JR's introduction both its capabilities and its community have grown substantially. Support for the major features of the JSON:API spec has been added over many releases. Customizing the behavior of resources has become cleaner. Adding callables to individual filters, sorts, and soon relationships has replaced overriding the core methods of the library, which has improved the clarity of code that defines resources. Another huge win was the addition of caching support in v0.9, which can make a big difference in performance for frequently requested resources. And, perhaps most importantly for me personally, JR is working well as the foundation for the backend of the product we're building.

New core team members

Sean Devine joined JR's core team in the very early days of the project. Sean's a long time contributor who's used JR to help build his construction logistics business, XBE.

Scott González just recently joined the core team. If you've ever had a question in our Gitter community, chances are that Scott was there to help you out. I'm really grateful to have Scott on the core team to help the project at a whole other level.

Improved documentation

We've added a documentation site where you can get updated on all the features that are now in the project. A Gitter community has been setup for chat and support. There you can usually get an answer quickly as there are multiple people watching the conversations and willing help out.

v0.10.0 is right around the corner

JR is now up to stable v0.9.5, with v0.10 currently in beta. Now seems like a good time to discuss what's coming in the v0.10 release and beyond.

Resource finders

The JSONAPI::Resource class was originally conceived as a thin layer on top of ActiveRecord models. JSONAPI::Resource would proxy down to the model for attributes, compose ActiveRecord::Relation expressions for resource searching and joins between resources over defined relationships. Some of the logic for how to perform these tasks was specific to models based on a SQL database which could use ActiveRecord::Relation. This resulted in a lot of ActiveRecord::Relation code in the JSONAPI::Resource class, which makes it difficult to back resources with ORMs other than ActiveRecord.

In v0.10 the functionality that interacts with the data stores has been abstracted into modules called resource finders. Resource finders work with the Processor to support finding resources while applying all the requested sorting, filtering, joining, and pagination.

ActiveRelationResourceFinder

As of this writing the only resource finder is the ActiveRelationResourceFinder. This is not a simply an extraction of the old resource code, but rather reworks the methods used to find resources and the related resources for a request. This resource finder approaches the finding of resources in several phases. The first phase searches for the identities and cache fields using pluck. This results in a very fast query to the database without instantiating model instances. When included resources are requested their identities are also found and added to a ResourceSet. The next phase, optionally, looks for already serialized resources from the cache and adds them to the resource set, avoiding instantiation and serialization of those models. Finally all remaining models are loaded by identity and serialized. By breaking the process into phases we gain efficiencies when communicating in bulk with the cache and with the database for each resource type, as well as minimizing model instantiation and serialization.

What's left for the beta period?

There's still a bit more to do before v0.10 is out of beta. Since support for additional resource finders is planned, we should allow resources with relationships to other resources that use different resource finders. For example, these relationships might reference a remote API server or even resources stored in a document database. A few changes to the existing codebase will be needed to make this possible.

What's next after v0.10.0? Sponsor a feature 🚀

Cerebris, which consists of just Dan and myself, has been self-funding the bulk of the development of JSONAPI::Resources since its inception. As you can probably imagine, this has been quite an undertaking for a two person firm, even with all the help from the other contributors (for which we are very grateful!). Frankly, we could use your help. It would be much appreciated if companies that are using JR could help out by sponsoring the development of new features. This would allow us to focus on the JSONAPI::Resources instead of consulting on completely separate projects. By allowing us to focus on this gem, you and the rest of the community can get useful new features more quickly, and you can focus on writing your own applications using JR.

We're still deciding what's coming next. Honestly, many of our decisions will depend upon funding. These are the features we're considering for upcoming releases:

Multiple operations

Supporting multiple operations per request is one of the most frequently requested features. Adding support for this in JR will first require finalizing support in the JSON:API spec. As one of the primary authors of the JSON:API spec, Dan is involved with shepherding the addition of multiple operation support into JSON:API. Once the feature is finalized in the spec, support can be added to JSONAPI::Resources. The exact details required are TBD based on the final form of the spec. However the foundations of JR were designed with multiple operations in mind.

Expanded filter types

JSONAPI::Resources supports basic filtering on relationships by ids and text filters with an exact match for fields. Custom filters can be used, but those require custom programming by the API authors. Built in support for common filtering concepts would be a big improvement.

For example making a text search case insensitive:

  
  class PostResource < JSONAPI::Resource
  attribute :title
  filter :title, case: :insensitive
end

Currently this requires a custom apply callable.

Profiles

Profiles have been added to JSON:API v1.1. Support for profiles in JSONAPI::Resources will require possibly significant changes. Beyond the obvious support for declaring and negotiating profiles, JR will also need to allow building custom profiles with unique capabilities. One example of this would be to allow the installation of different filtering profiles.

More resource finders

As alluded to above, JR could be extended to support additional resource finders. A prime candidate is a resource finder to support document databases such as MongoDB. Another possibility is a resource finder that proxies to another JSON:API server.

Custom features

If you have a custom feature in mind, please get in touch. As long as it's compliant with the JSON:API spec, we'll probably be glad to work with you to add support directly to JR. We're also open to working with you to build custom solutions that utilize JSONAPI::Resources to solve your business-specific needs.

JSON:API 1.0

2015-06-04T00:00:00Z

Yehuda Katz wrote the first draft of the JSON:API specification in May 2013 after hammering out the details in a long discussion with Steve Klabnik at RailsConf. JSON:API began as a codification of the shared expectations of a single server library for Rails, ActiveModel::Serializers, and a single JavaScript client library, Ember Data. (As a bit of prehistory, I gave a talk about these shared expectations at the first EmberCamp in February 2013).

Yehuda and Steve saw the value of separating these expectations into a formal specification that any client or server library could implement. Critically, the specification was encouraged to evolve in parallel, rather than in lockstep, with the original implementations. As a result, JSON:API has been influenced by developers both in and outside the original Ember and Rails communities from which it originated, which has undoubtedly resulted in a stronger spec with broader appeal.

After two years, four release candidates, hundreds of pull requests and issues, and countless hours of discussion, the JSON:API specification has finally reached 1.0.

It’s officially stable - we just tagged @jsonapi v1.0! So grateful for our community’s contributions and patience. https://t.co/fVWwmCl3y1
— Dan Gebhardt (@dgeb) May 29, 2015

Now that JSON:API is stable and committed to allowing only additive changes, it's poised to reach its full potential. At this unique time in the life of the specification, it seems appropriate to look both back at the journey to 1.0 and forward to the road ahead. But first a look at what makes JSON:API unique...

An Ambitious Specification

JSON:API is ambitious in purpose and scope: it defines both a media type (application/vnd.api+json) and rules for the usage of HTTP to fetch and modify resources represented by that media type. In this way JSON:API is similar to the Collection+JSON specification, but it has an even broader scope.

By standardizing so many of the decisions around designing and building an API, JSON:API allows developers to focus on the design of their applications.

Goals

So what kind of API will you build by following JSON:API? The spec states its goals in this way:

JSON:API is designed to minimize both the number of requests and the amount of data transmitted between clients and servers. This efficiency is achieved without compromising readability, flexibility, or discoverability.

These goals are apparent throughout the design of the spec. Features such as compound documents, sparse fieldsets, and multi-field sorting allow clients to request exactly the data they need from a server and nothing more.

For instance, let's imagine an API for a blog that exposes articles, comments, and people as resources. A client might make the following request:

  
  GET /articles?include=comments,author&fields[people]=first-name,last-name&sort=-date

The above request will fetch all articles as well as their associated comments and authors. People resources (authors in this case) will only be returned with their first and last names. The article collection will be sorted by date, most recent first. The server will either return all the results together in a single response document, or it may paginate them. JSON:API also specifies how pagination links must be returned so that any compliant client will understand them.

A Focus on Hypermedia

JSON:API has really benefited from Steve Klabnik's continued involvement. Steve is not only a standards junkie and hypermedia proponent - he is also literally writing the book on hypermedia APIs.

Thanks to Steve's influence, it's possible to build hypermedia APIs with JSON:API. Links can be added throughout JSON:API documents to specify canonical URLs for resources and their associated relationships. Clients can "crawl" links in an API just as your browser crawls links in HTML. By eliminating the need to hard-code URLs (or the logic to derive them), clients and servers become more loosely coupled and can more easily evolve.

Why JSON:API?

The Anti-Bikeshedding Weapon

JSON:API has gained entry to many organizations through its strong and consistent conventions that span almost every aspect of a "RESTful" API. Once a team starts to design an API, they often realize just how little guidance is provided by REST's constraints. Rather than bikeshedding for hours over minor API design details, many teams have turned to JSON:API for guidance.

The base JSON:API specification provides conventions for:

representing singular resources vs. resource collections
identifying resources, including heterogenous (mixed type) resources
including primary and related resources in a single compound document
representing relationships between resources
hypermedia links for resources, relationships, paginated collections, and more
fetching, creating, updating, and deleting resources and relationships
sparse fieldsets (i.e. limiting the fields included for each resource)
sorting resources
paginating primary and related resources
filtering resources
error statuses and data

The JSON:API site also provides recommendations that go beyond the scope of the base specification:

naming members
URL design
filtering strategies
supporting clients lacking PATCH

It's important to note that the base specification as well as the non-normative recommendations complement, and do not contradict, HTTP semantics.

A Thriving Ecosystem

While teams can immediately save time by adopting some of the hard-won conventions embodied by JSON:API, there are much broader and longer lasting benefits that can come from building a fully compliant API.

An ecosystem of JSON:API compliant libraries that span many languages and frameworks is actively being developed. Whether you're building a client or server, you should be able to lean on this ecosystem for assistance. Admittedly, many implementations are still works in progress, in no small part due to changes in JSON:API itself over the past two years. However, now that the spec has stabilized, it's exciting to see implementations come into compliance with 1.0.

The Journey to 1.0

From Draft to Guideline to Specification

JSON:API started its life as a draft with a pretty narrow focus. As it grew in scope, it tended to do so inclusively. Some areas of the spec became so flexible that the matrix of possible options became untenable to fully implement (e.g. URL vs. ID styles, keying primary data by data vs. resource type).

JSON:API gradually became a set of fluid guidelines for developing APIs that was not focused enough to be called a spec.

This "guideline phase" lasted for much of 2014. In retrospect, this period was truly invaluable because it allowed implementers to experiment and discover what worked and what didn't. When Yehuda and I sat down together to rewrite the spec fully in December 2014, we were able to "pave the cowpaths" by choosing the well trodden paths that were working for implementors. We replaced many SHOULDs with MUSTs. The resulting RC2 draft of the spec was much tighter in focus and actually came quite close to being tagged 1.0 in March.

Polishing 1.0

As tempting as it was at the time, it's a good thing that we didn't abruptly release RC2 as JSON:API 1.0. Instead, we decided to give implementations a chance to catch up and test the new spec as a whole. We realized that there were a number of implementations already committed to compliance with the spec and that they needed more time to thoroughly vet its new incarnation.

Two core contributors, Tyler Kellen and myself, have been actively developing compliant libraries. Tyler and his colleagues at Bocoup have been building Endpoints for Node. At Cerebris, Larry and I have been working on a server implementation for Rails, JSONAPI::Resources, as well as a client implementation in JavaScript, Orbit.js. During the final RC3 / RC4 phase, we all pushed to keep these libraries compliant with the spec to validate any changes.

This final phase, perhaps more than any other, was truly a community effort. I'm especially grateful for the contributions of Ethan Resnick, Kalle Tuure, hhware, Ward van Teijlingen, and Christoph Ziegenberg. They all really stepped up in the final months to raise issues and submit pull requests to ensure that JSON:API 1.0 was solid and would be extensible post-1.0. I also really, really appreciate all the time and effort that Tyler invested to help polish the final version of the spec.

I'm so proud of, and grateful to, the JSON:API community for working together so well on difficult problems that have historically been the source of so many arguments. Thanks to you all for making 1.0 happen!

JSON:API 1.0+

I'm looking forward to seeing JSON:API reach its full potential as its ecosystem matures. It shouldn't be long before 1.0 compliant implementations are available for most popular languages and frameworks. I'm also optimistic that compliance testing tools will soon be developed to help validate implementations.

In a nice bit of symmetry, Ember Data is coming full circle to embrace JSON:API like never before. Ember Data's JSON:API adapter and serializer are nearing full compliance. These layers will be very lean since the JSON:API format is also going to be used internally for normalized data. These changes should land with Ember Data 1.0.

With its extensible structure, the spec itself is also poised to evolve in interesting (and non-breaking) ways post-1.0.

For example, I expect that JSON:API will gain further hypermedia capabilities as the concept of links is extended.

Another exciting possibility that we've explored are extensions. Although still experimental, extensions should allow clients and servers to negotiate for the support of features not included in the base spec. One such extension we've explored allows for bulk operations to be performed in a single request.

In short, JSON:API 1.0 is just the beginning. It's a great time to get involved with this project.

If you're interested in learning more about JSON:API, please check out the spec at jsonapi.org.

If you have any questions or suggestions, please file an issue on JSON:API's Github repo.

And if you have any questions for me, please comment below.

Introducing JSONAPI::Resources

2014-08-22T00:00:00Z

It's been a long time coming, but the JSON:API spec is nearing a 1.0 release. Dan and I have been actively involved in helping to form this spec, which appeals to us because it is so ambitious and comprehensive. JSON:API goes beyond specifying a format for JSON payloads - it also specifies how data should be fetched and modified. By standardizing so many of the decisions around designing and building an API, JSON:API allows developers to focus on the design of their applications. As JSON:API catches on, we'll all benefit from the standardized tooling that develops for both clients and servers.

Our initial contribution to this tooling is JSONAPI::Resources, or "JR". JR is a gem that allows Rails apps to easily support the JSON:API spec. As you may have guessed from the name, JR is resource-centric. You define resources for your application and JR can automatically fulfill requests to fetch and modify them. JR not only handles the serialization of responses, but also provides controllers that support methods to interact with the resource. By declaring resource relationships you can allow related resources to be retrieved in compound documents, and by specifying resource attributes you can control how the resource is represented to the API client.

Until now, we've been using (and recommending and contributing toward) ActiveModel::Serializers, or "AMS", the Ruby library that has come closest to fulfilling the JSON:API spec. There are a couple reasons that we developed JR instead of continuing to work with AMS. First of all, AMS is not strictly focused on JSON:API, and has been out of compliance for some time. This is not a major hurdle and could be easily overcome by enabling a JSON:API mode in AMS, something which is already under discussion. The primary reason we developed JR is that AMS is focused on serializers and not resources. While serializers are just concerned with the representation of a model, resources can also act as a proxy to a backing model. In this way, JR can assist with fetching and modifying resources, and can therefore handle all aspects of JSON:API.

Components

Let's take a quick look at the major components of JSONAPI::Resources.

Resource

You can define the resources available through your API as subclasses of JSONAPI::Resource. A resource definition looks very similar to the definition of a serializer in AMS. Resources form the core of JR and are used by many of its components.

Let's say we're building a blog. Here's a simple resource definition for posts:

  
  require 'json/api/resource'

class PostResource < JSONAPI::Resource
  attributes :id, :title, :body

  has_one :author
end

And here's a corresponding author:

  
  class AuthorResource < JSONAPI::Resource
  attributes :id, :name

  has_many :posts
end

All declared attributes can, by default, be accessed through the API. There are also methods on a resource that you can implement to control which of the attributes are creatable, updateable, and fetchable. Any attribute on the underlying object that isn't declared in the resource definition will not be available through the resource.

Relationships support options to set different class names and keys from the resource names. In addition, a relationship can be treated "as a set" for create and update purposes.

In the following example, tags are defined with the acts_as_set option. This allows a collection of tags to be set on a post that will replace all of its existing tags:

  
  class PostResource < JSONAPI::Resource
  attribute :id
  attribute :title
  attribute :body
  attribute :subject

  has_one :author, class_name: 'Person'
  has_one :section
  has_many :tags, acts_as_set: true
  has_many :comments

  def subject
    @object.title
  end

  def self.updateable(keys, context)
    super(keys - [:author, :subject])
  end

  def self.createable(keys, context)
    super(keys - [:subject])
  end

  filters :title, :author
  filter :id
end

Also note that the above resource has a computed attribute called subject. This is simply the title of the post, and is not createable or updateable.

A resource also controls which filters its corresponding ResourceController will support. The Resource class provides basic search capabilities, but if you need more control you can implement a find method on your resource.

ResourceSerializer

A ResourceSerializer can serialize a resource into a JSON:API compliant hash, which can then be converted to JSON. ResourceSerializer has a serialize method that takes a resource instance to serialize, and optional fields, includes, and context parameters.

For example:

  
  post = Post.find(1)
JSONAPI::ResourceSerializer.new.serialize(PostResource.new(post))

This returns a hash like this:

  
  {
  posts: [{
    id: 1,
    title: 'New post',
    body: 'A body!!!',
    links: {
      section: nil,
      author: 1,
      tags: [1,2,3],
      comments: [1,2]
    }
  }]
}

You can also provide some options and filter the fields and include related records. include takes an array of related resources to serialize, and fields takes a hash of resource types to an array of attributes. For example:

  
  post = Post.find(1)
JSONAPI::ResourceSerializer.new.serialize(PostResource.new(post),
  ['comments','author','comments.tags','author.posts'],
  {people: [:id, :email, :comments],
   posts: [:id, :title, :author],
   tags: [:name],
   comments: [:id, :body, :post]})

This outputs:

  
  {
  :posts=>[
    {:id=>1,
     :title=>"New post",
     :links=>{:author=>1}}
    ],
    :linked=>{
      :posts=>[
        {:id=>2, :title=>"JR solves your serialization woes!", :links=>{:author=>1}}
      ],
      :people=>[
        {:id=>1, :email=>"joe@xyz.fake", :links=>{:comments=>[1]}}
      ],
      :tags=>[
        {:name=>"whiny"}, {:name=>"short"}, {:name=>"happy"}
      ],
      :comments=>[
        {:id=>1, :body=>"what a dumb post", :links=>{:post=>1}},
        {:id=>2, :body=>"i liked it", :links=>{:post=>1}}
      ]
    }
}

Note that multilevel includes can be specified with a dot notation, like 'author.posts'. In addition, you can control the fields for each resource type.

ResourceController

The ResourceController class provides index, show, create, update, delete, show_association, create_association, and destroy_association methods that function based on the resource definition matching the controller name. The easiest way to use ResourceController is to derive your ApplicationController from it, and in turn derive specific controllers from your ApplicationController. There is no need for any methods to exist in your individual controllers unless you need to alter the default behavior.

  
  class ApplicationController < JSONAPI::ResourceController
end

class ContactsController < ApplicationController
end

The ResourceController translates the includes and fields parameters from the JSON:API specified style into the internal structures used by the ResourceSerializer.

For example, the following request will get all the contacts with their included phone numbers:

  
  http://localhost:3000/contacts?include=phone_numbers&fields[contacts]=name_first,name_last&fields[phone_numbers]=number

The contact records will only contain the first and last names and the phone number will just contain the number.

Of course, you don't need to use ResourceController if your needs are different.

Routing

JR has a couple of helper methods available to assist you with setting up routes.

jsonapi_resources

Like resources in ActionDispatch, jsonapi_resources provides resourceful routes mapping between HTTP verbs and URLs and controller actions. This will also setup mappings for relationship URLs for a resource's associations. For example:

  
  require 'jsonapi/routing_ext'

Peeps::Application.routes.draw do
  jsonapi_resources :contacts
  jsonapi_resources :phone_numbers
end

This generates the following routes:

  
                       Prefix Verb   URI Pattern                                               Controller#Action
contact_links_phone_numbers GET    /contacts/:contact_id/links/phone_numbers(.:format)       contacts#show_association {:association=>"phone_numbers"}
                            POST   /contacts/:contact_id/links/phone_numbers(.:format)       contacts#create_association {:association=>"phone_numbers"}
                            DELETE /contacts/:contact_id/links/phone_numbers/:keys(.:format) contacts#destroy_association {:association=>"phone_numbers"}
                   contacts GET    /contacts(.:format)                                       contacts#index
                            POST   /contacts(.:format)                                       contacts#create
                new_contact GET    /contacts/new(.:format)                                   contacts#new
               edit_contact GET    /contacts/:id/edit(.:format)                              contacts#edit
                    contact GET    /contacts/:id(.:format)                                   contacts#show
                            PATCH  /contacts/:id(.:format)                                   contacts#update
                            PUT    /contacts/:id(.:format)                                   contacts#update
                            DELETE /contacts/:id(.:format)                                   contacts#destroy
 phone_number_links_contact GET    /phone_numbers/:phone_number_id/links/contact(.:format)   phone_numbers#show_association {:association=>"contact"}
                            POST   /phone_numbers/:phone_number_id/links/contact(.:format)   phone_numbers#create_association {:association=>"contact"}
                            DELETE /phone_numbers/:phone_number_id/links/contact(.:format)   phone_numbers#destroy_association {:association=>"contact"}
              phone_numbers GET    /phone_numbers(.:format)                                  phone_numbers#index
                            POST   /phone_numbers(.:format)                                  phone_numbers#create
           new_phone_number GET    /phone_numbers/new(.:format)                              phone_numbers#new
          edit_phone_number GET    /phone_numbers/:id/edit(.:format)                         phone_numbers#edit
               phone_number GET    /phone_numbers/:id(.:format)                              phone_numbers#show
                            PATCH  /phone_numbers/:id(.:format)                              phone_numbers#update
                            PUT    /phone_numbers/:id(.:format)                              phone_numbers#update
                            DELETE /phone_numbers/:id(.:format)                              phone_numbers#destroy

Use jsonapi_resource for singleton resources that can be looked up without an id.

You can control the relationship routes by passing a block into jsonapi_resources or jsonapi_resource. An empty block will not create any relationship routes.

You can add individual relationship routes with jsonapi_links. For example:

  
        jsonapi_resources :posts, except: [:destroy] do
        jsonapi_link :author, except: [:destroy]
        jsonapi_links :tags, only: [:show, :create]
      end

This will create relationship routes for author (show and create, but not destroy) and for tags (again show and create, but not destroy).

Getting started

We've shared a simple contact manager app created with JR called Peeps, which you can pull down and play with (some curl examples are provided). It also contains instructions for how to recreate the app if you want to see just what's involved. Hint - it's not much.

Status and Next Steps

So is JSONAPI::Resources complete? In a word, no. It is functional, but it is missing plenty of features. The biggest, as far as I see them, are pagination, sorting, and support for PATCH operations. Also not yet implemented are the top level meta and links objects. I plan to add these over time and would love community support to make and keep JR as compliant with JSON:API as possible.

In very basic testing I have found JSONAPI::Resources to be anywhere from 20% to 50% faster than the equivalent operation using version 0.8.1 of ActiveModel Serializers and 5% to 20% faster than the 0.9.0alpha master branch. Of course, there's probably some speed that can still be extracted from both projects.

I hope you find JSONAPI::Resources useful for building your own APIs. I'd appreciate your comments as well as your contributions.

Of Satellites and Rovers

2014-01-14T00:00:00Z

A few months ago I responded to some well publicized criticisms of client-side JavaScript web applications with some counterpoints. I promised a followup post to help clarify architecture decisions for web applications, and here it finally is…

When deciding whether to develop a traditional web app that generates HTML on the server or a client-side JavaScript web app, it's easy to focus on questions such as:

Which language can I use to write the bulk of my application?
Which approach is faster to load initially?
Which approach is faster to respond to subsequent actions?
Which requires the fewest architectural layers?

These questions have fairly quantifiable answers, and one factor may be so important for your application that it overrides all others. However, when this is not the case, you may end up feeling like your architectural decisions are going to involve a lot of unpleasant trade-offs.

A Thought Experiment

If you're racked with indecision, consider this: should your app be a communications satellite or a Mars rover?

A communications satellite, placed in close orbit around the Earth, acts as a relay for transmitting data between two points on the planet. The satellite does not need to understand the data: it relies on the transmitter to package up content that the receiver needs.

Similarly, a traditional web app relies on the server to generate HTML content, which is sent directly to the browser when requested. Once it reaches the browser, content is presented to the user with little manipulation. Every interaction with the application requires a round trip to the server. The browser becomes a relatively dumb but efficient intermediary.

On the other hand, a rover is imbued with artificial intelligence. It needs to be able to navigate remote landscapes, react to unexpected obstacles in real time, and communicate findings back to mission control. It should be able to survive communication problems while still interacting with its environment. A rover is more complex and autonomous than a satellite, so it needs to be particularly well tested before launch.

Just as a rover receives instructions from home and then uses them to interact with its landscape, a JavaScript web app receives raw data and needs to be able to make sense of it. It interacts directly with a user through the browser, without the need to involve "mission control" in real-time micro-decisions. Instead, it communicates in short bursts that contain exactly what it needs and what it's found. It must maintain its own state and have rules defining how it should respond to state changes.

Futurama

If you're still on the fence, try to look beyond the present. I consider these to be safe predictions:

Processors and browsers will become more performant.
Applications will be able to target evergreen browsers as they become the norm.
Improvements to JavaScript will make it more modular, capable and easier to code.
JavaScript frameworks will mature. Client-side data libraries will become more sophisticated and will better handle caching, transactions, undo / redo stacks and synchronization.

10…9…8…

In short, if interactivity is important for your app, then launch its intelligence and its sensors as close to users as possible by building a client-side web app. Ember.js is particularly good at building complex, autonomous and interactive web apps, and it's only getting better.

On the other hand, if your site is fairly static and you simply want to broadcast content to users, a traditional server-driven architecture may be right for your app.

Either way, it's worth pausing to consider this decision carefully, because a change in your approach will be both time consuming and costly.

The "Development Drawbacks" of JavaScript Web Applications

2013-08-08T00:00:00Z

With the advent of client-side application frameworks like Ember, Angular, and Backbone, there is a growing split in the web development community. A number of developers have dug in their heels against moving substantial application logic into JavaScript, and would prefer that servers continue to render as much HTML as possible. In the release notes for Rails 4, David Heinemeier Hansson declared that "a big focus has been on making it dead simple to build modern web applications that are screaming fast without needing to go the client-side JS/JSON server route". He went on to describe one of the new features, Turbolinks, as able to "essentially turn your app into a single-page javascript application in terms of speed, but with none of the developmental drawbacks".

I'd like to take a look at some of these perceived drawbacks and offer some counterpoints.

Language preference

Of course, we've only got one realistic language choice in the browser: JavaScript. If you prefer Ruby (or Python or Java or C#) over JavaScript, you may favor keeping as much of your application on the server as possible based on "developer happiness".

I agree that's an important metric, but let's face it: JavaScript simply can't be avoided when writing modern web applications. Instead of sprinkling jQuery snippets throughout your application in an effort to make it more "dynamic", you'll be much better off if you fully understand and embrace the JavaScript language.

Thanks to the efforts of TC39, JavaScript is actively being improved. You may be pleasantly surprised by some of the features coming in ES6, the next version of JavaScript. If you really can't stomach curly braces, give CoffeeScript a try. I should add that, in my consulting experience, I've noticed a trend towards front or back end specialization, especially on larger teams. If you strongly favor one or the other, you may not need to "wear all the hats" on a project.

Complexity

It's often argued that writing a client-side application paired with a backend API is substantially more complex than an equivalent server-rendered application. While that may be true in launching a minimum viable product, any time-to-launch advantages will probably dissipate as your service matures. In his criticism of client-side MVC, Thomas Fuchs claims that "what you end up with is building a layer cake that doesn’t add any value and slows down development."

I've found the opposite to be true: a strongly dilineated architecture benefits applications in the short and long run. By developing your front and back ends simultaneously, you can virtually guarantee that your service will have a useful and robust API, even at v1. And with an API as a firewall between front and back end code you'll gain discipline that will clarify architectural decisions and leave you with very little duplication of functionality across your stack.

Time to Load

An oft-cited problem with client-side applications is the time to download and initialize on page load. The total size of many JavaScript applications, including framework code, is typically the size of one or two JPEGs, and often is less than the total JavaScript downloaded on traditional web pages once all the miscellaneous plugins are added up. That's not to say that this is a non-issue: client-side applications typically don't display anything to users until they've been fully downloaded and initialized.

What's the answer? Start by delivering your assets as quickly as possible with a CDN. Consider splitting up larger applications into modules that can be progressively loaded as needed. This is possible in Ember, for instance, now that the router supports asynchronous loading of routes.

SEO

Although search crawlers don't yet automatically process JavaScript web applications, it's actually not that difficult to ensure that your public facing content will be searchable. Google provides a spec for making dynamically created content visible to crawlers, which Alex MacCaw discusses in his post SEO in JS Web Apps. Also check out SeoJs, which relies on PhantomJS to crawl your dynamic site and provide static indexable content to search spiders.

Primitive Browser Compability

This criticism is obvious: if you want your site to work without JavaScript, you'll need to create a version that is not entirely dependent upon JavaScript. The only way to make this happen is with redundant development of a simplified static site.

Of course, a large majority of server-rendered sites are also heavily dependent on JavaScript and face similar challenges to work with scriptless browsers. But then again, it's become so rare and undesirable to disable JavaScript that the option has been obfuscated in the upcoming v23 of Firefox.

Accessibility

While some screen readers don't work with JavaScript generated content, Apple's VoiceOver does a pretty decent job regardless of where the markup was created. You can try it out in OS X simply by pressing ⌘ + F5 in your browser.

Going further, the W3C's WAI-ARIA spec aims to make dynamic content more accessible to people with disabilities. By adding custom role and aria-* attributes to elements, combined with semantic structure, you can provide guidance to improve how content is presented by VoiceOver and other sophisticated screen readers.

Similar Appearance

Another charge that Thomas Fuchs levels is that "if you use something like Ember (which we didn’t), it’s even worse as all applications using it practically look the same (many people choose using Twitter’s Bootstrap library, for example)".

I'm not sure where this originated, but it is not unlike claiming that all Rails applications look the same. As a frequent user of and contributor to Ember, I can assure Thomas (and everyone else) that Ember applications are in no way tied to a particular style or user experience. Peruse popular Ember apps like Discourse, Yapp, Zendesk, and Square to see for yourself.

I realize that this post may seem a bit defensive, but I think it's important to not let claims go unchecked. I've personally been working with Ember.js for the past 20 months and couldn't be happier with my choice for the applications I've been developing. While some aspects of development have been more challenging, I think the pros far outweigh the cons for many types of applications.

Stay tuned for a post that can help clarify this decision for your application...

"Single Page Applications"

2013-07-31T00:00:00Z

I no longer use the term "Single Page Application".

The term is quite server-centric, which made a lot of sense when it was coined in 2005. However, with the introduction of pushState and replaceState in HTML5, applications can now directly manipulate the browser's history and visibly change the URL. It's hard to argue that an application exists on a "single page" when it can navigate to multiple URLs, all of which can be bookmarked or opened in new tabs, and can reconstitute their state with a browser refresh. Certainly this doesn't fit any user's definition of a "page".

Terminology is important. Instead of Single Page Application, I now say "JavaScript Web Application". Perhaps a bit boring, but undeniably accurate :)

Understanding Ember.Object

2012-03-06T00:00:00Z

Almost every object in Ember.js is derived from a common object: Ember.Object. This object is used as the basis for views, controllers, models, and even the application itself.

This simple architectural decision is responsible for much of the consistency across Ember. Because every object has been derived from the same core object, they all share some core capabilities. Every Ember object can observe the properties of other objects, bind their properties to the properties of other objects, specify and update computed properties, and much more.

As you'll see in this post, it's easy to get started with Ember.Object, but also easy to overlook some of its capabilities. A better understanding of Ember.Object will help you understand the architecture of Ember itself and enable you to improve the architecture of your own application.

Creating objects

It's almost as simple to create a new Ember.Object as a plain Javascript object:

  
  var emberObject = Ember.Object.create({
  greeting: "hello"
});

var jsObject = {
  greeting: "hello"
};

The object literal that is optionally passed to Ember.Object.create() defines properties directly on the instantiated object, not unlike the vanilla object. However, upon inspection in your console, you can see there's quite a bit more going on behind the scenes of the Ember object:

It would take a long tour of the Ember source to explore all the properties of even such a simple Ember object. Needless to say, it's all required for Ember to enable bindings, observers, and more. Although it looks like quite a bit of overhead, the complexity of the Ember object is contained almost entirely in its prototype (Ember.Object.prototype) and not within the object instance.

Extending classes

To go beyond vanilla Ember objects, you can extend Ember.Object or any of its descendents to create your own classes:

  
  var Person = Ember.Object.extend({
  species: "homo sapiens"
});

var Man = Person.extend({
  gender: "male"
});

var Woman = Person.extend({
  gender: "female"
});

Important: the object literal that is passed as an argument to extend() defines properties for the *prototype** of objects that will be instantiated by the class.*

Now, let's instantiate a person with create():

  
  var joe = Man.create({
  name: "Joe"
});

Important: remember that the object literal passed to create() defines properties of the *instantiated object** (not its prototype).*

And let's inspect our new person:

  
  console.log( joe.get("name") );               // "Joe"
console.log( joe.hasOwnProperty("name") );    // true
console.log( joe.get("gender") );             // "male"
console.log( joe.hasOwnProperty("gender") );  // false
console.log( joe.get("species") );            // "homo sapiens"
console.log( joe.hasOwnProperty("species") ); // false

console.log( Man.prototype.isPrototypeOf(joe) );          // true
console.log( Person.prototype.isPrototypeOf(joe) );       // true
console.log( Ember.Object.prototype.isPrototypeOf(joe) ); // true

As you can see, the prototype chain for joe includes Man.prototype, Person.prototype, and Ember.Object.prototype. Our person can correctly evaluate his name (defined directly on the instance), gender (defined on Man.prototype), and species (defined on Person.prototype). What a smart guy!

Initialization (and a common mistake!)

One of the most common mistakes for beginners to Ember is to think they're passing properties to an instance instead of a prototype. For example:

  
  var Person = Ember.Object.extend({
  chromosomes: ["x"] // CAREFUL !!!!!
});

var joe = Person.create();
joe.get("chromosomes").push("y");

var jane = Person.create();
jane.get("chromosomes").push("x");

// Joe and Jane are all mixed up?!?!?!?!
console.log( joe.get("chromosomes") );  // x, y, x
console.log( jane.get("chromosomes") ); // x, y, x

Why did this chromosomal mutation happen? The problem started when we added an array to our prototype when defining the Person class. This array was then shared with each object instantiated from Person.

How should we have handled this?

  
  var Person = Ember.Object.extend({
  chromosomes: null,
  init: function() {
    this._super();
    this.set("chromosomes", ["x"]); // everyone gets at least one X chromosome
  }
});

var joe = Person.create();
joe.get("chromosomes").push("y");  // men also get a Y chromosome

var jane = Person.create();
jane.get("chromosomes").push("x"); // women get another X chromosome

// Hurray - everyone gets their own chromosomes!
console.log( joe.get("chromosomes") );  // x, y
console.log( jane.get("chromosomes") ); // x, x

When declaring objects or arrays in your classes, you'll typically want to initialize them along with each instance in the init() function. In this way, each of your objects will receive its own unique instances of objects and arrays. Also remember to call this._super() from within init() so that init() will be called all the way up the prototype chain.

Of course, there's nothing wrong with keeping objects or arrays directly in your prototypes if they are meant to remain constant across instances. In fact, one common pattern is to keep a default setting in the prototype that's then duplicated for each instance in init(). These kinds of patterns are easy to implement once you realize how objects are created and initialized.

Want to play more with inheritance and initialization? I've extended this example on jsFiddle.

Reopening objects and classes

You can easily add properties to Ember classes after they've been defined using reopen():

  
  var Person = Ember.Object.extend({
  firstName: null,
  lastName:  null
});

Person.reopen({
  middleName: null
});

Specifically, reopen() modifies the prototype that will be used for objects instantiated by a class.

If you want to add properties directly to a class, use reopenClass():

  
  var Person = Ember.Object.extend({
  firstName: null,
  lastName:  null
});

Person.reopenClass({
  makeBaby: function(attributes) {
    return Person.create(attributes);
  }
});

var huey = Person.makeBaby({firstName: "Baby", lastName: "Huey"});

One useful pattern is to define class methods for finding and/or creating objects.

Mixing in concerns

While extending classes in a hierarchical fashion often works well, there is a tendency to end up with classes such as MaleLeftHandedPetOwnersOfPoodles. Trying to munge together a bunch of separate concerns in a single class can get messy. Ember's answer to this problem is Ember.Mixin. Here it is in action:

  
  var Pet = Em.Object.extend({
  name: null
});

var PetOwner = Ember.Mixin.create({
  pet: null,

  init: function() {
    this._super();
    this.set("pet", Pet.create({}));
  }
});

var Male = Ember.Mixin.create({
  chromosomes: null,

  init: function() {
    this._super();
    this.set("chromosomes", ["x", "y"]);
  }
});

var joe = Ember.Object.create(PetOwner, Male, {
  age:  25,
  name: "Joe",

  init: function() {
    this._super();
    this.get("pet").set("name", "Fifi");
  }
});

console.log( joe.get("name") );            // Joe
console.log( joe.get("age") );             // 25
console.log( joe.get("chromosomes") );     // x,y
console.log( joe.get("pet.name") );        // Fifi

In this example, we're merging a number of separate concerns in a single object. Joe is both a PetOwner and a Male, and has other traits such as an age and name. He not only has a pet, but that pet even has a name.

The separate concerns are each represented by an Ember.Mixin. The joe object is created as a merger of the PetOwner and Male mixins, as well an object literal that represents instance properties. Mixins get initialized in the order in which they are passed to create(), which allows joe to set his pet's name after PetOwner has created that pet.

Want to play more with this example? It's also on jsFiddle.

But wait... there's more :)

Mixins aren't limited to objects that you create(). They can also be used with extend(), reopen(), and reopenClass.

Furthermore, there's a suite of useful mixins built right into Ember core. Do you want your object to be enumerable? Mix in Ember.Enumerable. Want to create a view that triggers an action? Extend it with Ember.TargetActionSupport.

I think you'll find that by separating lateral concerns in mixins, and hierarchical concerns with extend(), you can build a very flexible architecture for your Ember apps.

Any questions or suggestions for further Ember posts? Please feel free to comment below -- Dan

Beginning Ember.js on Rails: Part 3

2012-01-31T00:00:00Z

This is part of a series of posts about Ember.js. Please read Warming up to Ember.js as well as the Ember.js home page if you're new to Ember.js.

As promised in Part 2 of this series, this post will show how records are added, updated and removed in our example app. This app uses our ultra-simple Ember REST library to communicate with a REST interface served by Rails. I'll try to point out when parts of this example use the persistence library (ember-rest.js) instead of core Ember (ember.js).

Because our REST interface was completed in Part 2, let's move right to the client-side code...

Creating records

We'll start by extending our Ember model and views to enable creating records. As you'll soon see, much of this work is applicable to editing records as well.

Extend the model

In order to serialize our model, we need to define its resourceName and resourceProperties. In this way, ember-rest.js can send back only the data required by our REST interface:

app/assets/javascripts/app/models/contact.js

  
  App.Contact = Ember.Resource.extend({
  resourceUrl:        '/contacts',
  resourceName:       'contact',
  resourceProperties: ['first_name', 'last_name'],

  validate: function() {
    if (this.get('first_name') === undefined || this.get('first_name') === '' ||
        this.get('last_name') === undefined  || this.get('last_name') === '') {
      return 'Contacts require a first and a last name.';
    }
  },

  fullName: Ember.computed(function() {
    return this.get('first_name') + ' ' + this.get('last_name');
  }).property('first_name', 'last_name')
});

The optional validate() method will be called by ember-rest.js when saving records. Returning an error string or object will prevent saving an invalid record. And yes, those validations might look cleaner in CoffeeScript ;)

Extend the listing view

Our listing view needs to allow contacts to be added. Let's modify its template first:

app/assets/javascripts/app/templates/contacts/list.handlebars

  
  <table>
  <thead>
    <tr>
      <th>ID</th>
      <th>Name</th>
    </tr>
  </thead>
  <tbody>
  {{#each contacts}}
    {{view App.ShowContactView contactBinding="this"}}
  {{/each}}
  {{#if isNewVisible}}
    <tr>
      <td>*</td>
      <td>
        {{view App.NewContactView}}
      </td>
    </tr>
  {{/if}}
  </tbody>
</table>
<div class="commands">
  <a href="#" {{action "showNew"}}>New Contact</a>
</div>

Notice the "New Contact" link at the bottom. We're using the {{action}} helper to delegate its click event (the default for action) to the showNew() handler on the listing's view class:

app/assets/javascripts/app/views/contacts/list.js

  
  App.ListContactsView = Ember.View.extend({
  templateName:    'app/templates/contacts/list',
  contactsBinding: 'App.contactsController',

  showNew: function() {
    this.set('isNewVisible', true);
  },

  hideNew: function() {
    this.set('isNewVisible', false);
  }
});

In turn, the view class sets its isNewVisible property to true. By using set(), Ember's bindings will trigger a change in the above template. {{#if isNewVisible}} will now be true, so the extra row will be displayed in our listing.

Create a view for new contacts

As you can see in the listing's template, a NewContactView will be created within the new row in our listing:

app/assets/javascripts/app/views/contacts/new.js

  
  App.NewContactView = Ember.View.extend({
  tagName:      'form',
  templateName: 'app/templates/contacts/edit',

  init: function() {
    this._super();
    this.set("contact", App.Contact.create());
  },

  didInsertElement: function() {
    this._super();
    this.$('input:first').focus();
  },

  cancelForm: function() {
    this.get("parentView").hideNew();
  },

  submit: function(event) {
    var self = this;
    var contact = this.get("contact");

    event.preventDefault();

    contact.saveResource()
      .fail( function(e) {
        App.displayError(e);
      })
      .done(function() {
        App.contactsController.pushObject(contact);
        self.get("parentView").hideNew();
      });
  }
});

There's a lot going on here!

First of all, this view's tagName will make it a form instead of the default div. Next are a couple methods overridden from the standard Ember.View:

init() - This is called to set up a view, but before it gets added to the DOM. It's a good place to create a new contact object and associate it with our view. This object will be referenced in templates associated with our view.

didInsertElement() - This is called immediately after our element gets inserted in the DOM. It's a good place for us to set focus to the initial input element on our form.

There are also a couple custom methods:

cancelForm() - hides this form in our parent view (see hideNew() in the listing view above).

submit() - Ember will automatically set up event listeners for views when you add methods from a standard list (currently here). In this case, we'll be listening for our form's submit() event.

Within the submit() handler, we'll attempt to create our contact with the saveResource() method defined in ember-rest.js. The jQuery deferred methods fail() and done() will handle failure and success. Failure could come from either a client-side validation problem in our model, a problem communicating with the server, or an error returned from our Rails controller. On success, the new contact will be pushed into our controller's collection. There's no need to refresh our views - Ember will just add a new entry to our listing!

Let's check out the template for this view:

app/assets/javascripts/app/templates/contacts/edit.handlebars

  
  {{#with contact}}
  {{view Ember.TextField valueBinding="first_name" placeholder="First name"}}
  {{view Ember.TextField valueBinding="last_name"  placeholder="Last name"}}
  <button type="submit">
    {{#if id}}Update{{else}}Create{{/if}}
  </button>
{{/with}}
<a href="#" {{action "cancelForm"}}>Cancel</a>

Perhaps you noticed that we aren't applying any attributes from our form to our model before calling saveResource()? We can skip this messiness because we've bound Ember.TextField views to our model's properties. Each view tracks focus and keyboard events to ensure that the model's property stays in sync with its corresponding input field.

You might also notice that, to determine the submit button's text, we're checking the model's id to see if this is a new record to create or an existing one to update. In this way, we can reuse this template to handle edits.

Editing and deleting records

Editing records is very similar to adding them. The major difference is that, in order to enable changes to be saved or cancelled, we're going to edit a copy of our object instead of the object itself.

Because the changes needed to edit and delete records require changes in the same views, I’m going to explain them together.

Extending the show view

Let's extend the template we're using to display each record in our listing:

app/assets/javascripts/app/templates/contacts/show.handlebars

  
  <td>{{contact.id}}</td>
<td class="data">
  {{#if isEditing}}
    {{view App.EditContactView}}
  {{else}}
    {{contact.fullName}}
  {{/if}}
  <div class="commands">
    {{#unless isEditing}}
      <a href="#" {{action "showEdit"}}>Edit</a>
      <a href="#" {{action "destroyRecord"}}>Remove</a>
    {{/unless}}
  </div>
</td>

You can see that we're following the same pattern from our listing template to either show an EditContactView when isEditing is true, or contact.fullName when it's not. Also, when we're not editing this contact, we display links to edit / remove it.

Let's also extend the corresponding view class:

app/assets/javascripts/app/views/contacts/show.js

  
  App.ShowContactView = Ember.View.extend({
  templateName: 'app/templates/contacts/show',
  classNames:   ['show-contact'],
  tagName:      'tr',

  doubleClick: function() {
    this.showEdit();
  },

  showEdit: function() {
    this.set('isEditing', true);
  },

  hideEdit: function() {
    this.set('isEditing', false);
  },

  destroyRecord: function() {
    var contact = this.get("contact");

    contact.destroyResource()
      .fail( function(e) {
        App.displayError(e);
      })
      .done(function() {
        App.contactsController.removeObject(contact);
      });
  }
});

The showEdit() and hideEdit() handlers toggle isEditing, which controls whether EditContactView will be shown within the template (as seen above).

The destroyRecord() handler calls our model's destroyResource() method, defined in ember-rest.js. It has fail() and done() deferreds, just like saveResource(). On success, the record is removed from the controller's collection. As you could guess, Ember ensures that this change is reflected in the DOM immediately.

Extending the edit view

EditContactView is similar to NewContactView, with a few exceptions:

app/assets/javascripts/app/views/contacts/edit.js

  
  App.EditContactView = Ember.View.extend({
  tagName:      'form',
  templateName: 'app/templates/contacts/edit',

  init: function() {
    this._super();

    // Create a new contact that's a duplicate of the contact in the parentView;
    // Changes made to the duplicate won't be applied to the original unless
    // everything goes well in submitForm()
    this.set("contact", this.get('parentView').get('contact').copy());
  },

  didInsertElement: function() {
    this._super();
    this.$('input:first').focus();
  },

  cancelForm: function() {
    this.get("parentView").hideEdit();
  },

  submit: function(event) {
    var self = this;
    var contact = this.get("contact");

    event.preventDefault();

    contact.saveResource()
      .fail( function(e) {
        App.displayError(e);
      })
      .done( function() {
        var parentView = self.get("parentView");
        parentView.get("contact").duplicateProperties(contact);
        parentView.hideEdit();
      });
  }
});

Within init(), we create a copy of the parent view's contact. This allows us to make changes that can be discarded if the form is cancelled.

In submit(), the contact's updated properties are copied back to the original after it's been saved successfully. This is done using the duplicateProperties() helper from ember-rest.js.

Of course, if you'd prefer that edits be made directly to the original record, you could skip both of these steps.

Whew, we made it! I hope that this series piqued your interest enough to try Ember yourself. If you've just been reading along, try running and modifying the example app yourself.

Although this is the final part of "Beginning Ember.js on Rails", I plan to blog more about Ember. There's quite a bit more to this framework than I've covered here, so please let me know if you have suggestions for future posts. If you'd like to stay tuned, you can follow our RSS, Twitter and Github accounts in the lower right. Thanks! - Dan

Beginning Ember.js on Rails: Part 2

2012-01-26T00:00:00Z

This is part of a series of posts on Ember.js. Please read Warming up to Ember.js as well as the Ember.js home page if you're new to Ember.js.

As promised in Part 1 of this series, this post will show how the example app uses our ultra-simple Ember REST library to query a resource's REST interface to display a list of records.

Server-side Rails

Our Rails code is close to the minimum needed to serve up a RESTful JSON interface. It was originally generated with rails g scaffold and then simplified further.

Model

The Rails model for contacts is quite basic:

app/models/contact.rb

  
  class Contact < ActiveRecord::Base
  validates :first_name, :presence => true
  validates :last_name, :presence => true
end

Controller

The controller is a simplified version of the scaffolding:

app/controllers/contacts_controller.rb

  
  class ContactsController < ApplicationController
  # GET /contacts
  # GET /contacts.json
  def index
    @contacts = Contact.all

    respond_to do |format|
      format.html # index.html.erb
      format.json { render json: @contacts }
    end
  end

  # GET /contacts/1.json
  def show
    @contact = Contact.find(params[:id])

    respond_to do |format|
      format.json { render json: @contact }
    end
  end

  # POST /contacts.json
  def create
    @contact = Contact.new(params[:contact])

    respond_to do |format|
      if @contact.save
        format.json { render json: @contact, status: :created, location: @contact }
      else
        format.json { render json: @contact.errors, status: :unprocessable_entity }
      end
    end
  end

  # PUT /contacts/1.json
  def update
    @contact = Contact.find(params[:id])

    respond_to do |format|
      if @contact.update_attributes(params[:contact])
        format.json { render json: nil, status: :ok }
      else
        format.json { render json: @contact.errors, status: :unprocessable_entity }
      end
    end
  end

  # DELETE /contacts/1.json
  def destroy
    @contact = Contact.find(params[:id])
    @contact.destroy

    respond_to do |format|
      format.json { render json: nil, status: :ok }
    end
  end
end

There are a couple interesting aspects to this controller code. First of all, the only action that responds to an html request is index. I've trimmed the others to respond only with json.

Also note that the update and destroy actions respond to success with:

  
    render json: nil, status: :ok

... instead of the scaffolded default (head :ok), which jQuery.ajax() interprets as an error.

Routes

As you can see, we're routing root requests to our contacts controller:

config/routes.rb

  
  EmberRestExample::Application.routes.draw do
  root :to => 'contacts#index'
  resources :contacts
end

Let's move to the client-side before we get back to our server-side views...

Client-side Ember

We're now going to take a quick look at the client-side Ember model, view and controller code needed to display a list of contacts. This code is all organized within app/assets/javascripts/app/, as discussed in part 1 of this series.

If you're following along in the example code, note that I'm leaving out a lot of the code having to do with editing records for the sake of simplicity.

Application

As reviewed in the first part of this series, the application object can be quite simple:

app/assets/javascripts/app/app.js

  
  App = Ember.Application.create();

This object will contain all of the models, controllers and views for the application.

Model

Let's move along to the model:

app/assets/javascripts/app/models/contact.js

  
  App.Contact  = Ember.Resource.extend({
  resourceUrl: '/contacts',

  fullName: Ember.computed(function() {
    return this.get('first_name') + ' ' + this.get('last_name');
  }).property('first_name', 'last_name')
});

This is an extension of Ember.Resource, which is defined in ember-rest.js as an extension of Ember.Object. The resourceUrl is the base url of the resource.

Also of interest in the model is the computed property fullName, which returns a concatenation of first_name and last_name. It defines these properties as dependencies with property('first_name', 'last_name'). If either of those dependencies is updated, then fullName will be updated too. Any bindings to fullName in views will also be updated.

Controller

Our Ember-based contacts controller is very simple:

app/assets/javascripts/app/controllers/contacts.js

  
  App.contactsController = Ember.ResourceController.create({
  resourceType: App.Contact
});

Instead of defining a class like App.Contact, we're creating App.contactsController as an object. It's an instance of Ember.ResourceController, which is defined in ember-rest.js as a thin extension to an Ember.ArrayController. Its only configured property is resourceType, which links it to our model. The controller knows enough to use the resourceUrl from the model to query resources (although the resourceUrl can be overridden at the controller level if needed).

Views

Let's now check out our Ember views.

ListContactsView renders the listing:

app/assets/javascripts/app/views/contacts/list.js

  
  App.ListContactsView = Ember.View.extend({
  templateName:    'app/templates/contacts/list',
  contactsBinding: 'App.contactsController',

  refreshListing: function() {
    App.contactsController.findAll();
  }
});

While ShowContactView renders each row within the listing:

app/assets/javascripts/app/views/contacts/show.js

  
  App.ShowContactView = Ember.View.extend({
  templateName: 'app/templates/contacts/show',
  classNames:   ['show-contact'],
  tagName:      'tr'
});

Each view is associated with a template via templateName. The rendered template is contained within an html element that is mapped to its corresponding view. By default this is a div, although views can override this with the tagName property. This element can be customized further with classNames.

Also note the contactsBinding property on App.ListContactsView, which binds the controller's data to this view as the property contacts.

Templates

Let's see how each of these views is templated in Handlebars. First up is our listing:

app/assets/javascripts/app/templates/contacts/list.handlebars

  
  <table>
  <thead>
    <tr>
      <th>ID</th>
      <th>Name</th>
    </tr>
  </thead>
  <tbody>
  {{#each contacts}}
    {{view App.ShowContactView contactBinding="this"}}
  {{/each}}
  </tbody>
</table>

This template loops through contacts, which are bound to App.contactsController, using the each helper and renders each one using ShowContactView. Because ShowContactView has a tagName of tr, a new row will be inserted for each record. It will also render the show template:

app/assets/javascripts/app/templates/contacts/show.handlebars

  
  <td>{{contact.id}}</td>
<td class="data">
  {{contact.fullName}}
</td>

Notice how the contactBinding in list.handlebars is passed through to the show view, which can reference the object as contact in its template.

All together now

Let's pull this all together in a single server-rendered ERB view:

app/views/contacts/index.html.erb

  
  <h1>Contacts</h1>

<script type="text/x-handlebars">
  {{ view App.ListContactsView }}
</script>

<script type="text/javascript">
  $(function() {
    App.contactsController.loadAll(<%= @contacts.to_json.html_safe %>);
  });
</script>

The first script block is written in Handlebars, as indicated by its type. It uses the Ember view helper to render App.ListContactsView.

The javascript block is a bit of an optimization. It loads contacts, fetched in our controller's index action, into our Ember-based App.contactsController. The reason for this is simple: we can improve performance by loading contacts in the same request as the page. A simpler alternative to calling loadAll() would be to find all contacts after jQuery has loaded, like so:

  
  <script type="text/javascript">
  $(function() {
    App.contactsController.findAll();
  });
</script>

Let's recap what we've done here. We first configured a REST interface to our data in Rails. Next we configured our Ember controller and model to load data from that interface via ember-rest.js. Finally, we hooked up our Ember views and templates to our controller's data.

Let's also recap what we haven't done here. Thanks to ember-rest.js, we haven't needed to write any ajax code to query our REST interface. And thanks to Ember, we haven't needed to write code to update our views when contacts are loaded into the controller's array.

Ember will really begin to shine when we see that our views are kept in sync even as contacts are added, updated, and removed. Speaking of which, my next post will cover just that...

Please continue on to Beginning Ember.js on Rails: Part 3, the final part in this series.