Tuesday, 23 December 2014

12 Tips of Christmas - 12 Testing your API

12 Tips of Christmas - 12 Testing your API

In our final tip, we're going to take a look at testing our API, which now looks like this

module API
  module V1
    class Posts < Grape::API
      version 'v1'
      format :json

      resource :posts do
        desc "Return 10 most recent posts"

        get do
          posts = Post.most_recent.limit(10)
          present :posts, posts, with: API::V1::Entities::Post
        end

        desc 'Find a specific post'
        params do
          requires :id, type: Integer, desc: "The ID of the post"
        end
        get ':id' do
          post = Post.find(params[:id)
          present :post, post, with: API::V1::Entities::Post              
        end
      end

    end
  end
end

To begin, we want to ensure that our API returns the data we expect it to

# spec/api/v1/post_spec.rb

describe API::V1::posts do
  describe "GET /api/v1/posts" do
    it "returns an empty array of statuses" do
      get "/api/v1/posts"
      expect(response.status).to eq(200)
      expect(JSON.parse(response.body)).to eq({"posts"=>[]})
    end

    it "filters based on names" do
      expected_post = create(:post, content: "Foobar")
      unexpected_post = create(:post, content: "Baz")
      get "/api/v1/posts?content=Foobar"

      expect(response.status).to eq(200)
      expect(JSON.parse(response.body)).to eq({"posts"=>[{"id"=>expected_post.id,
                                                           "content"=> expected_post.content, "created_at"=>"#{expected_post.created_at}"
                                                           }]})
    end
    it "filters based on location id" do
      expected_post = create(:post, content: "Foobar")
      unexpected_post = create(:post, content: "Baz")
      get "/api/v1/posts?place_id=Quas"

      expect(response.status).to eq(200)
      expect(JSON.parse(response.body)).to eq({"posts"=>[{"id"=>expected_post.id,
                                                           "content"=> expected_post.content, "created_at"=>"#{expected_post.created_at}"
                                                          }]})
    end
  end
end

As you can see these function very similar to a request spec and are implemented accordingly. The utilisation of the JSON.parse ensures our content that is exposed matched what we expect.

A simpler version for this is using airborne a Gem designed to not only verify the type of content we return, but the content itself, for example:

it 'should validate types' do
  expected_post = create(:post, content: "Foobar")
  unexpected_post = create(:post, content: "Baz")
  get "/api/v1/posts?content=Foobar"
  expect_json({"posts"=>[{"id"=>expected_post.id,"content"=> expected_post.content, "created_at"=>"#{expected_post.created_at}"}]})
  expect_json_types({id: :integer)
end

So now you have no excuse for not testing your API!

Sunday, 21 December 2014

12 Tips of Christmas - 11 Restricting your API

12 Tips of Christmas - 11 Restricting your API

Yesterday we ended up with the following API. The one issue we have is that we've exposed all of our Post model regardless if we want to or not. 
module API
  module V1
    class Posts < Grape::API
      version 'v1'
      format :json

      resource :posts do
        desc "Return 10 most recent posts"

        get do
          Post.most_recent.limit(10)
        end

        desc 'Find a specific post'
        params do
          requires :id, type: Integer, desc: "The ID of the post"
        end
        get ':id' do
          Post.find(params[:id)
        end
      end

    end
  end
end
Grape provides an easy way to deal with this in the form of entities.
Under our V1 API directory, we're going to create a Post entity, that will restrict the information that comes out of our API
# app/controllers/api/v1/entities/post.rb
module API
  module V1
    module Entities
      class Post < Grape::Entity
        expose :content, documentation: { type: "String", desc: "The Post content"}
        expose :title, documentation: { type: "String", desc: "The Post title"}

        expose :description, documentation: { type: "String", desc: "The Post description" }

        format_with(:iso_timestamp) { |dt| dt.iso8601 }

        with_options(format_with: :iso_timestamp) do
          expose :created_at, documentation: { type: "DateTime", desc: "When the Post was posted"}
        end

        expose :comments, using: API::V1::Entities::Comments
      end
    end
  end
end
With use of the expose method, we can dictate what we do and don't return from our API, as well as provide documentation for users consuming our API. 
When working with building an API initially, I ran into an issue where the datetime returned by my API was different to what was initially coming into the database, the format_with method alleviates this by providing an easy way to declare a format to utilise on a particular attribute, which is picked up in the with_options block.
Finally as our post has many comments we can also expose those to an API request and utilise another entity again to control what of the comment data we return.

Saturday, 20 December 2014

12 Tips of Christmas - 10 Building an API with Grape

12 Tips of Christmas - 10 Building API's with Grape

As I work more and more with Ember, grasping onto well structured API's becomes increasingly valuable. Thanks to Grape, building an API out of your Rails application is very easy.
To start, add grape to your Gemfile, like so and run bundle install
gem "grape"
As we're ultimately serving up a response to requests from the client, we're going to house our API in our controllers directory. As Grape supports versioned API's we're going to keep that structure in place when we begin to create our API. So, first things first, let's create a base.rb file to mount our versioned API's
# app/controllers/api/base.rb

module API
  class Base < Grape::API
    mount API::V1::Base
  end
end
Now let's create our other base.rb file in our V1 directory so we can mount the resources this version of the API will support.
# app/controllers/api/v1/base.rb

module API
  class Base < Grape::API
    mount API::V1::Users
    mount API::V1::Posts
  end
end
Let's also setup our routes to support our new API
# config/routes.rb

mount API::Base => '/api'
This makes our users and posts API available at http://localhost:3000/api/v1/users.json and http://localhost:3000/api/v1/posts.json respectively (assuming you're exporting out JSON).
So let's take a look at what our API's might look like:
module API
  module V1
    class Posts < Grape::API
      version 'v1'
      format :json

      resource :posts do
        desc "Return 10 most recent posts"

        get do
          Post.most_recent.limit(10)
        end

        desc 'Find a specific post'
        params do
          requires :id, type: Integer, desc: "The ID of the post"
        end
        get ':id' do
          Post.find(params[:id)
        end
      end

    end
  end
end
In this very simple example, we declare the version and the format in which we will return.
We also declare the resource we're going to work with, along with our two GET requests we accept, one that returns the 10 most recent posts and one that will return a post determined by the id parameter supplied.
You'll notice that this is starting to look alot like our regular controllers, as well it should. We can also expand on this to start allowing users to make POST and PATCH requests as well.
With our params block , we can specify what parameters we accept as well as in what format they should come, much like Rails' strong parameters.
We also have the ability to document our API as we go with our description methods, this is far far easier to do as you're building up the API so I highly encourage you to do it as you go.
In the next post we'll take a look at restricting the data coming back out of our API

Friday, 19 December 2014

12 Tips of Christmas - 9 Custom Generators

Twelve Tips of Christmas - 9 Custom Generators

With an application template and the assistance of a gem, bootstrapping a brand new Rails app is very easy for us these days. I hadn't realised how spoilt we had become until I had to create one from scratch recently.

One of the nice things in our bootstrap process, is that I have a few generators running to install some custom templates for our application to utilise. Creating a generator command is pretty easy and can be done within a gem or within your own Rails app

We'll use our basic example which is to copy our usual Capistrano configuration templates over to our application folder:

Firstly, you'll need to extend Rails::Generators::Base and give it the root directory of your templates to copy over

class CapistranoConfigGenerator < Rails::Generators::Base
  source_root File.expand_path("../../templates", __FILE__)
end

Then its as simple as creating your methods and using the Thor API to start moving your files over:

class CapistranoConfigGenerator < Rails::Generators::Base
  source_root File.expand_path("../../templates", __FILE__)

  def copy_config_files
    copy_file "config/deploy.rb", "config/deploy.rb"
    directory "config/deploy", "config/deploy"
  end
end

Passing in an additional description, will help new users determine what your generator actually does if they dont happen to look at your code

class CapistranoConfigGenerator < Rails::Generators::Base
  source_root File.expand_path("../../templates", __FILE__)

  desc 'Copies over Capistrano templates'
  def copy_config_files
    copy_file "config/deploy.rb", "config/deploy.rb"
    directory "config/deploy", "config/deploy"
  end
end

The help can be viewed by running (assuming your generator is housed in your Rails application): bin/rails generate capistrano_config --help

Following that, just running the generate command and it'll safely start moving over those files for you

`bin/rails generate capistrano_config`

The flexibility and scope of Thor makes it really easy to accomplish any bootstrapping you may need to do, I highly recommend checking out the documentation

Thursday, 18 December 2014

12 Tips of Christmas - 8 Send Emails with Sidekiq

12 Tips of Christmas - 8 Send Emails with Sidekiq

To help ensure users get a fast experience within your application, one tool you can utilise is Sidekiq to process any sending of email you might be doing asynchronously. 
To get started, just add the following line to your Gemfile
gem 'sidekiq'
You'll also need redis, so if you haven't got that installed run the following:
$ brew update

$ brew install redis

$ redis-server /usr/local/etc/redis.conf
To run Sidekiq:
$ bundle exec sidekiq
Sidekiq supports sending emails with ActionMailer off the bat, all you need to do is call delay before your mailer method instead of using deliver eg:
UserMailer.delay.reminder(@user)
We can also call delay_until to delay the email send until a specified time.
All too easy

Wednesday, 17 December 2014

12 Tips of Christmas - 7 Inversion of Control

12 Tips of Christmas - 7 Inversion of Control

A lot of my posts in this series tend to revolve around a common theme, refactoring. When extracting a class, or method, you should look to inversion of control to make testing, and identification of dependencies easier.
Suppose we had a class like this:
class Receipt
  def mark_purchase
    @purchase = Purchase.latest.first
    enter_purchase_amount @purchase.amount
  end
end
By returning an instance of purchase within the method, we have created an implicit dependency on Purchase, this also makes it harder to test the method without first requiring an instance of the Purchase model. On top of this, we are now tied to the Purchase API, when all we wanted is something that would respond to amount.
Fixing this is easy.
class Receipt
  attr_reader :purchase

  def initialize purchase
    @purchase = purchase
  end

  def mark_purchase
    enter_purchase_amount purchase.amount
  end
end
Now when we instantiate our object, we can give it an instance of any object, so long as that object responds to the amount method, giving us some great flexibility
On top of that, our class can now be decoupled from ActiveRecord within our tests, as all we need to do is provide a test double for a purchase object.
One other benefit is that now, our dependency on purchase is explicit, this assists with future maintainers as they will be able to quickly identify it rather than get surprised down the road.
Of course this example is overtly simple, in our object if we didn't require any other reference to purchase, it would be far simpler to just pass in our amount as a dependency. This example, does however illustrate that by moving the responsibility of assigning the dependency up the chain, we've gained an interface thats more flexible, easier to maintain and easier to test.

Tuesday, 16 December 2014

12 Tips of Christmas - 6 Decorators

One of the really nice things about working with Ember is that every part nicely encapsulates it's level of responsibility. With Rails, this can be a harder proposition, especially when dealing with the view layer. Decorators can alleviate this issue and form our 6th, valuable tip.
We can utilise decorators to move view related logic out of the model, or helper and into the decorator object, we can do this, using SimpleDelegator.
SimpleDelegator accepts an object as part of it's instantiation, and if it can't find a method it will delegate to the underlying object.
class UserDecorator < SimpleDelegator
  def full_title
    "#{title} #{first_name} #{last_name}"
  end
end


class UsersController < ApplicationController
  def show
    @user = UserDecorator.new(User.find(params[:id])
  end
end
Using decorators as a view object, is a very simple option for moving logic out of the business layer that is the model.
Extending this concept, methods within the model that don't explicitly relate to business logic can be moved out and repurposed in a decorator.
class UsersController < ApplicationController
  def index
    @users = UsersDecorator.new(User.all).latest_users
  end
end
The question of where and when to extract this logic, should be dictated by whether or not it falls outside of the responsibility of the object you might decorate it with. I'm a big believer in trying to adhere to Single Responsibility Principle, so this extraction makes a lot of sense.
We want to utilise SimpleDelegator rather than sub-classing our objects as we're not really interested in copying or exposing the base classes API, we just want to copy functionality.

Monday, 15 December 2014

12 Tips of Christmas - 5 Rendering a Hash with OpenStruct

12 Tips of Christmas - 5 Rendering a Hash with OpenStruct

OpenStruct is pretty fantastic, it let's you arbitrarily create attributes, which is fantastic if you have some dynamically generated hashes you need to work with. 
One of the really cool tricks you can do, is take that OpenStruct and render it, this is incredibly useful for sending out text messages, all you need is a little ERB.
to start, create your rendering object:
require 'ostruct'
require 'erb'

class SmsRenderer < OpenStruct  
  def render(template)
    ERB.new(template).result(binding)
  end
end
Now we have an object capable of rendering, all we need to do is give it a template, and a Hash with some attributes, like so:
def sms_template_render file_name, options = {}
  rendering_obj = SmsRenderer.new(options)
  template = File.open("#{Rails.root}/app/views/sms/#{file_name}.text.erb").read
end
Now you can use those lovely erb tags in your text message templates! 
If we just call the above method when passing content to your SMS send method, you'll get the dynamic text messages you're after.

Sunday, 14 December 2014

12 Tips of Christmas - 4 Null Objects

4. Null Object pattern

Sometimes you may find yourself co-opting nil, where we test to see if an object is nil and change the methods behaviour accordingly. Issues can arise right down to the view layer as we constantly check to see if a particular object is nil or not, i.e.: 
- if @membership.present?
  = @membership.plan
- else
  "Guest"
Enter the Null Object pattern.
A good use case for Null Objects are guest memberships, where we need them to conform to the regular membership API, but respond slightly differently.
class GuestMembership
  def active?
    false
  end

  def paid?
    false
  end

  def plan
    "Guest"
  end
end
Now, when we determine what membership is displayed, we make that decision not in the view, but in our model, or other class. This means our view can now look like this instead:
= @membership.plan
The downside to this pattern, is that you now need to maintain two sets of API's, but used sparingly, I really like how this enables me to pull logic out of views and even models, where I query to see if an object exists or not.

Saturday, 13 December 2014

12 Tips of Christmas - 3 Wrap instantiation inside a class method

3. Wrap instantiation inside a class method

Quite often I find myself when creating report objects, wanting to do the following:
@report = Report.new(params)
@report = @report.report()
Why not cut to the chase, by creating a report class method, that returns your shiny instantiated report for you:
class Report

  def self.report(params)
    report = self.new(params).report()
  end
end
Now we can simply call the following, whenever we want a new instance of our report:
@report = Report.report(params)
Much easier.

Friday, 12 December 2014

12 Tips of Christmas - 2 Virtus

2. Use Virtus in your form objects

I love form objects. Stripping away unwanted complexity in our models and housing them in nice neat little packages of code is amazing. Virtus gives me a little extra boost by doing alot of the coercions of my form attributes for me, allowing me to just get on with building the functionality I need. 
To get started, simply plug the virtus gem in your gemfile, and inside your form object (let's say its one of my favourites, a report) add the following:
class UserForm
  include Virtus.model

  attribute :joined_on, Date

  attribute :username, String
end
Now when I initialize the object with a params hash, I don't have to think about getters and setters, or cooercing Dates or DateTimes, I can just pass the params in and have Virtus do the hard work for me. 


Thursday, 11 December 2014

12 Tips of Christmas - 1 Use .map with Rspec

In the Christmas spirit of giving, I wanted to share with you 12 months worth of little tidbits that can help your Rails code. These are all little tips that I have been finding incredibly useful this year, and I'll be releasing one each day right up until Christmas Eve. 

1. Use map when comparing arrays in Rspec

Often when writing tests for a scope, or array equality, we'll end up with something like:
it { expect(User.active).to match_array([user_active, user_guest_active]) }
Of course, when that test fails, we end up with a lot of noise, as the output will give us the object in full. 
An easier way, is to use map to actually get out the information we're interested in:
it { expect(User.active.map(&:first_name)).to match_array([user_active, user_guest].map(&:first_name) }
This way, when we get our output back on our failing tests, it's much easier to determine what is actually wrong with our test as well as make it that much more obvious to the reader what they're looking for in return.


Sunday, 19 October 2014

Ember Objects, part 1

Ember Objects part 1

At the heart of Ember.js is ember objects, they're behind just about everything in the framework. If you're looking to improve your Ember know-how, understanding the Ember.Object is essential.
Ember.Object enables us to define new classes to work with, eg:
var Person = Ember.Object.extend({
    say: function(thing){
        alert(thing);
    }
});
We can also create a sub-class from any existing class by calling extend thus, our Person class above is simply a sub-class of Ember.Object.
This is reflected in Ember when we create our new models, we extend the existing Model class:
App.Person = DS.Model.extend({
  firstName: DS.attr('string'),
  birthday:  DS.attr('date')
});
If we wanted to create new instances of our Person object we utilise create instead, like so:
var tom = Person.create();
And then to create new instances of our model, we call createRecord, this is because a few extra bits are going on under the hood.

Get Set

If you're familiar with Ruby, you can override existing class methods here too, and like Ruby, we can access the underlying implementation of those class methods with a call to _super().
Ember objects make use of get and set as opposed to other frameworks for accessing and writing to its properties. It uses these methods to get around performance issues with multiple DOM updates and bindings. 
For example, when set is called, Ember will check to see if the value we're setting our property to is different to the existing value. If so, Ember knows to go ahead and trigger any updates to bindings, observers or computed properties. 
One additional feature with get is that it gives us access to unknownProperty, this is kind of similar to method_missing in Ruby, in that it allows our object to respond to requests it hasn't explicitly defined. 

Computed Properties

Computed properties are one of the major selling points of Ember. They can be setup like so:
var Room = Ember.Object.extend({
  width: null,
  height: null,
  area: function() {
    return this.get('width') * this.get('height');
  }.property('width', 'height')
});

var study = Room.create({
    width: 50,
    height: 10,
});

study.get('area') // 500

study.set('width', '10');

study.get('area') // 100

In the above example, we create a Room object that has a computed property of area, this computed property depends on width and height, so if one of those attributes changes, the value of area changes as a result.
Additionally, as opposed to say Angular, it also means in our views we can simply use the following:
{{#each}}
    Height: {{height}}
    Width: {{width}}
    Area: {{area}}
{{/each}}

No need for area(), which makes it much easier to update your application, should you require a computed property rather than an attribute.
You can also declare computed properties with some handy shorthand macros:

var Stark = Ember.Object.extend({
  winterIsComing: Ember.computed.equal('snow', 'ice'),

  direWolf: Ember.computed.and('wolf', 'large'),

  knowNothing: Ember.computed.not('knowledge'),

  knowNothing: Ember.computed.gte('bananas.length', 2),

  alive: Ember.computed.or('notFanFavourite', 'onTheWall')
});

You additionally don't have to supply the property declaration, which can make these easier to write. 
For more of these, see the documentation at Ember.js
So far we've covered how to create objects and instantiate them, how to work with attributes and computed properties. In the next post we'll be looking at Observers, some more complex computed property methods and bindings.

Sunday, 7 September 2014

Into to Ember and Ember CLI part two

Before we get started I'd like to give a huge thank you to @geoffreyd, he pretty much fixed all my code and set me straight on some really good best practices, not to mention spent an enormous amount of time putting up with my help vampirism. Additionally all the code for this post can be found on github
So far we've displayed our transactions on the page, but the amount property in our transaction model is just using a number to represent its value and we want to format it. So we're going to utilise a helper method so it's available across our views.
Helpers in ember are not dissimilar to helpers in Rails, particularly in this use case where we're planning on formatting an existing value. The main difference is by utilising ember, we can ensure our helper method updates as the values it depends upon changes.
Today we're going to register a new helper and convert our transaction amount to something resembling currency.
Ember CLI gives us a few options to achieve our goals, but in this case what we need is the following:
import Ember from "ember";
export default Ember.Handlebars.makeBoundHelper(function(amount, options){
  var amount = (amount/100).toFixed(2);
  var currencyAmount = "$"+ amount + "";
  return currencyAmount;
}); 
Insert the above into app/helpers/to-currency.js.
We use makeBoundHelper here instead of just helper or registerBoundHelper due to ember-cli. Ember-cli utilises the makeBoundHelper and makes it accessible to the ember container, this is outside the scope of this post, but if you'd like to dig a little into our applications internals within the console, run Transactions.__container__ within your browser.
The alternative to using this is using registerBoundHelper is that we'd need to take the extra step to define the helper function, then register our helper within app.js.
If we reload our application now we should see our transaction amount looking all pretty.

Routes

This is where most guides would start discussing Ember controllers and creating new transactions from within. We're not going down that path.
A Route in Ember represents state, which is represented with a url. As we're going to be manipulating data, and thus the state of the current page, we're going to store our actions relating to creating a new transaction in a route. To start though we need to specify a new route for the user to hit.
Router.map(function() {
  this.resource('transactions', { path: '/' }, function(){
    this.route('new'); 
  });
});
Here we have made /transactions/new available. This, by convention, will ensure Ember generates a TransactionsNewRoute, but we're going to create one of our own and start handling user input. To take user input we need a form, so let's create a new template for our transactions form:
<form {{action "createTransaction" on="submit"}}>
  <label for="transaction-name">Name:</label>
  {{input type="text" value=name id="name"}}

  <label for="transaction-amount">Transaction Amount:</label>
  {{input value=dollarValue id="comp-currency"}}

  <button type="submit">Save Transaction</button>
</form>
In Ember, if we don't assign a string to a value, that then becomes available to the context object within the template, bear this in mind when we start to look at our Route object later on.
So now that we have a form, let's make our form save our transactions with a Route:
import Ember from 'ember';

export default Ember.Route.extend({
    model: function(){
        return this.store.createRecord("transaction", { amount: 0, name: 'New Transaction' });
    },

    actions: {
      createTransaction: function(){
        var self = this;
        var transaction = this.controller.get('model');
        // TODO: set date format the way you want it.
        transaction.set('occurredOn', new Date);
        transaction.save().then(function(){
          self.transitionTo('transactions.index');
        });
      }
    }

});
Ok, there's a lot going on here, so lets break it down.
First up, we instantiate a brand new instance of transaction within the route, place it inside the model hook, and set it with some defaults using the createRecord method. This then sends the model to the controller, which if you remember from our first post talks exclusively to the template.
Next is our actions, specifically our createTransaction action. We can define actions within a Route object, a Controller or a View. To make understanding when to use which earlier, if you're dealing with data changes, use the Route, if you're dealing with changes within the object or collection, use a Controller, if you're dealing with interactions between views, use the View.
Within our createTransaction action, we retrieve our controller model, which seems a bit odd as we've defined it above. However we need to explicitly retrieve the model object as it stands from the controller, which as we reminded ourselves above, talks to the template. So here, we get the object as it stands in our form. We then save our new transaction, and make use of promises to return to the transactions index once complete.
There's one piece to puzzle missing, how does our dollarValue from our template, map to the amount on our model. The answer is in fact, in our model.

Computed Properties

One of Ember's most powerful features is computed properties.
It allows you to declare functions as properties on an object. When we create a computed property we defined the properties of the object it depends on at the end of the function, we can also use this to build a computed property that depends on another computed property. Awesome!
In our case below we have a computed property of dollarValue to map dollar values to cents in our database. When we use this property in our form, it sets the amount to the unformatted amount entered in. So when it comes time to saving the form, it automatically does all the adjustments for us.
var Transaction = DS.Model.extend({
    name: DS.attr('string'),
    amount: DS.attr('number'),
    occurredOn: DS.attr('date'),
    dollarValue: function(key, value, previousValue) {
        var currency;
        if (value !== undefined) {  // set was called
            var amount = Math.round(value * 100);
            currency = accounting.unformat(amount);
            this.set("amount", currency);
        } else {
          currency = this.get('amount');
        }

        // Get the value and return for either set or get.
        amount = (currency/100).toFixed(2);
        return accounting.formatMoney(amount, "");
    }.property('amount')
});

One more thing

There's just one thing we need to do, and that's instantiate an Ember Object Controller so our form gets all the attributes proxied through. So let's create a new TransactionsNewcontroller:
import Ember from "ember";

// Make TransactionsNewController an ObjectController,·
// so that it will proxy properties. !important
export default Ember.ObjectController.extend({

});

Monday, 25 August 2014

Intro to ember.js

Ember CLI

Ember is an opinionated JavaScript framework, it subscribes to the Rails philosophy of convention over configuration and makes it very easy to start building well structured, rich, client side applications.
Ember cli is a tool used to help build Ember applications, and similarly has a strong opinion on how you should structure and work with your code. Today's blog post is going to be using both of these tools.
As a Rails developer, the urge to utilise the ember-rails gem is pretty high, however I'm of the opinion that you should keep your Ember application separate from your Rails app and Ember cli provides too good a tool to ignore.
Ember cli is a command line tool thats based on the Ember App Kit project, it is meant to function as a replacement to Ember App Kit. It gives us a great project structure out of the box (not unlike when you generate a new Rails project with rails new), and a few handy generators.
To get started, please follow the instructions at ember cli, and come back when you're ready to proceed.
We're going to be making a simple budgeting application, we'll take incoming transactions, assign them a name, a date, and a price, and assign them to a category.
To start simply run ember new transactions this will create a new transactions folder and generate the application structure. Already we can run ember server from within our application and navigate to our ember app.
To help us identify what's going on in our application, we're going to navigate to ourapp.js file and add the following:
var App = Ember.Application.extend({
  ...
  LOG_TRANSITIONS: true,
  LOG_TRANSITIONS_INTERNAL: true
});

This will assist us in getting a better understanding of what's going on under the hood.

The Router

Next we're going to start setting up some of our routes within app/router.js. The Router in Ember, as opposed to individual route objects, is much like a router in Rails. The main point of difference between a router in Rails and a router in Ember is that a route in Ember represents any one of the possible states of your application, which in turn provides a url.
To start we're going to add our first real route, which will display an index of transactions:
Router.map(function() {
  this.resource('transactions', { path: '/' });
});

Note the addition of the path option, this tells Ember to render the transactions template when visiting the root path of your application.
When you give it a route like the above, it tells Ember that it needs an IndexRoute, aTransactionsRoute and a TransactionsIndexRoute as well as controllers and templates following the same naming convention eg TransactionsIndexController andtransactions/index.
What Ember will do for you is generate those required routes, controllers and templates for you, so you can continue to develop your application until you need to override the default behaviour within those files.

The Model

All this routing needs a model to back it. Once again there's some similarities with Rails here so go ahead and create a model in app/models/transaction.js:
import DS from 'ember-data';

var Transaction = DS.Model.extend({
  name: DS.attr('string'),
  amount: DS.attr('number'),
  occurredOn: DS.attr('date')
});

Transaction.reopenClass({
  FIXTURES: [
  {
    id: 1,
      name: "GYG Burritos",
      amount: "1200",
      occurredOn: "12/04/2014" 
  }
]});

export default Transaction;

We've imported Ember Data, using the import statement at the top of the page. Ember cli provides us the mechanism for this as it uses ES6 modules. How this happens is a bit beyond the scope of this post, however ES6 modules are not fully supported yet, so Ember uses some crafty magic to make these available to use across the board.
In addition we have also defined our model, given it some attributes with different types and created an initial fixture for us to work with. To utilise fixtures, open upapp/adapters/application.js and add the following:
import DS from 'ember-data';
export default DS.FixtureAdapter.extend();

This says to Ember to utilise fixtures as our data source.

A Route

Now we want to make sure when we visit the index of our application we see our list of transactions. To accomplish this, we need to use a route. A route helps define what model should be available to your template when we view our transactions, this is achieved with the model hook in the route.
For our first route, we're going to create the TransactionsRoute inapp/routes/transactions.js
import Ember from 'ember';
var TransactionsRoute = Ember.Route.extend({
  model: function(){
    return this.store.find('transaction');
  }
});

export default TransactionsRoute;

Note the import of Ember, this is another Ember cli requirement that whenever we need ember-data or Ember in our files, we import either of those depending on our needs.
We also return our available transactions in our model hook

A template

We've setup our routes, our model and some initial data, now we need to display our transactions. So we will setup a transactions template in app/templates/transactions.hbs
<ul>
  {{#each}}
    <li>{{name}} {{amount}} {{occurredOn}}</li>
  {{/each}}
</ul>

The each here loops through an array of records, and although we only have one transaction to return, this will ensure our data is displayed correctly and will support additional records when we progress to adding them.
Now if we run ember server from our terminal we should see our fixture data displayed for us.
I should take a step back here and explain that even though ember knows to go and find the transactions template, it's the {{outlet}} statement in app/templates/application.hbs which enables the template to bubble up to be displayed.
We'll be utilizing this concept further when we add additional features, but for now our list of transactions can remain in our transactions template.
We'll continue on from here in the next blog post, but for now if you'd like to take a look at the source code, you can find it on github

A Note on Controllers

We didn't look too closely at Ember Controllers in this post, this will come up in the next post in the series, however ember has created all the controllers we have needed and so far we haven't had to extend their base functionality from what we already have.