|
| 1 | +@doc overview |
| 2 | +@id queries |
| 3 | +@name Queries and Filtering |
| 4 | +@description |
| 5 | + |
| 6 | +Items injected into the data store are indexed by their primary key, but they're also stored in collections. |
| 7 | + |
| 8 | +`DS.findAll()` is used to asynchronously query a persistence layer for a collection of items. `DS.filter()` is used to |
| 9 | +synchronously query the items already in the data store. Here are some examples: |
| 10 | + |
| 11 | +Translates into a `GET` request to `/post`: |
| 12 | +```js |
| 13 | +DS.findAll('post', {}).then(function (posts) { |
| 14 | + posts; // [ { ... }, { ... }, ... , { ... } ] |
| 15 | + |
| 16 | + DS.filter('post', {}); // returns all posts in the data store |
| 17 | +}).catch(function (err) { |
| 18 | + err; // reason why query failed |
| 19 | +}); |
| 20 | +``` |
| 21 | + |
| 22 | +Translates into a `GET` request to `/post?query={"where":{"author":{"==":"John Anderson"}}}'` (url encoded of course): |
| 23 | +```js |
| 24 | +var params = { |
| 25 | + query: { |
| 26 | + where: { |
| 27 | + author: { |
| 28 | + '==': 'John Anderson' |
| 29 | + } |
| 30 | + } |
| 31 | + } |
| 32 | +}; |
| 33 | + |
| 34 | +DS.findAll('post', params).then(function (posts) { |
| 35 | + posts; // [ { ... }, { ... }, ... , { ... } ] |
| 36 | + |
| 37 | + DS.filter('post', params); // filters the posts already in the data store |
| 38 | +}).catch(function (err) { |
| 39 | + err; // reason why query failed |
| 40 | +}); |
| 41 | +``` |
| 42 | + |
| 43 | +Angular-data has a "query" language that it natively understands. To sync up how your API and the data store query |
| 44 | +collections you will need to do one of the following: |
| 45 | + |
| 46 | +##### Option A |
| 47 | +Configure your API to understand angular-data's query syntax, translating the query object into the appropriate database query. |
| 48 | + |
| 49 | +##### Option B |
| 50 | +Replace Angular-data's filter with your own filter that works the same way your API already works. |
| 51 | + |
| 52 | +Here's is angular-data's filter (it's pretty simple): |
| 53 | + |
| 54 | +```js |
| 55 | +function (resourceName, where, attrs) { |
| 56 | + var keep = true; |
| 57 | + utils.forOwn(where, function (clause, field) { |
| 58 | + if (utils.isString(clause)) { |
| 59 | + clause = { |
| 60 | + '===': clause |
| 61 | + }; |
| 62 | + } else if (utils.isNumber(clause)) { |
| 63 | + clause = { |
| 64 | + '==': clause |
| 65 | + }; |
| 66 | + } |
| 67 | + if ('==' in clause) { |
| 68 | + keep = keep && (attrs[field] == clause['==']); |
| 69 | + } else if ('===' in clause) { |
| 70 | + keep = keep && (attrs[field] === clause['===']); |
| 71 | + } else if ('!=' in clause) { |
| 72 | + keep = keep && (attrs[field] != clause['!=']); |
| 73 | + } else if ('>' in clause) { |
| 74 | + keep = keep && (attrs[field] > clause['>']); |
| 75 | + } else if ('>=' in clause) { |
| 76 | + keep = keep && (attrs[field] >= clause['>=']); |
| 77 | + } else if ('<' in clause) { |
| 78 | + keep = keep && (attrs[field] < clause['<']); |
| 79 | + } else if ('<=' in clause) { |
| 80 | + keep = keep && (attrs[field] <= clause['<=']); |
| 81 | + } else if ('in' in clause) { |
| 82 | + keep = keep && utils.contains(clause['in'], attrs[field]); |
| 83 | + } |
| 84 | + }); |
| 85 | + return keep; |
| 86 | +} |
| 87 | +``` |
| 88 | + |
| 89 | +If the following `params` argument is passed to `DS.filter`: |
| 90 | + |
| 91 | +```js |
| 92 | +var params = { |
| 93 | + query: { |
| 94 | + where: { |
| 95 | + author: { |
| 96 | + '==': 'John Anderson' |
| 97 | + } |
| 98 | + } |
| 99 | + } |
| 100 | +}; |
| 101 | + |
| 102 | +DS.filter('post', params); |
| 103 | +``` |
| 104 | + |
| 105 | +Then `DS.filter` will return the posts (already in the data store) where `post.author == 'John Anderson'` is true. |
| 106 | + |
| 107 | +Here's how to replace Angular-data's filter: |
| 108 | + |
| 109 | +```js |
| 110 | +DSProvider.defaults.filter = function (resourceName, where, attrs) { |
| 111 | + // custom filter |
| 112 | + // this will be called on every item in the collection |
| 113 | + // return true to keep `attrs` in the result set |
| 114 | + // return false to exclude `attrs` from the result set |
| 115 | +}); |
| 116 | +``` |
| 117 | + |
| 118 | +You can even override the filter per-resource: |
| 119 | + |
| 120 | +```js |
| 121 | +DS.defineResource({ |
| 122 | + name: 'post', |
| 123 | + filter: function (resourceName, where, attrs) { |
| 124 | + // custom filter for posts |
| 125 | + // this will be called on every item in the collection |
| 126 | + // return true to keep `attrs` in the result set |
| 127 | + // return false to exclude `attrs` from the result set |
| 128 | + } |
| 129 | +}); |
| 130 | +``` |
0 commit comments