firebase-collection.html

<!--
@license
Copyright (c) 2015 The Polymer Project Authors. All rights reserved.
This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
Code distributed by Google as part of the polymer project is also
subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
-->

<link rel="import" href="../polymer/polymer.html">
<link rel="import" href="firebase-query-behavior.html">

<!--
* **Note: This element is for the older Firebase 2 API**

For the latest official Firebase 3.0-compatible component from the Firebase team,
see the [polymerfire](https://github.com/firebase/polymerfire) component.
In this new component, the `firebase-collection` element has been replaced
with [`firebase-query`](https://github.com/firebase/polymerfire#firebase-query)

An element wrapper for the Firebase API that provides a view into the provided
Firebase location as an ordered collection.

By default, Firebase yields values as unsorted document objects, where each of
the children are accessible via object keys. The `<firebase-collection>`
element allows Firebase API orderBy*, limitTo* and other query-oriented methods
to be specified declaratively. The element then produces and maintains an Array
of ordered child items of the document that is convenient for iterating over
in other elements such as `<template is="dom-repeat">`.

Example:

      <template is="dom-bind">
        <firebase-collection
          order-by-child="height"
          limit-to-first="3"
          location="https://dinosaur-facts.firebaseio.com/dinosaurs"
          data="{{dinosaurs}}"></firebase-collection>
        <template is="dom-repeat" items="[[dinosaurs]]" as="dinosaur">
          <h4>[[dinosaur.__firebaseKey__]]</h4>
          Height: <span>[[dinosaur.height]]</span>m
        </template>
      </template>

As you may have noticed above, the original key of each item is available as
the `__firebaseKey__` property on the item.

The element makes special accomodations for documents whose children are
primitive values. A primitive value is wrapped in an object with the form:

```javascript
{
  value: /* original primitive value */
  __firebaseKey__: /* key of primitive value in parent document */
}
```

Accessor methods such as `add` and `remove` are provided to enable convenient
manipulation of the collection without direct knowledge of Firebase key values.

@demo demo/index.html
-->

<script>
  (function() {
    'use strict'

    var FirebaseCollection = Polymer({
      is: 'firebase-collection',

      behaviors: [
        Polymer.FirebaseQueryBehavior
      ],

      properties: {
        /**
         * A pointer to the current Firebase Query instance being used to
         * populate `data`.
         */
        query: {
          type: Object,
          notify: true,
          computed: '_computeQuery(location, limitToFirst, limitToLast, _orderByMethodName, _startAt, _endAt, _equalTo)',
          observer: '_queryChanged'
        },

        /**
         * An ordered array of data items produced by the current Firebase Query
         * instance.
         */
        data: {
          type: Array,
          readOnly: true,
          notify: true,
          value: function() {
            return [];
          }
        },

        /**
         * Specify a child key to order the set of records reflected on the
         * client.
         */
        orderByChild: {
          type: String,
          value: null,
          reflectToAttribute: true
        },

        /**
         * Specify to order by key the set of records reflected on the client.
         */
        orderByKey: {
          type: Boolean,
          value: false,
          reflectToAttribute: true
        },

        /**
         * Specify to order by value the set of records reflected on the client.
         */
        orderByValue: {
          type: Boolean,
          value: false,
          reflectToAttribute: true
        },

        /**
         * Specify to order by priority the set of records reflected on the
         * client.
         */
        orderByPriority: {
          type: Boolean,
          value: false,
          reflectToAttribute: true
        },

        /**
         * Specify a maximum number of records reflected on the client limited to
         * the first certain number of children.
         */
        limitToFirst: {
          type: Number,
          value: null,
          reflectToAttribute: true,
        },

        /**
         * Specify a maximum number of records reflected on the client limited to
         * the last certain number of children.
         */
        limitToLast: {
          type: Number,
          value: null,
          reflectToAttribute: true
        },

        /**
         * Specify a start record for the set of records reflected in the
         * collection.
         */
        startAt: {
          type: String,
          value: null,
          reflectToAttribute: true
        },

        /**
         * Specify an end record for the set of records reflected in the
         * collection.
         */
        endAt: {
          type: String,
          value: null,
          reflectToAttribute: true
        },

        /**
         * Specify to create a query which includes children which match the
         * specified value. The argument type depends on which orderBy*() function
         * was used in this query. Specify a value that matches the orderBy*()
         * type.
         */
        equalTo: {
          type: String,
          value: null,
          reflectToAttribute: true
        },

        /**
         * Specify to override the type used when deserializing the value of
         * `start-at`, `end-at` and `equal-to` attributes. By default, these
         * values are always deserialized as `String`, but sometimes it is
         * preferrable to deserialize these values as e.g., `Number`.
         *
         * Accepted values for this attribute, and their corresponding
         * deserialization types, are as follows:
         *
         *  - `string` => `String` (default)
         *  - `number` => `Number`
         *  - `boolean` => `Boolean`
         */
        orderValueType: {
          type: String,
          value: 'string',
          reflectToAttribute: true
        },

        _valueMap: {
          type: Object,
          value: function() {
            return {};
          }
        },

        _orderByMethodName: {
          computed: '_computeOrderByMethodName(orderByChild, orderByKey, orderByValue, orderByPriority)'
        },

        _orderByTypeCast: {
          computed: '_computeOrderByTypeCast(orderByChild, orderByKey, orderByValue, orderByPriority, orderValueType)'
        },

        _startAt: {
          computed: '_computeStartAt(startAt, _orderByTypeCast)'
        },

        _endAt: {
          computed: '_computeEndAt(endAt, _orderByTypeCast)'
        },

        _equalTo: {
          computed: '_computeEqualTo(equalTo, _orderByTypeCast)'
        }
      },

      listeners: {
        'firebase-child-added': '_onFirebaseChildAdded',
        'firebase-child-removed': '_onFirebaseChildRemoved',
        'firebase-child-changed': '_onFirebaseChildChanged',
        'firebase-child-moved': '_onFirebaseChildMoved',
      },

      created: function() {
        this._pendingSplices = [];
        this._lastLocallyAddedIndex = null;
      },

      /**
       * Add an item to the document referenced at `location`. A key associated
       * with the item will be created by Firebase, and can be accessed via the
       * Firebase Query instance returned by this method.
       *
       * If the query is not yet properly defined as it can be the case for bound location, the `query-error` event is fired.
       *
       * @param {Object} data A value to add to the document.
       * @return {Object} A Firebase Query instance referring to the added item.
       */
      add: function(data) {
        var query;

        this._log('Adding new item to collection with value:', data);

        if (!this.query) {
          this._fireQueryError('Query does not exist');
          return;
        }

        query = this.query.ref().push();
        query.set(data);

        return query;
      },

      /**
       * Remove an item from the document referenced at `location`. The item
       * is assumed to be an identical reference to an item already in the
       * `data` Array.
       *
       * @param {Object} data An identical reference to an item in `this.data`.
       */
      remove: function(data) {
        if (data == null || data.__firebaseKey__ == null) {
          // NOTE(cdata): This might be better as an error message in the
          // console, but `Polymer.Base._error` throws, which we don't want
          // to happen in this case.
          this._warn('Refusing to remove unknown value:', data);
          return;
        }

        this._log('Removing collection item "' + data.__firebaseKey__ + '"', data.value);

        this.removeByKey(data.__firebaseKey__);
      },

      /**
       * Look up an item in the local `data` Array by key.
       *
       * @param {String} key The key associated with the item in the parent
       * document.
       */
      getByKey: function(key) {
        return this._valueMap[key];
      },

      /**
       * Remove an item from the document associated with `location` by key.
       *
       * @param {String} key The key associated with the item in the document
       * located at `location`.
       */
      removeByKey: function(key) {
        if (!this.query) {
          this._error('Cannot remove items before query has been initialized.');
          return;
        }

        this.query.ref().child(key).remove();
      },

      _localDataChanged: function(change) {
        var pathParts = change.path.split('.');

        // We don't care about self-changes, and we don't respond directly to
        // length changes:
        if (pathParts.length < 2 || pathParts[1] === 'length') {
          return;
        }

        // Handle splices via the adoption process. `indexSplices` is known to
        // sometimes be null, so guard against that.
        if (pathParts[1] === 'splices' && change.value.indexSplices != null) {
          this._adoptSplices(change.value.indexSplices);
          return;
        }

        // Otherwise, the change is happening to a sub-path of the array.
        this._applySubPathChange(change);
      },

      _applySubPathChange: function(change) {

        if (!this.query) {
          this._fireQueryError('Query does not exist');
          return;
        }

        var key = change.path.split('.')[1];
        var value = Polymer.Collection.get(change.base).getItem(key);
        var firebaseKey = value.__firebaseKey__;

        // We don't want to accidentally reflect `__firebaseKey__` in the
        // remote data, so we remove it temporarily. `null` values will be
        // discarded by Firebase, so `delete` is not necessary:
        value.__firebaseKey__ = null;
        this.query.ref().child(firebaseKey).set(value);
        value.__firebaseKey__ = firebaseKey;
      },

      _adoptSplices: function(splices) {
        this._pendingSplices = this._pendingSplices.concat(splices);

        // We can afford apply removals synchronously, so we do that first
        // and save the `added` operations for the `debounce` below.
        this._applyLocalDataChange(function() {
          splices.forEach(function(splice) {
            splice.removed.forEach(function(removed) {
              this.remove(removed);
            }, this);
          }, this);
        });

        // We async until the next turn. The reason we want to do this is
        // that splicing within a splice handler will break the data binding
        // system in some places. This is referred to as the "re-entrancy"
        // problem. See polymer/polymer#2491.
        this.debounce('_adoptSplices', function() {
          this._applyLocalDataChange(function() {
            var splices = this._pendingSplices;

            this._pendingSplices = [];

            splices.forEach(function(splice) {
              var added = splice.object.slice(splice.index, splice.index + splice.addedCount);

              added.forEach(function(added, index) {
                this._lastLocallyAddedIndex = splice.index + index;
                this.add(added);
              }, this);
            }, this);

            this._lastLocallyAddedIndex = null;
          });
        });
      },

      _computeQuery: function(location, limitToFirst, limitToLast, orderByMethodName, startAt, endAt, equalTo) {
        var query;

        if (!location) {
          return;
        }

        this._log('Recomputing query.', arguments);

        try {
          query = new Firebase(location);

          if (orderByMethodName) {
            if (orderByMethodName === 'orderByChild') {
              query = query[orderByMethodName](this.orderByChild);
            } else {
              query = query[orderByMethodName]();
            }
          }

          if (startAt != null) {
            query = query.startAt(startAt);
          }

          if (endAt != null) {
            query = query.endAt(endAt);
          }

          if (equalTo != null) {
            query = query.equalTo(equalTo);
          }

          if (limitToLast != null) {
            query = query.limitToLast(limitToLast);
          }

          if (limitToFirst != null) {
            query = query.limitToFirst(limitToFirst);
          }

        } catch(e) {

          this._fireQueryError('Query cannot be instantiated with location ' + location + ' (' + e.toString() + ')');

        } finally {

          return query;

        }

      },

      _queryChanged: function() {
        this._valueMap = {};
        this._setData([]);
        Polymer.FirebaseQueryBehavior._queryChanged.apply(this, arguments);
      },

      _computeOrderByMethodName: function(orderByChild, orderByKey, orderByValue, orderByPriority) {
        if (orderByChild) {
          return 'orderByChild';
        }

        if (orderByKey) {
          return 'orderByKey';
        }

        if (orderByValue) {
          return 'orderByValue';
        }

        if (orderByPriority) {
          return 'orderByPriority';
        }

        return null;
      },

      _computeOrderByTypeCast: function(orderByChild, orderByKey, orderByValue, orderByPriority, orderValueType) {
        return function typeCast(value) {
          if (!orderByKey &&
              value != null &&
              FirebaseCollection.ORDER_VALUE_TYPES[orderValueType]) {
            return FirebaseCollection.ORDER_VALUE_TYPES[orderValueType](value);
          }

          return value;
        };
      },

      _computeStartAt: function(startAt, orderByTypeCast) {
        return orderByTypeCast(startAt);
      },

      _computeEndAt: function(endAt, orderByTypeCast) {
        return orderByTypeCast(endAt);
      },

      _computeEqualTo: function(equalTo, orderByTypeCast) {
        return orderByTypeCast(equalTo);
      },

      _valueFromSnapshot: function(snapshot) {
        var value = snapshot.val();

        if (!(value instanceof Object)) {
          value = {
            value: value,
            __firebasePrimitive__: true
          };
        }

        value.__firebaseKey__ = snapshot.key();

        return value;
      },

      _valueToPersistable: function(value) {
        var persistable;

        if (value.__firebasePrimitive__) {
          return value.value;
        }

        persistable = {};

        for (var property in value) {
          if (property === '__firebaseKey__') {
            continue;
          }

          persistable[property] = value[property];
        }

        return persistable;
      },

      _onFirebaseChildAdded: function(event) {
        this._applyRemoteDataChange(function() {
          var value = this._valueFromSnapshot(event.detail.childSnapshot);
          var key = value.__firebaseKey__;
          var previousValueKey = event.detail.previousChildName;
          var index = previousValueKey != null ?
            this.data.indexOf(this._valueMap[previousValueKey]) + 1 : 0;
          var lastLocallyAddedValue;

          this._valueMap[value.__firebaseKey__] = value;

          // NOTE(cdata): The rationale for this conditional dance around the
          // last locally added index (since you will inevitably be wondering
          // why we do it):
          // There may be a "locally" added value which was spliced in. If
          // there is, it may be in the "wrong" place in the array. This is
          // due to the fact that Firebase may be applying a sort to the
          // data, so we won't know the correct index for the locally added
          // value until the `child_added` event is fired.
          // Once we get the `child_added` event, we can check to see if the
          // locally added value is in the right place. If it is, we just
          // `set` it to the Firebase-provided value. If it is not, then
          // we grab the original value, splice in the Firebase-provided
          // value in the right place, and then (importantly: at the end)
          // find the locally-added value again (since its index may have
          // changed by splicing-in Firebase's value) and splice it out of the
          // array.
          if (this._lastLocallyAddedIndex === index) {
            this.set(['data', index], value);
          } else {
            if (this._lastLocallyAddedIndex != null) {
              lastLocallyAddedValue = this.data[this._lastLocallyAddedIndex];
            }

            this.splice('data', index, 0, value);

            if (this._lastLocallyAddedIndex != null) {
              this.splice('data', this.data.indexOf(lastLocallyAddedValue), 1);
            }
          }
        });
      },

      _onFirebaseChildRemoved: function(event) {
        if (this._receivingLocalChanges) {
          this._valueMap[event.detail.oldChildSnapshot.key()] = null;
          // NOTE(cdata): If we are receiving local changes, that means that
          // the splices have already been performed and items are already
          // removed from the local data representation. No need to remove
          // them again.
          return;
        }

        this._applyRemoteDataChange(function() {
          var key = event.detail.oldChildSnapshot.key();
          var value = this._valueMap[key];
          var index;

          if (!value) {
            this._error('Received firebase-child-removed event for unknown child "' + key + '"');
            return;
          }

          index = this.data.indexOf(value);
          this._valueMap[key] = null;

          if (index !== -1) {
            this.splice('data', index, 1);
          }
        });
      },

      _onFirebaseChildChanged: function(event) {
        this._applyRemoteDataChange(function() {
          var value = this._valueFromSnapshot(event.detail.childSnapshot);
          var oldValue = this._valueMap[value.__firebaseKey__];

          if (!oldValue) {
            this._error('Received firebase-child-changed event for unknown child "' + value.__firebaseKey__ + '"');
            return;
          }

          this._valueMap[oldValue.__firebaseKey__] = null;
          this._valueMap[value.__firebaseKey__] = value;
          this.set('data.' + this.data.indexOf(oldValue), value);
        });
      },

      _onFirebaseChildMoved: function(event) {
        this._applyRemoteDataChange(function() {
          var key = event.detail.childSnapshot.key();
          var value = this._valueMap[key];
          var previousChild;
          var newIndex;
          var currentIndex;
          var previousIndex;

          if (!value) {
            this._error('Received firebase-child-moved event for unknown child "' + key + '"');
            return;
          }

          previousChild = event.detail.previousChildName != null ?
            this._valueMap[event.detail.previousChildName] : null;

          currentIndex = this.data.indexOf(value);
          previousIndex = previousChild ? this.data.indexOf(previousChild) : -1;
          newIndex = currentIndex > previousIndex ? previousIndex + 1 : previousIndex;

          this.splice('data', currentIndex, 1);
          this.splice('data', newIndex, 0, value);
        });
      }
    });

    FirebaseCollection.ORDER_VALUE_TYPES = {
      string: String,
      number: Number,
      boolean: Boolean
    };
  })();
</script>