+ Rails Standards
+ 
+ Easy Microservices
+ 
+ One API, Many Clients
+ 
+ Client Support
+ 
+ Error Handling
+ 
+ Automatic Documentation
+ 
+ 
+ 
+ 
+
+ {{ content }}
+
+
+
+
+
+
+
+ Overview
+-
+
- + Quickstart + +
- + Tutorial + +
- + Concepts + +
+
+ Resources
+-
+
- + YARD Documentation + +
- + Slack Chat + +
- + Contact us + +
+
+ Related
+-
+
- + JSONAPI Spec + +
- + jsonapi-rb + +
- + VueJS + +
+ 
+ 
+ 
+ 
+
+
+ 
+ 
+ 
+
+We use [jsonapi-rb](http://jsonapi-rb.org) for serialization. If you've used [active_model_serializers](https://github.com/rails-api/active_model_serializers) before, it will look incredibly familiar:
+
+{% highlight ruby %}
+# app/serializers/serializable_post.rb
+class SerializablePost < JSONAPI::Serializable::Resource
+ type :posts
+
+ attribute :title
+ attribute :description
+ attribute :body
+end
+{% endhighlight %}
+
+Would render the [JSONAPI Document](http://jsonapi.org/format/#document-structure):
+
+{% highlight ruby %}
+{
+ data: {
+ type: "posts",
+ id: "123",
+ attributes: {
+ title: "My Post",
+ description: "Some description",
+ body: "Blah blah blah"
+ }
+ }
+}
+{% endhighlight %}
+
+#### Associations
+
+To add an association:
+
+{% highlight ruby %}
+has_many :comments
+{% endhighlight %}
+
+Assuming there is a corresponding `SerializableComment`, you'd see:
+
+{% highlight ruby %}
+{
+ data: {
+ type: "posts",
+ id: "123",
+ attributes: { ... },
+ relationships: {
+ comments: {
+ data: [
+ { id: "1", type: "comments" }
+ ]
+ }
+ }
+ },
+ included: [
+ {
+ type: "comments",
+ id: "1"
+ }
+ ]
+}
+{% endhighlight %}
+
+> Note: Your `Resource` must [whitelist this sideload]({{site.github.url}}/ruby/reads/nested) as well.
+
+#### Customizing Serializers
+
+Occasionally you may need to normalize, format, or elsewise transform
+your `Model` into an effective JSON representation. To do this, pass a
+block to `attribute` and reference the underlying `@object` being
+serialized:
+
+{% highlight ruby %}
+attribute :title do
+ @object.title.upcase
+end
+{% endhighlight %}
+
+> Why not methods like AMS? To avoid collissions with native ruby methods like `tap`.
+
+Keep in mind all serializers have access to `@context` - the calling
+controller in Rails.
+
+#### Conditional Fields
+
+You may want to render a field based on runtime context - for instance,
+only show the `salary` field if the user is a manager. Keeping in mind
+that `@context` will always be available as the calling controller:
+
+{% highlight ruby %}
+attribute :salary, if: -> { @context.current_user.manager? }
+{% endhighlight %}
+
+> [View additional documentation at jsonapi-rb.org](http://jsonapi-rb.org)
+
+> [Visit the jsonapi-rb Gitter chatroom](https://gitter.im/jsonapi-rb)
diff --git a/ruby/reads/sorting.md b/ruby/reads/sorting.md
new file mode 100644
index 0000000..1ce259e
--- /dev/null
+++ b/ruby/reads/sorting.md
@@ -0,0 +1,50 @@
+---
+layout: page
+---
+
+{% include ruby-toc.html %}
+
+
+
+**JSORM can be used with the client-side framework of your choice**. To give an example of real-world usage, we've created a demo application using
+[VueJS](https://vuejs.org/). Vue is lightweight and provides the
+bare-bones we need to illustrate JSONAPI and JSORM in action.
+
+This will point to a [slightly-tweaked branch](https://github.com/jsonapi-suite/employee_directory/tree/prepare_clientside) of the server-side API
+above.
+
+Let's create our app.
+
+### Step 0: Setup
+
+We've started with a basic Vue app configured with Webpack. None of this
+is JSONAPI-specific, just boilerplate to get started quickly.
+
+
+[View the Branch on Github](https://github.com/jsonapi-suite/employee-directory-vue/tree/step_0_setup)
+
+### Step 1: Models
+
+We'll start by defining our models, which should look very familiar if
+you've worked with `ActiveRecord`. Again, see the [JSORM
+documentation](/js/home) if any of this looks confusing to you.
+
+
+[View the Diff on Github](https://github.com/jsonapi-suite/employee-directory-vue/compare/step_0_setup...step_1_models)
+
+### Step 2: Data Grid
+
+We'll add a simple data grid to our page listing all `Employee`s. This
+will turn into a search grid, but for now we're simply loading employees
+via `Employee.all()`
+
+
+[View the Diff on Github](https://github.com/jsonapi-suite/employee-directory-vue/compare/step_1_models...step_2_data_grid)
+
+### Step 3: Adding Relationships
+
+Here we've added a `currentPosition` relationship to avoid fetching
+excess data from the server. When the page loads we fetch the
+employees, current positions for those employees, and the departments for those positions.
+
+
+[View the Diff on Github](https://github.com/jsonapi-suite/employee-directory-vue/compare/step_2_data_grid...step_3_includes)
+
+### Step 4: Filtering
+
+Here we've added a bit of state to the page, `query`, which will be
+bound to the form inputs. We pass `query` to `Employee.where` to
+successfully query employees by first and last name.
+
+
+[View the Diff on Github](https://github.com/jsonapi-suite/employee-directory-vue/compare/step_3_includes...step_4_filtering)
+
+### Step 5: Sorting
+
+Just like with filters, we add a bit of state to our page to track
+sorting parameters. When the user clicks a table header, we'll update
+that state and pass it to our query.
+
+
+
+[View the Diff on Github](https://github.com/jsonapi-suite/employee-directory-vue/compare/step_4_filtering...step_5_sorting)
+
+### Step 6: Stats
+
+A JSORM promise returns a `response` object with a `data` key - the
+model instance(s) we've been referencing so far. It also returns a
+`meta` key that reflects the [meta](http://jsonapi.org/format/#document-meta) section of the JSONAPI response.
+
+Here we'll request the total count of employees in our query to the
+server, grab that total count from `meta`, and bind it to the page as
+`totalCount`
+
+
+[View the Diff on Github](https://github.com/jsonapi-suite/employee-directory-vue/compare/step_5_sorting...step_6_stats)
+
+### Step 7: Pagination
+
+Building on what we've already done, we can apply a similar pattern for
+pagination. We add the `currentPage` state and alter it when the user
+clicks pagination links. We use `currentPage` and `totalCount` to figure
+out if we should display previous/next page links.
+
+
+[View the Diff on Github](https://github.com/jsonapi-suite/employee-directory-vue/compare/step_6_stats...step_7_pagination)
+
+### Step 8: Basic Form Setup
+
+We'll be adding a form to create and update employees. This step just
+adds the relevant HTML and Vue code to get set up, before involving
+JSORM.
+
+
+[View the Diff on Github](https://github.com/jsonapi-suite/employee-directory-vue/compare/step_7_pagination...step_8_basic_form_setup)
+
+### Step 9: Dropdowns
+
+Our form will submit employees, positions and departments in a single
+request. We associate a position to an existing department through a
+`select` dropdown. To populate that dropdown, we fetch all departments
+from the server and bind it to the `select`.
+
+
+[View the Diff on Github](https://github.com/jsonapi-suite/employee-directory-vue/compare/step_8_basic_form_setup...step_9_dropdown)
+
+### Step 10: Nested Create/Update
+
+This step simply binds our instantiated models to the form. When the
+form is submitted, we save everything in a single one-line request.
+
+After the form submission, we could edit the form and submit again -
+JSORM will know to `PATCH` an update to the appropriate URL
+automatically.
+
+Note we could also edit our search to immediately reflect the new
+data...but this is more Vue-specific than anything to do with JSORM, so
+we'll hold off until the last step.
+
+
+[View the Diff on Github](https://github.com/jsonapi-suite/employee-directory-vue/compare/step_9_dropdown...step_10_nested_create)
+
+### Step 11: Validations
+
+Our server-side code will automatically handle validation errors and
+give us a well-formatted response. JSORM will read that response and
+automatically apply `error` objects to our model instances. Here we
+display simple error messages without involving any JS code.
+
+
+[View the Diff on Github](https://github.com/jsonapi-suite/employee-directory-vue/compare/step_10_nested_create...step_11_validations)
+
+### Step 12: Nested Destroy
+
+This step adds buttons to our form that will add and remove positions
+for a given employee. To add, we simply `push` a new `Employee` onto the
+relationship array. To remove, we set `isMarkedForDestruction = true`,
+which allows for "unsaved deleted records". This follows a similar
+pattern to one introduced in Ember Data, [explained here](https://www.emberjs.com/blog/2015/09/02/ember-data-2-0-released.html#toc_unsaved-deleted-records).
+
+Note that if we wanted to **disassociate** the position rather than
+**destroying** the underlying record, we could use
+`position.isMarkedForDisassociation = true`.
+
+
+[View the Diff on Github](https://github.com/jsonapi-suite/employee-directory-vue/compare/step_10_nested_create...step_11_validations)
+
+### Step 13: VueJS Wrap-up
+
+Our final step adds some Vue-specific functionality - we add an
+`EventBus` to allow selecting an employee from the grid and binding it
+to the form, and refresh the search grid after each form submission.
+
+
+[View the Diff on Github](https://github.com/jsonapi-suite/employee-directory-vue/compare/step_12_nested_destroy...step_13_vue)
+
+