← Back to branch summary

~smagoun/whoopsie/whoopsie-lp1017637

« back to all changes in this revision

Viewing changes to backend/stats/static/js/yui/docs/recordset/index.html

  • Committer: Evan Dandrea
  • Date: 2012-05-09 05:53:45 UTC
  • Revision ID: evan.dandrea@canonical.com-20120509055345-z2j41tmcbf4as5uf
The backend now lives in lp:daisy and the website (errors.ubuntu.com) now lives in lp:errors.

Show diffs side-by-side

added added

removed removed

Lines of Context:
backend/stats/static/js/yui/docs/recordset/index.html
1
 
<!DOCTYPE html>
2
 
<html lang="en">
3
 
<head>
4
 
    <meta charset="utf-8">
5
 
    <title>Recordset</title>
6
 
    <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Maven+Pro:400,700">
7
 
    <link rel="stylesheet" href="../../build/cssgrids/grids-min.css">
8
 
    <link rel="stylesheet" href="../assets/css/main.css">
9
 
    <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
10
 
    <script src="../../build/yui/yui-min.js"></script>
11
 
</head>
12
 
<body>
13
 
 
14
 
<div id="doc">
15
 
    <h1>Recordset</h1>
16
 
 
17
 
    
18
 
        <a href="#toc" class="jump">Jump to Table of Contents</a>
19
 
    
20
 
 
21
 
    <div class="yui3-g">
22
 
        <div class="yui3-u-3-4">
23
 
            <div id="main">
24
 
                <div class="content"><div class="intro component">
25
 
    <p>
26
 
        The Recordset utility allows the storage and retrieval of objects with
27
 
        similar properties.
28
 
    </p>
29
 
</div>
30
 
 
31
 
<h2 id="getting-started">Getting Started</h2>
32
 
 
33
 
<p>
34
 
To include the source files for Recordset and its dependencies, first load
35
 
the YUI seed file if you haven't already loaded it.
36
 
</p>
37
 
 
38
 
<pre class="code prettyprint">&lt;script src=&quot;http:&#x2F;&#x2F;yui.yahooapis.com&#x2F;3.5.0&#x2F;build&#x2F;yui&#x2F;yui-min.js&quot;&gt;&lt;&#x2F;script&gt;</pre>
39
 
 
40
 
 
41
 
<p>
42
 
Next, create a new YUI instance for your application and populate it with the
43
 
modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
44
 
YUI will automatically load any dependencies required by the modules you
45
 
specify.
46
 
</p>
47
 
 
48
 
<pre class="code prettyprint">&lt;script&gt;
49
 
&#x2F;&#x2F; Create a new YUI instance and populate it with the required modules.
50
 
YUI().use(&#x27;recordset&#x27;, function (Y) {
51
 
    &#x2F;&#x2F; Recordset is available and ready for use. Add implementation
52
 
    &#x2F;&#x2F; code here.
53
 
});
54
 
&lt;&#x2F;script&gt;</pre>
55
 
 
56
 
 
57
 
<p>
58
 
For more information on creating YUI instances and on the
59
 
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
60
 
documentation for the <a href="../yui/index.html">YUI Global Object</a>.
61
 
</p>
62
 
 
63
 
 
64
 
<h2 id="using">Using Recordsets</h2>
65
 
 
66
 
<h3 id="basics">Recordset basics</h3>
67
 
 
68
 
<p>
69
 
    A Recordset in its simplest form is a collection of records, where records
70
 
    can be considered to be object literals. Recordset allows the user to
71
 
    handle this collection of records with a consistent API.
72
 
</p>
73
 
 
74
 
<p>
75
 
    Recordset augments the functionality of <code>Y.Arraylist</code> but goes a
76
 
    step further, by allowing the developer to quickly store and retrieve
77
 
    objects with similar properties. Additional submodules can be plugged into
78
 
    a <code>Y.Recordset</code> instance to enable sorting, filtering and
79
 
    indexing by specific keys.
80
 
</p>
81
 
 
82
 
<p>
83
 
    Initializing a Recordset is straight-forward:
84
 
</p>
85
 
 
86
 
<pre class="code prettyprint">YUI().use(&quot;recordset-base&quot;, function(Y) {
87
 
    var data = [
88
 
                {a:3, b:2, c:1},
89
 
                {a:9, b:8, c:7},
90
 
                {a:1, b:2, c:3}
91
 
        ],
92
 
 
93
 
        &#x2F;&#x2F;Recordset is created with the objects from the data array
94
 
        myRecordset = new Y.Recordset({records: data}),
95
 
 
96
 
        &#x2F;&#x2F;Empty Recordsets can also be created
97
 
        anEmptyRecordset = new Y.Recordset();
98
 
 
99
 
});</pre>
100
 
 
101
 
 
102
 
 
103
 
<h3 id="crud">Adding, Removing, Updating and Emptying</h3>
104
 
 
105
 
<p>
106
 
    A <code>Y.Recordset</code> can be filled with a single, or an array of
107
 
    object literals. Under the hood, Recordset will convert these objects into
108
 
    <code>record</code> instances - essentially creating a light wrapper around
109
 
    them.
110
 
</p>
111
 
 
112
 
<p>
113
 
    More information on performing operations on Recordset can be seen the the
114
 
    documentation for the <a href="recordset-basic.html">
115
 
    <code>recordset-base</code> sub-module</a>.
116
 
</p>
117
 
 
118
 
<h4 id="add">Adding Records</h4>
119
 
 
120
 
<pre class="code prettyprint">var data = [
121
 
    {key:&quot;a&quot;, label:&quot;Column A&quot;},
122
 
    {key:&quot;b&quot;, label:&quot;Column B&quot;},
123
 
    {key:&quot;c&quot;, label:&quot;Column C&quot;}
124
 
],
125
 
myRecordset = new Y.Recordset({records:data});
126
 
 
127
 
&#x2F;&#x2F;Adding a single record to the end of a Recordset
128
 
myRecordset.add({key:&quot;d&quot;, label:&quot;Column D&quot;});
129
 
 
130
 
&#x2F;&#x2F;Adding multiple records at the 2nd index of the Recordset
131
 
myRecordset.add([
132
 
    {key:&quot;e&quot;, label:&quot;Column E&quot;},
133
 
    {key:&quot;f&quot;, label:&quot;Column F&quot;}
134
 
], 2);</pre>
135
 
 
136
 
 
137
 
<h4 id="remove">Removing Records</h4>
138
 
 
139
 
<pre class="code prettyprint">var data = [
140
 
    {key:&quot;a&quot;, label:&quot;Column A&quot;},
141
 
    {key:&quot;b&quot;, label:&quot;Column B&quot;},
142
 
    {key:&quot;c&quot;, label:&quot;Column C&quot;}
143
 
],
144
 
myRecordset = new Y.Recordset({records:data});
145
 
 
146
 
&#x2F;&#x2F;removes the record stored at index 2 (in this case {key:&quot;c&quot;, label:&quot;Column C&quot;} is removed)
147
 
myRecordset.remove(2);
148
 
 
149
 
&#x2F;&#x2F;Removes 2 records starting at index zero
150
 
myRecordset.remove(0,2);</pre>
151
 
 
152
 
 
153
 
<h4 id="updating-records">Updating Records</h4>
154
 
 
155
 
<pre class="code prettyprint">var data = [
156
 
    {key:&quot;a&quot;, label:&quot;Column A&quot;},
157
 
    {key:&quot;b&quot;, label:&quot;Column B&quot;},
158
 
    {key:&quot;c&quot;, label:&quot;Column C&quot;}
159
 
],
160
 
 
161
 
myRecordset = new Y.Recordset({records:data});
162
 
 
163
 
&#x2F;&#x2F;overwite the record at index 2 with the following record
164
 
myRecordset.update({key:&quot;d&quot;, label:&quot;Column D&quot;}, 2);
165
 
 
166
 
&#x2F;&#x2F;You can also update multiple records at a time.
167
 
&#x2F;&#x2F;Here we are updating indices 0 and 1 of the Recordset with the corresponding two objects.
168
 
myRecordset.update([
169
 
    {key:&quot;e&quot;, label:&quot;Column E&quot;},
170
 
    {key: &quot;f&quot;, label: &quot;Column F&quot;}
171
 
], 0);</pre>
172
 
 
173
 
 
174
 
<h4 id="emptying-a-recordset">Emptying a Recordset</h4>
175
 
 
176
 
<pre class="code prettyprint">var data = [
177
 
    {key:&quot;a&quot;, label:&quot;Column A&quot;},
178
 
    {key:&quot;b&quot;, label:&quot;Column B&quot;},
179
 
    {key:&quot;c&quot;, label:&quot;Column C&quot;}
180
 
],
181
 
 
182
 
myRecordset = new Y.Recordset({records:data});
183
 
myRecordset.empty();</pre>
184
 
 
185
 
 
186
 
<h3 id="events">Events</h3>
187
 
 
188
 
<p>
189
 
    The Recordset Utility fires custom events in addition attribute change
190
 
    events. Details on these events are shown below. The sub-module responsible
191
 
    for firing each event is represented in square braces.
192
 
</p>
193
 
 
194
 
<table>
195
 
        <thead>
196
 
                <tr>
197
 
                        <th>Event [sub-module]</th>
198
 
                        <th>Payload</th>
199
 
                </tr>
200
 
        </thead>
201
 
        <tbody>
202
 
                <tr>
203
 
                        <td><code>add</code> [base]</td>
204
 
                        <td><strong>added:</strong> an array of new records that were added (can contain a single record)<br/>
205
 
                        <strong>index:</strong> index that the addition started at
206
 
                        </td>
207
 
                </tr>
208
 
                <tr>
209
 
                        <td><code>remove</code> [base]</td>
210
 
                        <td><strong>removed:</strong> an array of records that were removed (can contain a single record)<br/>
211
 
                        <strong>index:</strong> index that the removals started at<br/>
212
 
                                <strong>range:</strong> range of records that were removed
213
 
                        </td>
214
 
                </tr>
215
 
                <tr>
216
 
                        <td><code>update</code> [base]</td>
217
 
                        <td><strong>updated:</strong> an array of records that updated (added to the Recordset)<br/>
218
 
                        <strong>index:</strong> index that the updates started at<br/>
219
 
                                <strong>range:</strong> range of records that were updated
220
 
                        </td>
221
 
                </tr>
222
 
                <tr>
223
 
                        <td><code>empty</code> [base]</td>
224
 
                        <td>Empty object bag</td>
225
 
                </tr>
226
 
                <tr>
227
 
                        <td><code>change</code> [base]</td>
228
 
                        <td>Empty object bag, fired whenever records in the Recordset change (ie: they are added, removed, updated, or emptied)</td>
229
 
                </tr>
230
 
                <tr>
231
 
                        <td><code>sort</code> [sort]</td>
232
 
                        <td><strong>field:</strong> A string representing the key to sort by<br/>
233
 
                        <strong>desc:</strong> Boolean representing whether sorting order is descending<br/>
234
 
                                <strong>sorter:</strong> The comparison function being used to sort
235
 
                        </td>
236
 
                </tr>
237
 
        </tbody>
238
 
</table>
239
 
 
240
 
<h3 id="sorting">Sorting</h3>
241
 
 
242
 
<p>
243
 
    The <code>RecordsetSort</code> plugin allows a Recordset to have default
244
 
    and custom sorting functionality. Various helper methods and attributes are
245
 
    provided. A brief listing is shown below. Refer to the documentation for
246
 
    the <a href="recordset-sort.html">
247
 
    <code>RecordsetSort</code> plugin</a> to see code snippets.
248
 
</p>
249
 
 
250
 
<dl>
251
 
        <dt><code>sort(key,desc,function [optional])</code></dt>
252
 
                <dd>
253
 
            Sorts a Recordset by the value in the provided key. Recordset is
254
 
            sorted in descending order if <code>desc</code> is truthy. Optional
255
 
            custom comparison function can be supplied to sort by.
256
 
        </dd>
257
 
    <dt><code>resort()</code></dt>
258
 
        <dd>Resorts a Recordset using last-used sorting arguments</dd>
259
 
    <dt><code>reverse()</code></dt>
260
 
        <dd>Reverses the Recordset without performing any sort operations</dd>
261
 
    <dt><code>flip()</code></dt>
262
 
        <dd>
263
 
            Resorts the Recordset in ascending order if the last sort arguments
264
 
            specified descending, and vice versa.
265
 
        </dd>
266
 
    <dt><code>lastSortProperties Attribute</code></dt>
267
 
        <dd>
268
 
            An object bag with <code>field</code>, <code>desc</code> and
269
 
            <code>sorter</code> keys listing the last-used arguments to sort
270
 
            by.
271
 
        </dd>
272
 
    <dt><code>isSorted Attribute</code></dt>
273
 
        <dd>A boolean representing if the Recordset is in a sorted state.</dd>
274
 
</dl>
275
 
 
276
 
<h3 id="filtering">Filtering</h3>
277
 
 
278
 
<p>
279
 
    The <code>RecordsetFilter</code> plugin allows a Recordset to be filtered,
280
 
    and returns subsets of that Recordset (as a separate Recordset instance).
281
 
    Refer to the documentation for the <a
282
 
    href="recordset-filter.html">
283
 
    <code>RecordsetFilter</code> plugin to see code snippets.</a>
284
 
</p>
285
 
 
286
 
<dl>
287
 
        <dt><code>filter(key or function, value)</code></dt>
288
 
                <dd>
289
 
            If a key/value pair is passed in, returns a Recordset with records
290
 
            that match the key/value pair. Supports a custom function for more
291
 
            advanced filtering. The custom function must return a boolean.
292
 
        </dd>
293
 
    <dt><code>reject(function)</code></dt>
294
 
        <dd>
295
 
            The inverse of filter. Executes the supplied function on each item.
296
 
            Returns a new Recordset containing the items that the supplied
297
 
            function returned <code>false</code> for.
298
 
        </dd>
299
 
    <dt><code>grep(pattern)</code></dt>
300
 
        <dd>
301
 
            Iterates over the Recordset, returning a new Recordset of all the
302
 
            elements that match the supplied regular expression
303
 
        </dd>
304
 
</dl>
305
 
 
306
 
 
307
 
<h3 id="indexing">Indexing</h3>
308
 
 
309
 
<p>
310
 
    In the <code>recordset-base</code> submodule, the <code>table</code>
311
 
    attribute stores an associative array that hashes all records within the
312
 
    Recordset by their unique YUIDs. This table is kept in sync with the
313
 
    Recordset through custom events.
314
 
</p>
315
 
 
316
 
<p>
317
 
    To allow for customization when indexing, there is the
318
 
    <code>RecordsetIndexer</code> plugin. Refer to the <a
319
 
    href="recordset-indexer.html"><code>RecordsetIndexer</code>
320
 
    documentation</a> for full details.
321
 
</p>
322
 
 
323
 
 
324
 
<dl>
325
 
        <dt><code>createTable(key)</code></dt>
326
 
                <dd>
327
 
            Creates a hash table with the given key with all existing records
328
 
            in the Recordset.
329
 
        </dd>
330
 
    <dt><code>getTable(key)</code></dt>
331
 
        <dd>Get a hash table that hashes records by a given key.</dd>
332
 
    <dt><code>hashTables</code> attribute</dt>
333
 
        <dd>
334
 
            An object bag, with each property referring to a user-created hash
335
 
            table.
336
 
        </dd>
337
 
</dl>
338
 
</div>
339
 
            </div>
340
 
        </div>
341
 
 
342
 
        <div class="yui3-u-1-4">
343
 
            <div class="sidebar">
344
 
                
345
 
                    <div id="toc" class="sidebox">
346
 
                        <div class="hd">
347
 
                            <h2 class="no-toc">Table of Contents</h2>
348
 
                        </div>
349
 
 
350
 
                        <div class="bd">
351
 
                            <ul class="toc">
352
 
<li>
353
 
<a href="#getting-started">Getting Started</a>
354
 
</li>
355
 
<li>
356
 
<a href="#using">Using Recordsets</a>
357
 
<ul class="toc">
358
 
<li>
359
 
<a href="#basics">Recordset basics</a>
360
 
</li>
361
 
<li>
362
 
<a href="#crud">Adding, Removing, Updating and Emptying</a>
363
 
<ul class="toc">
364
 
<li>
365
 
<a href="#add">Adding Records</a>
366
 
</li>
367
 
<li>
368
 
<a href="#remove">Removing Records</a>
369
 
</li>
370
 
<li>
371
 
<a href="#updating-records">Updating Records</a>
372
 
</li>
373
 
<li>
374
 
<a href="#emptying-a-recordset">Emptying a Recordset</a>
375
 
</li>
376
 
</ul>
377
 
</li>
378
 
<li>
379
 
<a href="#events">Events</a>
380
 
</li>
381
 
<li>
382
 
<a href="#sorting">Sorting</a>
383
 
</li>
384
 
<li>
385
 
<a href="#filtering">Filtering</a>
386
 
</li>
387
 
<li>
388
 
<a href="#indexing">Indexing</a>
389
 
</li>
390
 
</ul>
391
 
</li>
392
 
</ul>
393
 
                        </div>
394
 
                    </div>
395
 
                
396
 
 
397
 
                
398
 
                    <div class="sidebox">
399
 
                        <div class="hd">
400
 
                            <h2 class="no-toc">Examples</h2>
401
 
                        </div>
402
 
 
403
 
                        <div class="bd">
404
 
                            <ul class="examples">
405
 
                                
406
 
                                    
407
 
                                        <li data-description="Shows how to instantiate and interact with a standard Recordset by adding, removing and updating records/objects. Explains the events that are fired, and shows how to access the built-in hash table that stores records by their YUIDs.">
408
 
                                            <a href="recordset-basic.html">Basic Recordset</a>
409
 
                                        </li>
410
 
                                    
411
 
                                
412
 
                                    
413
 
                                        <li data-description="Shows how to sort a Recordset using the default sorter, or a custom sort function. Additionally, demonstrates how convenience attributes help in determining when Recordset is in a sorted state, and what the last sort parameters were.">
414
 
                                            <a href="recordset-sort.html">Recordset Sort Plugin</a>
415
 
                                        </li>
416
 
                                    
417
 
                                
418
 
                                    
419
 
                                        <li data-description="Shows how to use filtering methods to Recordset. Key-value filtering, and filtering by providing a custom function are covered.">
420
 
                                            <a href="recordset-filter.html">Recordset Filter Plugin</a>
421
 
                                        </li>
422
 
                                    
423
 
                                
424
 
                                    
425
 
                                        <li data-description="Shows how to create and access hash tables on Recordset. Tables are kept in sync through events fired by Recordset.">
426
 
                                            <a href="recordset-indexer.html">Recordset Indexer Plugin</a>
427
 
                                        </li>
428
 
                                    
429
 
                                
430
 
                            </ul>
431
 
                        </div>
432
 
                    </div>
433
 
                
434
 
 
435
 
                
436
 
            </div>
437
 
        </div>
438
 
    </div>
439
 
</div>
440
 
 
441
 
<script src="../assets/vendor/prettify/prettify-min.js"></script>
442
 
<script>prettyPrint();</script>
443
 
 
444
 
</body>
445
 
</html>