Merge pull request #1304 from NullVoxPopuli/ember-findRecord-include-how-to

Add docs for Ember.

Author: beauby

docs/README.md

@@ -15,6 +15,7 @@ This is the documentation of AMS, it's focused on the **0.10.x version.**
 - [How to add root key](howto/add_root_key.md)
 - [How to add pagination links](howto/add_pagination_links.md)
 - [Using AMS Outside Of Controllers](howto/outside_controller_use.md)
+- [How to use JSON API with Ember](howto/ember-and-json-api.md)
 
 ## Getting Help
 

docs/howto/ember-and-json-api.md

@@ -0,0 +1,92 @@
+# How to use JSON API Query Parameters with Ember
+
+ - [Preparation](./ember-and-json-api.md#preparation)
+   - [Adapter Changes](./ember-and-json-api.md#adapter-changes)
+   - [Serializer Changes](./ember-and-json-api.md#serializer-changes)
+ - [Including Nested Resources](./ember-and-json-api.md#including-nested-resources)
+
+## Preparation
+
+Note: This guide assumes that `ember-cli` is used for your ember app.
+
+The JSON API specification calls for hyphens for multi-word separators. AMS uses underscores.
+To solve this, in Ember, both the adapter and the serializer will need some modifications:
+
+### Adapter Changes
+
+```javascript
+// app/adapters/application.js
+import DS from 'ember-data';
+import ENV from "../config/environment";
+
+export default  DS.JSONAPIAdapter.extend({
+  namespace: 'api',
+  // if your rails app is on a different port from your ember app
+  // this can be helpful for development.
+  // in production, the host for both rails and ember should be the same.
+  host: ENV.host,
+
+  // allows the multiword paths in urls to be underscored
+  pathForType: function(type) {
+    let underscored = Ember.String.underscore(type);
+    return Ember.String.pluralize(underscored);
+  },
+
+  // allows queries to be sent along with a findRecord
+  // hopefully Ember / EmberData will soon have this built in
+  urlForFindRecord(id, modelName, snapshot) {
+    let url = this._super(...arguments);
+    let query = Ember.get(snapshot, 'adapterOptions.query');
+    if(query) {
+      url += '?' + Ember.$.param(query);
+    }
+    return url;
+  }
+});
+```
+
+### Serializer Changes
+
+```javascript
+// app/serializers/application.js
+import Ember from 'ember';
+import DS from 'ember-data';
+var underscore = Ember.String.underscore;
+
+export default DS.JSONAPISerializer.extend({
+  keyForAttribute: function(attr) {
+    return underscore(attr);
+  },
+
+  keyForRelationship: function(rawKey) {
+    return underscore(rawKey);
+  }
+});
+
+```
+
+## Including Nested Resources
+
+Previously, `store.find` and `store.findRecord` did not allow specification of any query params.
+The AMS default for the `include` parameter is to be `nil` meaning that if any associations are defined in your serializer, only the `id` and `type` will be in the `relationships` structure of the JSON API response.
+For more on `include` usage, see: [The JSON API include examples](./../general/adapters.md#JSON-API)
+
+With the above modifications, you can execute code as below in order to include nested resources while doing a find query.
+
+```javascript
+store.findRecord('post', postId, { adapterOptions: { query: { include: 'comments' } } });
+```
+will generate the path `/posts/{postId}?include='comments'`
+
+So then in your controller, you'll want to be sure to have something like:
+```ruby
+render json: @post, include: params[:include]
+```
+
+If you want to use `include` on a collection, you'd write something like this:
+
+```javascript
+store.query('post', { include: 'comments' });
+```
+
+which will generate the path `/posts?include='comments'`