Skip to content

Commit 2321073

Browse files
jmdobryjmdobry
committed
Added queries & filtering docs. #28 
1 parent 057de03 commit 2321073

File tree

5 files changed

+181
-30
lines changed

5 files changed

+181
-30
lines changed

‎Gruntfile.js

+6-16
Original file line numberDiff line numberDiff line change
@@ -236,17 +236,19 @@ module.exports = function (grunt) {
236236
'guide/angular-data/index.doc',
237237
'guide/angular-data/overview.doc',
238238
'guide/angular-data/resources.doc',
239-
'guide/angular-data/synchronous.doc',
240239
'guide/angular-data/asynchronous.doc',
240+
'guide/angular-data/synchronous.doc',
241+
'guide/angular-data/queries.doc',
241242
'guide/angular-data/how.doc'
242243
],
243244
rank: {
244245
index: 1,
245246
overview: 2,
246247
resources: 3,
247-
synchronous: 4,
248-
asynchronous: 5,
249-
how: 6
248+
asynchronous: 4,
249+
synchronous: 5,
250+
queries: 6,
251+
how: 7
250252
}
251253
},
252254
{
@@ -285,15 +287,6 @@ module.exports = function (grunt) {
285287
custom: 6
286288
}
287289
},
288-
{
289-
id: 'angular-data-queries',
290-
title: 'Queries',
291-
docs: ['guide/angular-data/queries/'],
292-
rank: {
293-
index: 1,
294-
overview: 2
295-
}
296-
},
297290
{
298291
id: 'angular-data-adapters',
299292
title: 'Adapters',
@@ -393,7 +386,4 @@ module.exports = function (grunt) {
393386
]);
394387
grunt.registerTask('go', ['build', 'watch']);
395388
grunt.registerTask('default', ['build']);
396-
397-
// Used by TravisCI
398-
grunt.registerTask('ci', ['test', 'doc']);
399389
};

‎guide/angular-data/queries.doc

+130
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
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+
```

‎guide/angular-data/queries/queries.doc

-13
This file was deleted.

‎guide/home.html

+41
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ <h1>
5252
<tr>
5353
<th>Project</th>
5454
<th>angular-data</th>
55+
<th>angular-data-mocks</th>
5556
<th>angular-cache</th>
5657
</tr>
5758
</thead>
@@ -60,6 +61,7 @@ <h1>
6061
<td>Branch</td>
6162
<td>master</td>
6263
<td>master</td>
64+
<td>master</td>
6365
</tr>
6466
<tr>
6567
<td>Bower</td>
@@ -69,6 +71,12 @@ <h1>
6971
style="max-width:100%;">
7072
</a>
7173
</td>
74+
<td>
75+
<a href="http://badge.fury.io/bo/angular-data-mocks">
76+
<img src="https://badge.fury.io/bo/angular-data-mocks.png" alt="Bower version"
77+
style="max-width:100%;">
78+
</a>
79+
</td>
7280
<td>
7381
<a href="http://badge.fury.io/bo/angular-cache">
7482
<img src="https://badge.fury.io/bo/angular-cache.png" alt="Bower version"
@@ -84,6 +92,12 @@ <h1>
8492
style="max-width:100%;">
8593
</a>
8694
</td>
95+
<td>
96+
<a href="http://badge.fury.io/js/angular-data-mocks">
97+
<img src="https://badge.fury.io/js/angular-data-mocks.png" alt="NPM version"
98+
style="max-width:100%;">
99+
</a>
100+
</td>
87101
<td>
88102
<a href="http://badge.fury.io/js/angular-cache">
89103
<img src="https://badge.fury.io/js/angular-cache.png" alt="NPM version"
@@ -99,6 +113,12 @@ <h1>
99113
alt="Build Status" style="max-width:100%;">
100114
</a>
101115
</td>
116+
<td>
117+
<a href="https://travis-ci.org/jmdobry/angular-data-mocks">
118+
<img src="https://travis-ci.org/jmdobry/angular-data-mocks.png?branch=master"
119+
alt="Build Status" style="max-width:100%;">
120+
</a>
121+
</td>
102122
<td>
103123
<a href="https://travis-ci.org/jmdobry/angular-cache">
104124
<img src="https://travis-ci.org/jmdobry/angular-cache.png?branch=master"
@@ -114,6 +134,12 @@ <h1>
114134
style="max-width:100%;">
115135
</a>
116136
</td>
137+
<td>
138+
<a href="https://codeclimate.com/github/jmdobry/angular-data-mocks">
139+
<img src="https://codeclimate.com/github/jmdobry/angular-data-mocks.png" alt="Code Climate"
140+
style="max-width:100%;">
141+
</a>
142+
</td>
117143
<td>
118144
<a href="https://codeclimate.com/github/jmdobry/angular-cache">
119145
<img src="https://codeclimate.com/github/jmdobry/angular-cache.png" alt="Code Climate"
@@ -129,6 +155,12 @@ <h1>
129155
style="max-width:100%;">
130156
</a>
131157
</td>
158+
<td>
159+
<a href="https://gemnasium.com/jmdobry/angular-data-mocks">
160+
<img src="https://gemnasium.com/jmdobry/angular-data-mocks.png" alt="Dependency Status"
161+
style="max-width:100%;">
162+
</a>
163+
</td>
132164
<td>
133165
<a href="https://gemnasium.com/jmdobry/angular-cache">
134166
<img src="https://gemnasium.com/jmdobry/angular-cache.png" alt="Dependency Status"
@@ -144,6 +176,12 @@ <h1>
144176
alt="Coverage Status" style="max-width:100%;">
145177
</a>
146178
</td>
179+
<td>
180+
<a href="https://coveralls.io/r/jmdobry/angular-data-mocks?branch=master">
181+
<img src="https://coveralls.io/repos/jmdobry/angular-data-mocks/badge.png?branch=master"
182+
alt="Coverage Status" style="max-width:100%;">
183+
</a>
184+
</td>
147185
<td>
148186
<a href="https://coveralls.io/r/jmdobry/angular-cache?branch=master">
149187
<img src="https://coveralls.io/repos/jmdobry/angular-cache/badge.png?branch=master"
@@ -156,6 +194,9 @@ <h1>
156194
<td>
157195
<a href="https://github.com/jmdobry/angular-data/blob/master/LICENSE">MIT License</a>
158196
</td>
197+
<td>
198+
<a href="https://github.com/jmdobry/angular-data-mocks/blob/master/LICENSE">MIT License</a>
199+
</td>
159200
<td>
160201
<a href="https://github.com/jmdobry/angular-cache/blob/master/LICENSE">MIT License</a>
161202
</td>

‎guide/nav.html

+4-1
Original file line numberDiff line numberDiff line change
@@ -28,11 +28,14 @@
2828
<li>
2929
<a href="/documentation/guide/angular-data-resource/basic">Defining Resources</a>
3030
</li>
31+
<li>
32+
<a href="/documentation/guide/angular-data/asynchronous">Asynchronous Methods</a>
33+
</li>
3134
<li>
3235
<a href="/documentation/guide/angular-data/synchronous">Synchronous Methods</a>
3336
</li>
3437
<li>
35-
<a href="/documentation/guide/angular-data/asynchronous">Asynchronous Methods</a>
38+
<a href="/documentation/guide/angular-data/queries">Queries & Filtering</a>
3639
</li>
3740
<li>
3841
<a href="/documentation/guide/angular-data/how">How do I...?</a>

0 commit comments

Comments
 (0)