polymer/src/lib/template/array-selector.html

<!--
@license
Copyright (c) 2014 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
-->

<!--
Keeping structured data in sync requires that Polymer understand the path
associations of data being bound.  The `array-selector` element ensures path
linkage when selecting specific items from an array (either single or multiple).
The `items` property accepts an array of user data, and via the `select(item)`
and `deselect(item)` API, updates the `selected` property which may be bound to
other parts of the application, and any changes to sub-fields of `selected`
item(s) will be kept in sync with items in the `items` array.  When `multi`
is false, `selected` is a property representing the last selected item.  When
`multi` is true, `selected` is an array of multiply selected items.

```html
<dom-module id="employee-list">

  <template>

    <div> Employee list: </div>
    <template is="dom-repeat" id="employeeList" items="{{employees}}">
        <div>First name: <span>{{item.first}}</span></div>
        <div>Last name: <span>{{item.last}}</span></div>
        <button on-click="toggleSelection">Select</button>
    </template>

    <array-selector id="selector" items="{{employees}}" selected="{{selected}}" multi toggle></array-selector>

    <div> Selected employees: </div>
    <template is="dom-repeat" items="{{selected}}">
        <div>First name: <span>{{item.first}}</span></div>
        <div>Last name: <span>{{item.last}}</span></div>
    </template>

  </template>

  <script>
    Polymer({
      is: 'employee-list',
      ready: function() {
        this.employees = [
            {first: 'Bob', last: 'Smith'},
            {first: 'Sally', last: 'Johnson'},
            ...
        ];
      },
      toggleSelection: function(e) {
        var item = this.$.employeeList.itemForElement(e.target);
        this.$.selector.select(item);
      }
    });
  </script>

</dom-module>
```
-->

<script>

  Polymer({
    is: 'array-selector',

    properties: {

      /**
       * An array containing items from which selection will be made.
       */
      items: {
        type: Array,
        observer: 'clearSelection'
      },

      /**
       * When `true`, multiple items may be selected at once (in this case,
       * `selected` is an array of currently selected items).  When `false`,
       * only one item may be selected at a time.
       */
      multi: {
        type: Boolean,
        value: false,
        observer: 'clearSelection'
      },

      /**
       * When `multi` is true, this is an array that contains any selected.
       * When `multi` is false, this is the currently selected item, or `null`
       * if no item is selected.
       */
      selected: {
        type: Object,
        notify: true
      },

      /**
       * When `multi` is false, this is the currently selected item, or `null`
       * if no item is selected.
       */
      selectedItem: {
        type: Object,
        notify: true
      },

      /**
       * When `true`, calling `select` on an item that is already selected
       * will deselect the item.
       */
      toggle: {
        type: Boolean,
        value: false
      }
    },

    /**
     * Clears the selection state.
     *
     * @method clearSelection
     */
    clearSelection: function() {
      // Unbind previous selection
      if (Array.isArray(this.selected)) {
        for (var i=0; i<this.selected.length; i++) {
          this.unlinkPaths('selected.' + i);
        }
      } else {
        this.unlinkPaths('selected');
      }
      // Initialize selection
      if (this.multi) {
        if (!this.selected || this.selected.length) {
          this.selected = [];
          this._selectedColl = Polymer.Collection.get(this.selected);
        }
      } else {
        this.selected = null;
        this._selectedColl = null;
      }
      this.selectedItem = null;
    },

    /**
     * Returns whether the item is currently selected.
     *
     * @method isSelected
     * @param {*} item Item from `items` array to test
     * @return {boolean} Whether the item is selected
     */
    isSelected: function(item) {
      if (this.multi) {
        return this._selectedColl.getKey(item) !== undefined;
      } else {
        return this.selected == item;
      }
    },

    /**
     * Deselects the given item if it is already selected.
     *
     * @method isSelected
     * @param {*} item Item from `items` array to deselect
     */
    deselect: function(item) {
      if (this.multi) {
        if (this.isSelected(item)) {
          var skey = this._selectedColl.getKey(item);
          this.arrayDelete('selected', item);
          this.unlinkPaths('selected.' + skey);
        }
      } else {
        this.selected = null;
        this.selectedItem = null;
        this.unlinkPaths('selected');
        this.unlinkPaths('selectedItem');
      }
    },

    /**
     * Selects the given item.  When `toggle` is true, this will automatically
     * deselect the item if already selected.
     *
     * @method isSelected
     * @param {*} item Item from `items` array to select
     */
    select: function(item) {
      var icol = Polymer.Collection.get(this.items);
      var key = icol.getKey(item);
      if (this.multi) {
        if (this.isSelected(item)) {
          if (this.toggle) {
            this.deselect(item);
          }
        } else {
          this.push('selected', item);
          skey = this._selectedColl.getKey(item);
          this.linkPaths('selected.' + skey, 'items.' + key);
        }
      } else {
        if (this.toggle && item == this.selected) {
          this.deselect();
        } else {
          this.selected = item;
          this.selectedItem = item;
          this.linkPaths('selected', 'items.' + key);
          this.linkPaths('selectedItem', 'items.' + key);
        }
      }
    }

  });

</script>