Before getting deeper into some technical [Cangaroo][1] guide I wanted to give
some more insights about how **Cangaroo** was born. This is the story that tells
how the death of a *SaaS* gave us the opportunity to create a brand new
**open-source** project.

One of our clients has many Spree stores, almost ten and all of these stores
share the following features:

* send order information data to a third-party application;
* receive stock updates from that application;
* receive shipments updates from that application;
* send an email to the customer service when an order is considerd risky.

In the first place you can think that the easier way to accomplish this is
updating each store code to "speak" directly with that application in order to
send and receive data. This introduces a lot of code duplication and is really
error prone.

Another solution could be to create a gem that is included in all stores.
At the beginning it looked like a good solution but what happens if you had to
add another feature? For example what if you have to send an email for each new
customer? At this point you had to:

* update the gem to include this feature;
* update the new ref of the gem into the `Gemfile` of each store;
* run tests (often duplicated) on each store;
* deploy each store.

Now, it can seems like reasonable approach but think at each time you find a bug
and you have to replicate all the steps above. It's time consuming and we love
to use our time to build new features instead of repeating actions mechanically.

Another problem comes when any third-party application endpoint has some
problem, like a downtime. In order to don't loose data you need to add a queue
system to retry the request. Of course each store needs its own queue system
with all performance related stuff that increases infrastructure costs.

With the primary aim to solve this scenario the Spreecommerce created a Saas
named Wombat, whose claim said:


> "Wombat is your store’s integration platform; connect any store to any
service. Wombat gets you up and running in minutes, no custom code required.".

With Wombat an user can configure what to do on a particular event, with a UI
interface, for example you can setup something like


```
When a new Order comes in from the store A, send an email to the customer and
tweet an happy face.
```
or

```
When a new Order comes in from any store, send an email to the customer
service.
```

Wombat talks with external services API using [integrations][2] that
live in the middle between Wombat and third-party services. Each external
service has its own integration, for example there are integrations for
Mailchimp, SalesForce, etc.

Everything was working fine until the day the Spreecommerce was aquired,
Wombat died and the source code was released only to customers.

At this point we had to decide how to go ahead, and the alternatives were:

1. to take Wombat source code and to host it on our servers;
2. to reintroduce features back into the stores with all the issues described
   above;
3. to create an alternative system that replaces Wombat behavior.

Accordling to one of our cool clients, we decided to go with the latter and, since
we strongly believe in open-source we also decided to publicly release it.
**Cangaroo** was born.

**Cangaroo** is named after the Kangaroo animal, which I've seen together with a
real wombat during one of my trips across Australia. Unfortunately Kangaroo gem
name was already taken so we changed it a bit.

![Wombat and Kangaroo](https://cdn.sanity.io/images/kqgmf0g2/production/cc6571173aaf14682ce59d847f829ffb80add623-770x578.jpg?fit=clip)
*A picture with a Wombat and a Kangaroo taken by me in Australia.*

**Cangaroo** is a Rails Engine that you can mount on a new or exsisting Rails
application. One cool thing about this project is that it uses the same API
specification of Wombat so we don't have to change anything into our client
stores repo continuing to use the code that was acting as an adapter for Wombat
(via the `spree_wombat` extension).

The main differences from Wombat are:

* **Cangaroo** is designed for developers, not for endusers.
As a developer I prefer to use my editor to configure behaviors instead of
clicking around a web page; this is why it's developer friendly,
it doesn't have a UI like Wombat, everythings is done via code.
* **Cangaroo** doesn’t store data like Wombat did, it just receives data and
decides what to do based on how it's configured.
* Lately Wombat added the possibility to also schedule recurring requests to
external services in order to receive data without having an event that triggers
that call. For now **Cangaroo** doesn't have this feature but it's something
we are planning to add as soon as possible.

This is the whole story about **Cangaroo** and why we decided to create it.
To learn more you can take a look at [README][1] and stay in touch with our
blog. We are planning to post soon a tutorial that explains how to setup
**Cangaroo**, integrate it into a spree/solidus store using the
[spree_wombat extension][3] and one of the existing Wombat integrations.

[1]: https://github.com/nebulab/cangaroo
[2]: https://github.com/wombat
[3]: https://github.com/spree/spree_wombat
[4]: https://github.com/spree/spree_wombat#push_url

The birth of a Cangaroo

This year World IA Day took place also in Pescara and we had the honor to sponsor this great event. It was an opportunity for part of our team and all the attendees to celebrate Information Architecture (IA), but also to learn and to discuss together about this discipline.

## What is the WIAD?
The World IA Day is a one-day annual conference hosted by local organizers in many locations across the world with the purpose of spreading the practice of IA. In Pescara the event was organized by [Blikke](http://blikke.com/) and [Digital Borgo](http://www.digitalborgo.com/) and it was amazing to see so many people attend and show interest in this field even in a relatively small reality. This kind of events lays the foundations to build and grow up solid local communities.

## What is Information Architecture?
As explained by [The Information Architecture Institute](http://www.iainstitute.org/):

> "Information architecture is the practice of deciding how to arrange the parts of something to be understandable."

In other words, in a world full of information a good IA helps people to easily find what they’re looking for.

## Highlights
The first of the 8 speakers to talk was Luca Rosati, one of the founders of the Italian association of information architects. He talked about inconsistency between the multitude of channels and devices people are using everyday and how the IA could help companies avoid this problem designing with omnichannel strategy in mind.

In the next talk, Andrea Violante, Design Lead at NiEW Design, spoke about the usability gap between products and services we use in our spare time and tools we use at work. This gap is even more pronounced in the industrial automation field but recently, with the help of IA and User Experience, we’re moving towards a user-centered design. In fact we’re approaching to the fourth industrial revolution (or Industry 4.0).

During her talk, Yvonne Bindi, Freelance Information Architect, explained us the importance of words as powerful interfaces and how we can use them to guide the user towards the achievement of his goals.

Vincenzo Di Maria and Claudia Busetto from Commonground People and Architecta told us about their experience in working as professional designers in Sicily through the process of a project their worked on.

Hoang Huynh and Valeria Adani explained that designing a tourist experience is hard because it’s difficult to identify every variable a user will consider when choosing a service instead of another.

And yes, we also played with LEGO® bricks with Alessandra Cianchettini, Innovation Coach at Cocoon Projects, who explained us in the last talk how to collect useful informations through the LEGO® SERIOUS Play® methodology.

![LEGO® SERIOUS Play®](https://cdn.sanity.io/images/kqgmf0g2/production/71fe2a79abad879dde8212d3775a9223203fab9c-770x380.jpg?fit=clip)

The whole conference was really inspiring, fun and helpful for UX and IA practitioner of any level. Information Architecture is important in these days more than ever and at Nebulab we know that a well-structured content is crucial to create a good user experience.

Every designer, but also non-designers, should known more about this discipline, so I invite you to attend the next year World IA Day in a location near you.

Here is the video of the event (Italian only):

* [Part 1](https://www.youtube.com/watch?v=ROU9WPg_m3w)
* [Part 2](https://www.youtube.com/watch?v=yfvBJesSnKU)

World IA Day 2016 Pescara

In order to let the creativity to flow, we decided to organize an hackathon
involving all the team.
Nebulab believes in side projects, they help to form the junior members
and grow the seniors, and put them in front of new challenges such as the
exploration of fresh technologies.

**But... what to do?** Perhaps the embryonic idea was already present in the
head of some of us...recently a recurring Slack topic is the future of the
Spree platform, on which, essentially, all our projects are based and whose
support had been declared abandoned by the original core team.
This event resulted in the birth of a community for the development
of a new ecommerce platform, [Solidus](https://solidus.io/), starting from a Spree fork.
The discussions on the [Solidus Slack channel](https://slack.solidus.io/) have
shown the need to quickly search and access the extensions developed for this
new platform.
Then it was a short step. A small webapp, easy to develop in a limited space of time,
a Solidus extensions search tool using GitHub API.
Given that everybody was interested in Javascript frameworks, the choice came down to Ember.js. Being known for a framework that increases developer productivity, we thought it would be great for a 1-day hackaton.

![Coffe Break](https://cdn.sanity.io/images/kqgmf0g2/production/c189632a02839d69d004c0c20f2081ffdcb4ccc5-770x350.jpg?fit=clip)

After a short but intense brain-storming on Ember.js structures and a coffee
break, we started coding, dividing us in four groups.

- Communication with GitHub API
- Search Form
- Interface Design
- Frontend development

Taking inspiration from the [biologic radar used in Metal Gear Solid](https://metalgear.wikia.com/wiki/Soliton_Radar)
, we named it *Soliton* and, once created the repository, the rule was: push on it as often as possible!

Referring to [Ember.js Guides](https://guides.emberjs.com), we've easily built the
frontend and backend application skeleton code while in parallel the style support tools were configured (with [bourbon and neat as usual](https://nebulab.com/blog/neat-a-semantic-approach-to-grid/)).
In the meantime Davide, our designer, was free to imagine and draw the user interface.

![Soliton Interface](https://cdn.sanity.io/images/kqgmf0g2/production/cb4ec13e01d3687ed330949c0d17b925d8df8f4e-770x305.jpg?fit=clip)

A side-project carried out in the informal context of an hackathon day has,
without any doubt, the positive side-effect to strengthen the union of the team,
that by our nature can be distributed anywhere in the world. A great opportunity to
work side by side and having a few laughs!

See y'all the next hackathon!

![Working on Soliton](https://cdn.sanity.io/images/kqgmf0g2/production/8a39d998fb3dd3cca793484759fc652537a5accf-770x408.jpg?fit=clip)

The Soliton Hackathon

Spree or Solidus? Which OSS project Nebulab, as an agency involved in
Ruby on Rails eCommerce development, should invest on? This blog post
tells the story about what's happening inside our agency in choosing
where to put more effort.

## Spree and Nebulab

Nebulab has proudly been one of the first company that adopted Spree. In fact
we are using it since version 0.30. We always did our best contributing
actively to the project and its extensions, attending almost all SpreeConf
around the world and supporting the community via the Spree Mailing List.

We strongly believed in this project that we used for 100% of our eCommerce
customers, often recommending them to migrate to Spree from other platform,
like Magento or custom Ruby on Rails eCommerce applications.

We have also been one the first company that applied to be a
[Spree Solution Partner][spree solution partners]. This partnership allowed us
to give something back to the project and take a lot of contacts with clients
all over the world.

On October 28th Spree announced that [they will no longer
maintain the OSS project](https://spreecommerce.com/blog/future-of-spree-oss).
The main reason is that the Spree company has been acquired by another
bigger company, First Data.

It's easy to imagine our feelings hearing that our favorite OSS project
would have a so drastic change in its maintenance and community management.

Bad news never come alone. **[Wombat][wombat]**, an
integration platform built from Spree company that we were using for some
of our clients, would be discontinued soon. Fortunately, according with one of
our cool customers which was extensively using that service, we developed
[Cangaroo][cangaroo], an Open Source alternative to Wombat, that we are
currently using successfully in production.

## Solidus

Months before this event, a group of developers from
[Bonobos][bonobos], one of the
[biggest online retail store][bonobos ipo] in the United States and
[Stembolt][stembolt], a Canadian web development firm, forked
Spree because they started to diverge from the direction Spree was taking.
They called the project [Solidus][solidus], naming it after an
[old Roman coin][solidus coin] and the
[SOLID principles of Object Oriented Design][solid principles].

Having more activity we naturally started taking a look at this fork,
understanding its principles and its different approach that we started
to appreciate and share.

If you are interested in differences between the two platforms
[this article][spree vs solidus] is a great resource.

Here's a list of stuff that we like about Solidus:

### A Solid Roadmap

Solidus guys decided to put focus on fixing and improving current codebase
instead of adding new features that are probably unnecessary for many stores.

Here you can find the full
[Solidus Future Plans][solidus future plans].

We trust developers involved in the Solidus project, we can see on the
[Solidus GitHub Repository][solidus github] that they are great in what they do
and lately they also have emerged for their attention for security issues.

### Top Priority to Code Integrity

Solidus is trying to get rid of stuff that doesn't look clean like the
improper use of `class_eval`. This is not only a question of code
style but ensure it's easier to customize your stores, your extensions and
to update Solidus from one version to the next one.

But why **class_eval** is not a good practice?

Of course it depends by the situation but in general using class_eval you
are re-opening the general class definition; technically this is not
an inheritance and this means that into the re-opened class you cannot use
`super` to replicate a previously defined method behavior. For the
sake of better understanding this concept, let's make a simplified example:


**Spree::Stock::ShippingRateSorter** is a class defined into the solidus
core that defines how to sort shipping rates.

```ruby
# Solidus Core

# app/models/spree/stock/shipping_rate_sorter.rb
module Spree
  module Stock
    class ShippingRateSorter
      attr_reader :shipping_rates

      def initialize(shipping_rates)
        @shipping_rates = shipping_rates
      end

      def sort
        shipping_rates.sort_by(&:cost)
      end
    end
  end
end
```
Now, in your store or extension, suppose you want to change how to sort
those elements. Specifically we want to reverse the order of shipping rates.
We used to write in our stores something like:

```ruby
# Our App or Extension

# app/models/spree/stock/shipping_rate_sorter_decorator.rb
module Spree
  module Stock
    ShippingRateSorter.class_eval do
      def sort
        shipping_rates.sort_by(&:cost).reverse
      end
    end
  end
end
```

This is not terrible, at least until the default way shipping rates are sorted
changes into core, and our code is no more compliant with it making it a mess
to update solidus to more recent versions.

Often, the solution to this kind of problem is using **super** to inherit the
behavior of core code in order to make our extensions less dependant to that
code.

Solidus is proposing to change this `class_eval` over-usage, moving to a more
clean way to extend stuff.

```ruby
# Our App or Extension

# app/models/spree/stock/custom_shipping_rate_sorter.rb
module Spree
  module Stock
    class CustomShippingRateSorter < ShippingRateSorter
      def sort
        super.reverse
      end
    end
  end
end

# config/initializers/spree.rb
Spree::Config.shipping_rate_sorter_class = Spree::Stock::MyShippingRateSorter
```

Awesome, isn't it?

### Forked from Spree 2.4

Solidus has been forked from Spree 2.4, and now Spree is at 3.0. The main change
between these versions is the introduction of **Twitter Boostrap** into both
frontend and backend. That wasn't a good idea in our opinion for several
reasons:

- updating would mean changing frontend code of all stores we were working on;
- 90% of our clients are not interested in bootstrap themes but a
custom frontend style, so often it would probably be more work to
remove it than to adapt the spree frontend to that specific store needs;
- in our vision the frontend HTML should not include front-end framework class
names but semantic ones that represents what's inside that specific element.

### Active Community

Lot of friends and contributors that we did know on the Spree community have
already joined the Solidus community. In fact, in the
[Solidus Slack channel][solidus slack] there are already 400+ developers
that discuss, support each other and design together the future Solidus moves.

We also love conferences, and we look forward to attend
[Solidus Conf 2016][solidus conf] in Toronto, an opportunity for us
to learn, to better understand the Solidus goals and to meet community members
and clients in person.

## Our choice

Our plan is to start all new stores using Solidus but to stay with Spree for
the majority of those already developed. We think that this is the decision
that makes more sense, also because Spree has new maintainers now and this
should ensure quick response to any security issue that could come out.

Even if Spree seems to be reborn with a
[new core team and roadmap][new spree core team],
we think that there's still a lot to do for Spree to recapture our interest
and we currently feel comfortable with the Solidus approach, which we hope to
contribute to as much as we can.


[bonobos]: https://bonobos.com/
[bonobos ipo]: https://pando.com/2014/07/06/bonobos-raises-another-55-million-and-aims-for-an-ipo-all-in-spite-of-being-ecommerce/
[cangaroo]: https://github.com/nebulab/cangaroo
[new spree core team]: https://spreecommerce.com/blog/spree-roadmap-announcement
[solid principles]: https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)
[solidus]: http://solidus.io/
[solidus coin]: https://en.wikipedia.org/wiki/Solidus_(coin)
[solidus conf]: http://conf.solidus.io/
[solidus future plans]: https://github.com/solidusio/solidus/milestones
[solidus slack]: http://slack.solidus.io/
[solidus github]: http://github.com/solidusio/solidus
[spree solution partners]: https://spreecommerce.com/solution_partners
[spree vs solidus]: http://bluestout.com/blog/spree-vs-solidus-ecommerce-platforms/
[stembolt]: https://stembolt.com/
[wombat]: https://github.com/wombat

Why Solidus?

As a result of a **Responsive** approach in **Web Design** and therefore to
the need to create adaptable layouts suitable from different devices, has become
usual, I would say almost fundamental, to use a good Grid System.

A **Grid System** is nothing but a system of `columns` separated by `gutters`
according to which our layout's contents are distributed.

![Grid-System](https://cdn.sanity.io/images/kqgmf0g2/production/1f9e540381ada431e7f7e1c4be772337e232eb42-770x300.jpg?fit=clip)

This system helps us not only to handle layout's elements proportions and
positioning in a more concrete way, but it helps us especially in the task of
rearranging our contents according to the size of the screen, making them
accessible from any device.

A *Grid System* can be *Fluid* or *Fixed*, depending on how columns' size is
computed (if `px` or `%`), but the common trend is to use **Fluid Grid**, that
allow us to manage dimensions according to a proportional system and so it's
more easily adaptive.

Resources about grids available online are so many and have been conceived many
*frameworks*, each with its advantages and faults, but anyway a lot to choose
from.

## Choose a Grid System or D.I.Y.?

Many not being satisfied with 'limits' that the choice of a system can reach,
decided to create a Grid System themselves.
Surely it's not a choice to blame, we know that many developers are more at ease
using their own resources, however creating, optimizing and improving a
framework requires a lot of time and effort.

Then an important point to keep in mind is related to *teamwork*:
in a team often happens that you have to make changes on an existing project,
therefore it's very important to have a well detailed documentation, that a
custom resource doesn't have.

We should also consider all the benefits we would have choosing an *open-source*
project, in fact its being collaborative and open to improvements by many users,
makes it a real great choice.

## Popular Grid Systems overview

Often our needs change depending on time and the project we're working on, then
in the course of our job we focused on several **frameworks**, even so we tried
many before getting to a satisfying choice for us:
lately in fact we're using [Neat] (http://neat.bourbon.io/) for our projects, in
addition to [Bourbon] (http://bourbon.io/), a useful and powerful
*Mixin Library* on which it has been developed.

But before we talk about *Neat*, let's see some **Grid System** we used:

#### Bootstrap

[Bootstrap] (http://getbootstrap.com/) it's surely the most popular and one of
the first *frameworks* designed. In addition to a Responsive Grid System it has
a wide infrastructure full of utilities such as CSS components, global styles
for HTML elements and a series of jQuery plugins that may be included
individually or all together. So a very rich base to start.

Talking about its own *Grid System*, it has a structure like this:

```html
<div class="container">
  <div class="row">
    <div class="col-sm-6">...</div>
    <div class="col-sm-6">...</div>
  </div>
</div>
```

Columns should be positioned inside a `.row` and this one inside a `.container`.
Classes for columns follow this convention:

```html
<div class="col–{xs/sm/md/lg}–{numberOfColumns}">
```
Where `{xs/sm/md/lg}` respond to devices:

```
  xs = phones
  sm = tablets
  md = desktops
  lg = large desktops
```

So in the example above we have two `div` by 6 columns starting from tablet
devices `(sm = tablet)`, instead in mobile these will cover the entire row.

#### Skeleton

[Skeleton] (http://getskeleton.com/) compared to Bootstrap is less provided, but
not for this less helpful: besides the Responsive Grid, it provides a set of
predefined classes for our tables, forms, buttons and lists.

```html
<div class="container">
  <div class="row">
    <div class="one column">...</div>
    <div class="eleven columns">...</div>
  </div>
</div>
```

The grid follows a standard similar to Bootstrap with a `.container` and a
`.row` and this rule for columns classes:

```html
<div class="LiteralNumberOfColumns column/s">
```

So it has a different way for naming classes, non-numeric but literal this time:
maybe it's more intuitive and immediate compared to Bootstrap but it
has not the same potential so they are not to compare (in fact there's no
definition through classes between devices).

#### Foundation

Also [Foundation] (http://foundation.zurb.com/) can be a useful tool, it
provides us also Components and Plugins and going on with versions have
increased and become many.

Let's talk about Grid:

```html
<div class="row">
  <div class="small-6 large-5 columns">...</div>
  <div class="small-6 large-7 columns">...</div>
</div>
```

Also here there's a `.row` that contains columns and to define the width of a
column we do:

```html
<div class="small/medium/large - numberOfColumns columns">
```

Here `small/medium/large` refers to the device we are working on, and the
number, for example `6`, to the amount of columns that it must cover.

## Bourbon Neat

Nothing to say about these frameworks, but one of the first things that concerned
us about [Neat] (http://neat.bourbon.io/) is the different approach used to
define the Grid:

> “ Neat is a semantic grid framework „

**Neat** in fact, is built entirely with `Sass`, so it allows us to separate
the markup from the grid definition, which occurs in stylesheets, making a more
clean and simple code, but above all, more maintainable:
in fact we could completely upset the style without changing each class in the
html page.
It also helps us in the aim to create a **semantic** markup because we won't have
to put additional classes to declare grid.

###### html:
```html
<article>...</article>
<article>...</article>
```

###### scss:
```scss
article {
  @include span-columns(6);
}
```

It's a helpful approach even if we consider methodologies for code structure and
organization like [OOCSS] (https://github.com/stubbornella/oocss/wiki), [SMACSS]
(https://smacss.com/) or [BEM] (https://en.bem.info/);

This kind of system in fact, enables us more easily to:

- separate *structure* from *presentation*
- assign clear and meaningful *classes names*, much possible descriptive of their
content
- built an architecture made from potentially *"reusable" blocks*

Also since the modular approach will bring us to have extended class names,
sometimes also formed by compound words (for example `header__logo`, and in the
case of *SMACSS* also of additional *state-rules* like `tab is-collapsed`), to
put other classes for grid won't surely ease the understanding and the
readability of our code.

We have to point out that lately also in the latest versions of *Bootstrap*,
*Foundation* and others there's an option for using this approach, but it seems
like an adjustment rather than the primary trend, in fact the complete
documentation is focused on predefined classes to be included directly in the
html.

The semantic approach is used also in the naming of **mixin** and **variables**
that it provides us, which are in my opinion intuitive and well defined.

Let's see basic mixins to build our **Responsive Layout**:

### Mixins

##### Outer-container

```scss
@mixin outer-container($local-max-width: $max-width) { ... }
```

The mixin `outer-container` is used to define the main container in which other
elements will be placed;

###### html:
```html
<section class=”main-articles”>
  <article>...</article>
  <article>...</article>
</section>
```

###### scss:
```scss
.main-articles {
  @include outer-container(1280px);
}
```

If we look at generated css we see that its purpose is to center the content
with `margin-left` and `margin-right`, set a `max-width` and "clean" any `float`
with another mixin (`@include clearfix`, a *Bourbon* mixin). The `max-width` is
a value that can be defined in a variable, as we'll see later.

###### Css Output:

```css
.main-articles {
  max-width: 1280px;
  margin-left: auto;
  margin-right: auto;
}

.main-articles:after {
  clear: both;
}
```

##### Span-columns

```scss
@mixin span-columns($span, $display: block) { ... }
```

With `Span-columns` we can decide the number of columns that a single element
must cover and optionally its display property.

###### html:
```html
<section class=”main-articles”>
  <article>...</article>
  <article>...</article>
</section>
```

###### scss:
```scss
.main-articles {
  @include outer-container;

  article {
    @include span-columns(6);
  }
}
```

![Span columns](https://cdn.sanity.io/images/kqgmf0g2/production/0684f1fed457d96e49c12a1606316f68299f98f6-770x400.jpg?fit=clip)

##### Shift

```scss
@mixin shift($n-columns: 1) { ... }
```

`Shift` allows us to move an item by columns, then assuming that we want only an
`<article>` positioned in the middle:

###### html:
```html
<section class=”main-articles”>
  <article>...</article>
</section>
```

###### scss:
```scss
.main-articles {
  @include outer-container;

  article {
    @include span-columns(6);
    @include shift(3);
  }
}
```

![Shift](https://cdn.sanity.io/images/kqgmf0g2/production/e0589496a4316750dea2293a40ce58e708c9e4c5-770x400.jpg?fit=clip)

### Variables

Also we could change grid properties by setting some **variables**:

```scss
$grid-columns: 12 !default;
```

`Grid-columns` specifies the number of columns in the grid: by default is 12 but
this value can be changed overwriting this variable or, as we'll see later,
inside a mixin where we could also choose a different number of these in each
`breakpoint`.

```scss
$max-width: 1280px;
```

`Max-width` sets the maximum size of the grid; by default it's set in `em` but
we can insert it also in `px`; so every `outer-container` will take this maximum
size, even if you can change it separately for each container through the
`outer-container()` mixin.

```scss
$visual-grid: true;
```

A nice feature then, is related to the `visual-grid` variable, that set to
`true`, shows a real grid on the background of our layout, something very
useful in development.

Later it's possibile to change its color, arrangement (below or above our
contents) and opacity:

```scss
$visual-grid-color: #eee !default;
$visual-grid-index: back !default;
$visual-grid-opacity: 0.4 !default;
```

Finally we mast talk about **Media queries**, that are fundamentals for
*Responsive Design*; as you can see we can define them inside a variable and
also specify the number of columns we want to create for each of these (in the
ex.: 12 12 4):

```scss
$desktop: new-breakpoint(min-width 960px 12);
$tablet: new-breakpoint(max-width 959px 12);
$mobile: new-breakpoint(max-width 767px 4);
```

We can recall these variables inside the `media()` mixin whenever we want to
make a change depending on a breakpoint:

```scss
.main-articles {
  @include outer-container;

  article {
    @include span-columns(6);

    @include media($mobile) {
      @include fill-parent;
    }
  }
}
```

In the last example we used `fill-parent` mixin, that makes an element fits the
entire size of its container `div`. If we set a `shift` before to this element,
in addition to `fill-parent` we have to reset it with `shift(0)`.

```scss
@include shift(3);

@include media($mobile) {
  @include fill-parent;
  @include shift(0);
}
```

Therefore in mobile we'll have a 4 columns grid and each `<article>` will fill
its container:

![Mobile](https://cdn.sanity.io/images/kqgmf0g2/production/c9148f7c2db9bbf798cb92835ea4b1c661ac01c4-770x818.jpg?fit=clip)

As you can see **Neat** gives us very useful tools to simplify and help our
workflow: with few lines of code and by intuitive keywords that are easy to
remember, we have a strong foundation to develop our *Responsive Layout*,
creating a clean and readable code.

Here we talked about just a part of its structure, if you're interested and you
want a more detailed view you can look at its [Documentation]
(http://thoughtbot.github.io/neat-docs/latest/), in our opinion also this very
simple and well explained, and furthermore here is a [Codepen]
(http://codepen.io/ritaD86/pen/XXzzVB) with the example in action.

Neat - A semantic approach to Grid

Here at Nebulab we love to hack with new exciting technologies, that's why we dedicate
20% of our work time for study and open source contribution. In this post we'll cover authentication made
with Rails, [JSON Web Tokens](http://jwt.io/) and [ReactJS](https://facebook.github.io/react/).

### How JSON Web Token works
_JSON Web Token_ (aka _JWT_) is a useful standard becoming more prevalent, it allows you to sign information with a signature that can be verified at a later time with a secret signing key. It is a perfect solution for single page apps, avoiding the use of sessions to allow communication between a client (not necessarily a browser) and a server. In its simplest form, JWT is composed by three URL encoded parts:

* **Header:** it represents the metadata for the token and contains at least the type of the signature and/or encryption algorithm
* **Claims:** is the information you want to sign
* **JSON Web Signature (JWS):** it is composed by the header and the claims digitally signed using the algorithm specified in the header

Here is a basic example of how to generate a JWT with plain Javascript:

```javascript
// Header
var header = {
  "alg": "HS256", // algorithm used for the  signature
  "typ": "JWT"    // the type of token
};

// Claims
var claims = {
  "id": "1234567890",
  "name": "John Doe",
  "email": "johndoe@example.com"
};

// Signature
var payload = base64UrlEncode(header) + "." + base64UrlEncode(claims);
var signature = HMACSHA256(payload, 'my_secret');

// JWT
var myJWT = payload + "." + signature;
```

#### The server side
We're using Rails for the server side part, so we installed the [jwt gem](https://github.com/progrium/ruby-jwt) and wrote some code to integrate it inside our app:

```ruby
# lib/json_web_token.rb

class JsonWebToken
  class << self
    def encode(payload, exp = 24.hours.from_now)
      payload[:exp] = exp.to_i
      JWT.encode(payload, Rails.application.secrets.secret_key_base)
    end

    def decode(token)
      body = JWT.decode(token, Rails.application.secrets.secret_key_base)[0]
      HashWithIndifferentAccess.new body
    rescue
      # we don't need to trow errors, just return nil if JWT is invalid or expired
      nil
    end
  end
end

```

##### Authenticating the user with email and password
At this point, we needed two workflows: the first one only happens the first time the user authenticates. Once the user's identity is verified, the JWT is created. **Note:** We used [simple_command](https://github.com/nebulab/simple_command) gem to manage this part, it helped a lot in keeping Rails controllers and models very slim.

```ruby
# app/commands/authenticate_user.rb

class AuthenticateUser
  prepend SimpleCommand

  def initialize(email, password)
    @email = email
    @password = password
  end

  def call
    JsonWebToken.encode(user_id: user.id) if user
  end

  private

  attr_accessor :email, :password

  def user
    user = User.by_email(email)
    return user if user && user.authenticate(password)

    errors.add :user_authentication, 'invalid credentials'
    nil
  end
end
```

Followed by the controller that uses it:

```ruby
# app/controllers/authentication_controller.rb

class AuthenticationController < ApplicationController
  skip_before_action :authenticate_request

  def authenticate
    command = AuthenticateUser.call(params[:email], params[:password])

    if command.success?
      render json: { auth_token: command.result }
    else
      render json: { error: command.errors }, status: :unauthorized
    end
  end
end
```

##### Authentication on following requests
The second part is related to authenticating the requests from client using the JWT we generated during user authentication:

```ruby
# app/commands/authenticate_api_request.rb

class AuthenticateApiRequest
  prepend SimpleCommand

  def initialize(headers = {})
    @headers = headers
  end

  def call
    user
  end

  private

  attr_reader :headers

  def user
    @user ||= User.find(decoded_auth_token[:user_id]) if decoded_auth_token
    @user || errors.add(:token, 'Invalid token') && nil
  end

  def decoded_auth_token
    @decoded_auth_token ||= JsonWebToken.decode(http_auth_header)
  end

  def http_auth_header
    if headers['Authorization'].present?
      return headers['Authorization'].split(' ').last
    else
      errors.add :token, 'Missing token'
    end
    nil
  end
end
```

And again, the controller part:

```ruby
class ApplicationController < ActionController::API
  before_action :authenticate_request

  attr_reader :current_user
  helper_method :current_user

  private

  def authenticate_request
    @current_user = AuthenticateApiRequest.call(request.headers).result

    render json: { error: 'Not Authorized' }, status: 401 unless @current_user
  end
end
```

As you can see it is very simple and similar to session based authentication. The only difference is the fact that we are dealing with a _token_ instead of a cookie.

#### The client side

Of course, the browser doesn't know how to deal with JWTs and thus, it needs to store the JWT for its subsequent requests. To make this possible, we relied on a relatively recent feature of HTML5 called [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API) that allows to store key/value pairs on the browser. For the Javascript part we chose ReactJS, but keep in mind that this is possible using plain Javascript and we just wrapped the necessary code inside our app.

##### Setup
Before proceedeing it's important to highlight the fact that we _skipped_ the default Rails [asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html) and relied on a stack based on [NodeJS](https://nodejs.org/), [Browserify](http://browserify.org/) and [Gulp](http://gulpjs.com/) with a bunch of plugins. The main reason is the fact that the NodeJS (and [npm](https://www.npmjs.com/)) stack is easier, faster and kept updated, without having to deal with _wrapper_ gems. To adapt your rails app is quite easy, just edit `config/application.rb` and disable the javascript asset generator:

```ruby
# ...

module JWTReactApp
  class Application < Rails::Application
    # more configs...

    config.generators do |generate|
      # DISABLE ASSET GENERATORS
      generate.javascript_engine false
      # more generator configs...
    end
  end
end

```

Setup the NodeJS packages we're going to use through `package.json`:


```javascript
{
  "name": "my_react_app",
  "version": "0.0.0",
  "description": "ReactJS app",
  "main": "index.js",
  "scripts": {},
  "author": "Andrea Pavoni",
  "license": "MIT",
  "homepage": "",
  "dependencies": {
    "browserify": "^8.1.3",
    "coffee-react": "^2.4.1",
    "coffee-reactify": "^2.1.0",
    "coffee-script": "^1.9.1",
    "gulp": "^3.8.11",
    "gulp-browserify": "^0.5.1",
    "gulp-rename": "^1.2.0",
    "gulp-size": "^1.2.1",
    "gulp-util": "^3.0.4",
    "jquery": "^2.1.3",
    "react": "^0.12.2"
  }
}
```

Finally a basic a `gulpfile.coffee` to manage the tasks. These will work like `rake` in the Ruby world.
In our case, it exposes `build` and `watch`, which respectively _bundles_ all the javascripts in one file and _watches_ the filesystem for changes to javascripts to rebuild:

```coffee
gulp = require("gulp")
gutil = require("gulp-util")
browserify = require("gulp-browserify")
rename = require("gulp-rename")
size = require("gulp-size")

JS_SRC='./app/assets/javascripts'
DEST='public'
JS_BUNDLE='app'

gulp.task 'build', ->
  gulp.src("#{JS_SRC}/application.coffee", { read: false })
    .pipe(browserify(
      transform: ['coffee-reactify']
      extensions: ['.coffee']
    ))
    .on("error", gutil.log)
    .pipe(rename("#{JS_BUNDLE}.js"))
    .pipe gulp.dest("#{DEST}/js")
    .pipe(size showFiles: true, title: "Plain JS")

gulp.task "watch", ->
  gulp.watch "#{JS_SRC}/**/*.coffee", ['build']

gulp.task "default", ["build"]
```

**NOTE:** For those not confident with CoffeeScript, you can easily translate it into plain Javascript with [js2coffee](http://js2.coffee/) online tool.

##### The client side, for real
Our initial implementation started with a simple utility library to manage the authentication for the client side:

```coffee
# app/assets/javascripts/lib/auth.coffee

authenticateUser = (email, password, callback) ->
  $.ajax '/authenticate',
    type: 'POST'
    data: {email: email, password: password}
    success: (resp) ->
      callback(authenticated: true, token: resp.auth_token)
    error: (resp) ->
      callback(authenticated: false)

module.exports =
  login: (email, pass, callback) ->
    if @loggedIn()
      callback(true) if callback
      @onChange true
      return

    authenticateUser email, pass, (res) =>
      authenticated = false
      if res.authenticated
        localStorage.token = res.token
        authenticated = true

      callback(authenticated) if callback
      @onChange authenticated

  getToken: ->
    localStorage.token

  logout: (callback) ->
    delete localStorage.token
    callback() if callback
    @onChange(false)

  loggedIn: ->
    !!localStorage.token

  onChange: ->
```

As you can see, it is very simple, we have a Javascript object which exposes some methods and helpers. The main one, `login`, makes an AJAX request with user credentials to the server endpoint. If credentials are correct, it will store the resulting JWT from the server response and stores it on `localStorage`. The JWT will then be used to make authenticated requests to the server.

Finally we integrated it inside the main application component:

```coffee
# app/assets/javascripts/application.coffee

React = require 'react'
Auth = require './lib/auth'
# other requires...

App = React.createClass
  getInitialState: ->
    loggedIn: Auth.loggedIn()

  setStateOnAuth: (loggedIn) ->
    @setState loggedIn: loggedIn

  componentWillMount: ->
    Auth.onChange = @setStateOnAuth

  render: ->
    # React's render ...
```

And here's how we use it for the authenticated requests:

```coffee
# app/assets/javascripts/notifications_list.coffee

React = require 'react'
Auth = require '../lib/auth'
# other requires...

module.exports = React.createClass
  getInitialState: ->
    return {results: []}

  componentDidMount: ->
    $.ajax '/notifications',
      headers:
        'Authorization': "Bearer #{Auth.getToken()}"
      success: (data) =>
        @setState({results: data.notifications})
  render: ->
    # React's render ...
```

As you can see, we need to set an authorization token header for our requests. The code is
simple for didactic purposes, in a real scenario it might be useful to create a custom helper
to append the authentication header token in each request by default.

### Conclusions
We've only scratched the surface, but the intent of this article was to offer a gentle introduction. We're happy to listen to your feedbacks and questions, if you want some more in-depth article, please let us know :-)

Authentication with Rails, JWT and ReactJS

Usually it's easy to add a gem (not an extension) to Spree but sometimes things
can get a little rough, [devise_invitable](https://github.com/scambra/devise_invitable)
is just like that, at first it might seem easy to install, but that's not true,
follow us to see how we have installed this good gem on Spree commerce.

We recently added an "invite a friend" feature to a Spree ecommerce. Looking for
a solution we didn't find any valid extension but we knew there was the
[devise_invitable gem](https://github.com/scambra/devise_invitable).
At first it seemed an easy task but devise_invitable didn't just work out of the
box with Spree so we needed to get our hands dirty.

Let's start by adding the devise_invitable gem to our Gemfile:

```ruby
gem 'devise_invitable', '~> 1.3'
```

then as usual run `bundle install` and generate everything that's needed by
devise_invitable:

```shell
$ bundle install
$ rails generate devise_invitable:install
$ rails generate devise_invitable:views spree
$ rails generate devise_invitable Spree::User
$ rake db:migrate
```

Now it's time to make some changes to our user model so we need to decorate the
__Spree::User__ class and add the invitable module, the other modules come from
[spree_auth_devise](https://github.com/spree/spree_auth_devise/blob/master/app/models/spree/user.rb#L6)
and as usual we can change those if we need some custom behavior.

```ruby
# app/models/spree/user_decorator.rb

Spree::User.class_eval do
  devise :database_authenticatable, :registerable, :recoverable, :rememberable,
         :trackable, :validatable, :encryptable, :invitable,
         encryptor: 'authlogic_sha512'
end
```

Then we run the application, go to `/signup` and add a user we can use to invite
our friends. If we go to `/user/spree_user/invitation/new` we see a form
for inviting new users. Here is where the trouble starts, an
`uninitialized constant Spree::InvitationsController` exception is raised
because devise_invitable is not under the Spree namespace.

When working with Spree, namespace troubles are to be expected, since Spree uses
a namespace for everything if you want to integrate something that is not an
extension you'll probably end up in this situation.

In this case we need to create a `Spree::InvitationsController` class which
inherits from `Devise::InvitationsController`.

```ruby
# app/controllers/spree/invitations_controller.rb

class Spree::InvitationsController < Devise::InvitationsController
end
```

then we try to reload the previus path another exception is raised:

`undefined method 'spree_user_invitation_path'`

this time the exception is raised because the path helper used by the
devise_invitable views is wrong. To fix it we have two options, we can either
change the devise `router_name` or change the path to the devise_invitable
views.

The first option is faster to apply but it makes devise only work in the Spree
namespace and in some cases that is not what we want.
If in an application is using the Spree engine alone this solution can safely be
used, we can add this to the devise initializer:

```ruby
# config/initializers/devise.rb

Devise.router_name = :spree
Devise.scoped_views = true
```

and we're done with this option.

The other option needs a little more work but it's the one we prefer since it's
more flexible and more versatile. We have to completely change the path helpers
in the views to use the Spree namespace:

```erb
# app/views/spree/invitations/new.html.erb
...
<%= form_for resource, :as => resource_name, :url => spree.spree_user_invitation_path, :html => {:method => :post} do |f| %>
...

# app/views/spree/invitations/edit.html.erb
...
<%= form_for resource, :as => resource_name, :url => spree.spree_user_invitation_path, :html => { :method => :put } do |f| %>
...

# app/views/spree/mailer/invitation_instructions.html.erb
...
<p><%= link_to I18n.t("devise.mailer.invitation_instructions.accept"), accept_spree_user_invitation_url(:invitation_token => @token) %></p>
...
```

The exception should be gone, we should be able to go to
`/user/spree_user/invitation/new` see the form and send an invite.  While
sending the email another exception is raised, devise_invitable is looking for
the email views in the wrong path because `Devise.mailer` is set to
`Spree::UserMailer`. This should be a simple fix:

```shell
$ mv app/views/spree/mailer app/views/spree/user_mailer
```

At last we have to setup the `default_url_options` for the mailer,
like we would normally do with devise:

```ruby
# config/environments/development.rb

config.action_mailer.default_url_options = { host: 'localhost', port: 3000 }
```

Now we should be able to go to `/user/spree_user/invitation/new` to invite a
user, all should be good, the email is sent and the new user can click on the
link to setup a password, but... there is no layout for these
views, lets fix this.

Normally we would make `InvitationsController` inherit from
`Spree::StoreController` but because our controller already inherits from
`Devise::InvitationsController` we need to add some modules and helpers to make
sure it works as expected:

```ruby
module Spree
  class InvitationsController < Devise::InvitationsController
    include Spree::Core::ControllerHelpers::Common
    include Spree::Core::ControllerHelpers::Store
    helper 'spree/base', 'spree/store'
  end
end
```

now we can just add a link to the invitation page using deface with the route
`new_spree_user_invitation` to let your users invite their friends.

If you want to take a look at the final result you can go
[here](https://github.com/nebulab/spree-invite-a-friend-example) to download the
 demo application. In this application you can find two branches, the
[solution_with_router_name](https://github.com/nebulab/spree-invite-a-friend-example/tree/solution_with_router_name)
and the [master](https://github.com/nebulab/spree-invite-a-friend-example/tree/master)
branch that use the last option in this article.

Installing Devise Invitable on Spree

Coming from a _Ruby and Rails_ background, we've always found very strange how
nowadays most JavaScript libraries that require _Node Packaged Modules_
recommend some dependencies to be installed globally one by one.
As Ruby developers that always felt strange to us. We'll see how to use
[npm](https://www.npmjs.org) like we use [Bundler](http://bundler.io).

It seems that every recent JavaScript project has one or more `npm install -g`
commands you should run to install some of the project's dependencies globally.
That is bad for READMEs that grow bigger and bigger, bad for setup
time because developers are forced to read much more instructions before being
able to work and bad for your computer because you pollute system directories
with development packages.
So we've come up with this question: why on earth should you be installing stuff
with `npm install -g` when npm is perfectly capable of running like Bundler
does?

After years of hard work done by using the great tool that
[Bundler](http://bundler.io) is, we don't like installing all those libraries
globally. Conceptually we like projects and applications to be self-contained,
standardized and easy to just pick up and play.

Basically this is the workflow every Rails developer knows and loves:

1. install bundler with `gem install bundler` if not already installed;
2. download an application, typically via `git clone`;
3. `cd` inside the application and run `bundle install`.

These three steps are usually everything that's required to have the
dependencies you need to start playing with the application (for example to
start exploring with `rails console`). That also means that you can go from zero
to the application running without even reading the README.

The same workflow seems unapplicable if you read the documentation of most npm
packages. As a team we're still very much experimenting with JavaScript so we
tend to change tools and libraries very often; we're still looking for the
workflow that works best for us. That means we could be using different tools
for different projects. Probably many developers are in our same exact position.

So this is why we've been trying to reproduce with npm the workflow we love
with Bundler. We found that it is actually possible and quite easy.

### Setup

As an example we'll demonstrate how to prepare an application from scratch
by using [ember-cli](https://cli.emberjs.com/) a utility we've been really
interested in since it came out. It's basically a set of tools and templates to
work with [ember](http://emberjs.com).

If you take a look at the project's
[Getting Started](https://cli.emberjs.com/release/basic-use/) section you'll
see there are plenty of tools you have to install by using `npm install -g`.
We'll do it differently.

First of all make sure you have npm installed. In addition to installing npm you
should add the local binaries folder to your `$PATH` environment variable. Since
npm will use the local directory `node_modules` to keep all your packages (the
binaries too), you need to have this:

```bash
PATH=./node_modules/.bin:$PATH
```

somewhere inside your `~/.zshrc` or `~/.bashrc` files.

Then create an empty folder which will host your project. From inside the
project's directory you can run all the `npm install` commands without the `-g`
flag and those will be installed in the `./node_modules` path inside your
project. You should also exclude this directory from your version control system
as this directory will contain code you don't want in your repository.

To create an application with `ember-cli`:

```bash
$ npm install ember-cli
$ ember init
$ npm install --save-dev phantomjs bower
```

This will generate everything and keep track of the dependecies of your app
inside the `package.json` file. Think of it as your `Gemfile` for JavaScript
applications. The `--save-dev` flag will make sure npm changes `package.json` to
reflect the dependecies you just installed.

To make sure developers don't fight with different versions of a dependency we
can add a `Gemfile.lock` equivalent, like this:

```bash
$ npm shrinkwrap --dev
```

Npm will add a new `npm-shrinkwrap.json` that keeps track of the exact
dependencies required to run your precious application (that you might want to
keep in your repository).
The `--dev` option makes sure development dependencies are tracked as well as
production dependencies.

Using the `npm-shrinkwrap.json` file also has some benefits in production
because it ensures you always have control of which versions will actually be
installed in the production environment (just like Bundler).

### Have fun

The procedure for setting up an application might be slightly longer than that
required by Bundler but, after doing this, the next developer working on the
application can just run:

```bash
$ npm install
```

after downloading the application to get all the dependencies required to use
the application smoothly.

Using npm like Bundler

Using Ember.js with Spree

Now that we've been working with Ember.js for a while, we wanted to give a quick update
on what we found works out for us while working with it, both client and server side.
We thought this post would be useful since we initially had some problems finding the right
tools but now we really feel we found the right toolchain.

## Client Side

We found the client side needs tools to: organize code, write tests and fake an API.
About data persistance libraries: we use [Ember Data](https://github.com/emberjs/data)
but we won't be talking about that here because it's a really hard choice and it really
depends on what you need to work on.

### Organize Code

The client side is probably the most complex part; since Ember.js does not (yet) provide powerful
buildtools, you have to go with whatever works best for you. Forget the starter kit provided
on the homepage. It's a fast way to start experimenting but you'll end up with a huge messy
file.

To provide some order to our apps we use [Brunch](http://brunch.io) with the
[tapas-with-ember](https://github.com/mutewinter/tapas-with-ember) skeleton. These tools will
let you (among other things):

* organize Ember code in a clean way
* manage Ember, Ember Data/Ember Model and Handlebars libraries
* write CoffeeScript (pretty much everywhere)
* provide automatic file reloading
* have a workbench ready to do TDD
* generate files with templates via [scaffolt](https://github.com/paulmillr/scaffolt)
* manage multiple environments (we use development, test, staging, production just like in Rails)
* compile, compress, lint your code

In addition to all those things, Brunch and tapas-with-ember are simple and well written so
it's easy to add any missing functionality you may need.

### Write Tests

We hate reinventing wheels; for testing Ember applications we went straight to what
[Ember provides](http://emberjs.com/guides/testing/integration/). This means we use
[QUnit](http://qunitjs.com) which, compared to more elaborate libraries like
[Jasmine](http://jasmine.github.io), may be disappointing but it also means that it works
without any additional work on our side.

To make the syntax more readable we use [SpecIt](https://github.com/joshuaclayton/specit).
It's an old library but it works pretty well. At times we had some deprecation warnings
but the library it's simple enough that it just requires changing a method to make it compatible
with QUnit's latest version.

Another thing we found really works out for us is using fixtures (like Ember Data's
`DS.FixtureAdapter`) instead of using a mocking library like [Sinon.JS](http://sinonjs.org).
By adding some test helpers the code needed to create fake data to be used when testing
is really clean, like this:

```coffeescript
create(
  user: { id: "current", products: [1, 2] }
  product: [ { id: 1, name: "Product #1" }, { id: 2, name: "Product #2" } ]
)
```

To run tests we use [Karma](http://karma-runner.github.io/0.10/index.html) which comes
with tapas-with-ember so you have pretty much everything done for you.

### Fake an API

One thing we can't believe no one is talking about is how to crate a fake API server to use
when you want to take a look at all the Ember code you've written.

On this matter we couldn't find a lot of libraries. Everything that's available usually
returns static data but we don't like that, we prefer dynamic data so that if we want to fake
hundreds of json objects we don't need a huge static json file.

After some time spent trying out various solutions we came across [dyson](https://github.com/webpro/dyson)
a simple library for providing fake dynamic data via a Node server. A quick example of how
to generate ten json objects with dynamic attributes:

```javascript
var currentId = 0;

module.exports = {
  path: '/products',
  collection: true,
  size: 10,

  template: {
    id: function() {
      currentId += 1;
      return currentId.toString();
    },
    name: function() {
      return 'Product #' + this.id;
    }
  }
};
```

## Server Side

Once you have a pretty good idea of how the Ember application might work, you'll obviously
need some APIs to actually serve the content that will make the client side application
come to life.

We usually don't split teams between client side and server side so most of the time whoever is
working on an Ember application also designs and codes the server side APIs. We use Rails for
APIs; the biggest problems we usually find are: rendering json data and providing great documentation
for our APIs.

### Render JSON Data

To render json data we use [ActiveModelSerializers](https://github.com/rails-api/active_model_serializers);
it's the library which works best with Ember and it's full of conventions so you don't need
to write everything yourself. Compared to RABL (another popular API builder library) ActiveModelSerializers
feels more robust and doesn't give you the feeling you're writing that json data by hand.

One important aspect of writing a good json API is having a good data format. We use [JSON API](http://jsonapi.org)
for this. JSON API is a standard for writing good json APIs; even though it's not quite
ready yet (it's still in its draft state), it's really powerful because you don't have to spend
time choosing what format will work for you, you'll have a format that will work and scale
well from few json objects to thousands.

### API Documentation

If your API is public you probably want some good documentation to go with it.
We use [Apipie-rails](https://github.com/Pajk/apipie-rails) for this because it's straightforward.
By providing a simple DSL, Apipie-rails will let you write documentation for your API
endpoinds in no time. Once you're done writing about your API you'll end up with a mountable
engine which exposes your neat documentation in an easy to read format.
Among the cool features of Apipie-rails one of the most useful is that you can actually
use the documentation DSL to validate the API parameters (presence, type, regex, ...) so
you don't have to manage parameters validation in the controllers yourself.

## Deploy

One last note about application deployment. We've looked around for some solutions
coming from the js world but couldn't really find something that works out of the box.
We decided to stick with what we know and love: [Capistrano](http://capistranorb.com).
There are tons of great gems for Capistrano and it's so powerful that we went from no
deploy to production in no time!

## Concluding Thoughts

The Ember ecosystem is not quite ready for the casual noob. Coming from a Rails world
we had to face many new problems and a lot of hard choices. The good thing is that,
if you take the time to find the tools that work for you, you'll be immensely rewarded.
Working with Ember can be just as good as working with Rails even though, for now,
Ember does not provide its buildtools (but seems like they
[will come in 2014](http://emberjs.com/blog/2013/12/17/whats-coming-in-ember-in-2014.html)).

So this is what we're using currently to work on our Ember applications, what do you think
about it? What is your current setup?

The Nebulab