|
1 | 1 | (function() { |
2 | 2 | 'use strict'; |
3 | 3 | /** |
4 | | - * Creates and maintains a synchronized list of data. This constructor should not be |
5 | | - * manually invoked. Instead, one should create a $firebase object and call $asArray |
6 | | - * on it: <code>$firebase( firebaseRef ).$asArray()</code>; |
| 4 | + * Creates and maintains a synchronized list of data. This is a pseudo-read-only array. One should |
| 5 | + * not call splice(), push(), pop(), et al directly on this array, but should instead use the |
| 6 | + * $remove and $add methods. |
7 | 7 | * |
8 | | - * Internally, the $firebase object depends on this class to provide 5 $$ methods, which it invokes |
9 | | - * to notify the array whenever a change has been made at the server: |
| 8 | + * It is acceptable to .sort() this array, but it is important to use this in conjunction with |
| 9 | + * $watch(), so that it will be re-sorted any time the server data changes. Examples of this are |
| 10 | + * included in the $watch documentation. |
| 11 | + * |
| 12 | + * Internally, the $firebase object depends on this class to provide several $$ (i.e. protected) |
| 13 | + * methods, which it invokes to notify the array whenever a change has been made at the server: |
10 | 14 | * $$added - called whenever a child_added event occurs |
11 | 15 | * $$updated - called whenever a child_changed event occurs |
12 | 16 | * $$moved - called whenever a child_moved event occurs |
|
22 | 26 | * |
23 | 27 | * Instead of directly modifying this class, one should generally use the $extend |
24 | 28 | * method to add or change how methods behave. $extend modifies the prototype of |
25 | | - * the array class by returning a clone of $FirebaseArray. |
| 29 | + * the array class by returning a clone of $firebaseArray. |
26 | 30 | * |
27 | 31 | * <pre><code> |
28 | | - * var ExtendedArray = $FirebaseArray.$extend({ |
| 32 | + * var ExtendedArray = $firebaseArray.$extend({ |
29 | 33 | * // add a new method to the prototype |
30 | 34 | * foo: function() { return 'bar'; }, |
31 | 35 | * |
|
43 | 47 | * var list = new ExtendedArray(ref); |
44 | 48 | * </code></pre> |
45 | 49 | */ |
46 | | - angular.module('firebase').factory('$FirebaseArray', ["$log", "$firebaseUtils", |
| 50 | + angular.module('firebase').factory('$firebaseArray', ["$log", "$firebaseUtils", |
47 | 51 | function($log, $firebaseUtils) { |
48 | 52 | /** |
49 | 53 | * This constructor should probably never be called manually. It is used internally by |
|
54 | 58 | * @constructor |
55 | 59 | */ |
56 | 60 | function FirebaseArray(ref) { |
| 61 | + if( !(this instanceof FirebaseArray) ) { |
| 62 | + return new FirebaseArray(ref); |
| 63 | + } |
57 | 64 | var self = this; |
58 | 65 | this._observers = []; |
59 | 66 | this.$list = []; |
60 | 67 | this._ref = ref; |
61 | 68 | this._sync = new ArraySyncManager(this); |
62 | 69 |
|
63 | 70 | $firebaseUtils.assertValidRef(ref, 'Must pass a valid Firebase reference ' + |
64 | | - 'to $FirebaseArray (not a string or URL)'); |
| 71 | + 'to $firebaseArray (not a string or URL)'); |
65 | 72 |
|
66 | 73 | // indexCache is a weak hashmap (a lazy list) of keys to array indices, |
67 | 74 | // items are not guaranteed to stay up to date in this list (since the data |
|
532 | 539 | */ |
533 | 540 | _assertNotDestroyed: function(method) { |
534 | 541 | if( this._isDestroyed ) { |
535 | | - throw new Error('Cannot call ' + method + ' method on a destroyed $FirebaseArray object'); |
| 542 | + throw new Error('Cannot call ' + method + ' method on a destroyed $firebaseArray object'); |
536 | 543 | } |
537 | 544 | } |
538 | 545 | }; |
|
548 | 555 | * methods to add onto the prototype. |
549 | 556 | * |
550 | 557 | * <pre><code> |
551 | | - * var ExtendedArray = $FirebaseArray.$extend({ |
| 558 | + * var ExtendedArray = $firebaseArray.$extend({ |
552 | 559 | * // add a method onto the prototype that sums all items in the array |
553 | 560 | * getSum: function() { |
554 | 561 | * var ct = 0; |
|
557 | 564 | * } |
558 | 565 | * }); |
559 | 566 | * |
560 | | - * // use our new factory in place of $FirebaseArray |
| 567 | + * // use our new factory in place of $firebaseArray |
561 | 568 | * var list = new ExtendedArray(ref); |
562 | 569 | * </code></pre> |
563 | 570 | * |
|
672 | 679 | return FirebaseArray; |
673 | 680 | } |
674 | 681 | ]); |
| 682 | + |
| 683 | + /** @deprecated */ |
| 684 | + angular.module('firebase').factory('$FirebaseArray', ['$log', '$firebaseArray', |
| 685 | + function($log, $firebaseArray) { |
| 686 | + return function() { |
| 687 | + $log.warn('$FirebaseArray has been renamed. Use $firebaseArray instead.'); |
| 688 | + return $firebaseArray.apply(null, arguments); |
| 689 | + }; |
| 690 | + } |
| 691 | + ]); |
675 | 692 | })(); |
0 commit comments