third_party/polymer/polymer-selection/polymer-selection.html

   1 <!--
   2 Copyright 2013 The Polymer Authors. All rights reserved.
   3 Use of this source code is governed by a BSD-style
   4 license that can be found in the LICENSE file.
   5 -->
   6 <!--
   7 /**
   8  * @module Polymer Elements
   9  */
  10 -->
  11 <!--
  12 /**
  13  * The polymer-selection element is used to manage selection state. It has no
  14  * visual appearance and is typically used in conjuneciton with another element.
  15  * For example, <a href="polymer-selector.html">polymer-selector</a>
  16  * use a polymer-selection to manage selection.
  17  *
  18  * To mark an item as selected, call the select(item) method on
  19  * polymer-selection. Notice that the item itself is an argument to this method.
  20  * The polymer-selection element manages selection state for any given set of
  21  * items. When an item is selected, the `polymer-select` event is fired.
  22  * The attribute "multi" indicates if multiple items can be selected at once.
  23  *
  24  * Example:
  25  *
  26  *     <polymer-element name="selection-example">
  27  *        <template>
  28  *          <style>
  29  *            ::-webkit-distributed(> .selected) {
  30  *              font-weight: bold;
  31  *              font-style: italic;
  32  *            }
  33  *          </style>
  34  *          <ul on-tap="{{itemTapAction}}">
  35  *            <content></content>
  36  *          </ul>
  37  *          <polymer-selection id="selection" multi on-polymer-select="{{selectAction}}"></polymer-selection>
  38  *        </template>
  39  *        <script>
  40  *          Polymer('selection-example', {
  41  *            itemTapAction: function(e) {
  42  *              this.$.selection.select(e.target);
  43  *            },
  44  *            selectAction: function(e, detail) {
  45  *              detail.item.classList.toggle('selected', detail.isSelected);
  46  *            }
  47  *          });
  48  *        </script>
  49  *     </polymer-element>
  50  *
  51  *     <selection-example>
  52  *       <li>Red</li>
  53  *       <li>Green</li>
  54  *       <li>Blue</li>
  55  *     </selection-example>
  56  *
  57  * @class polymer-selection
  58  */
  59  /**
  60  * Fired when an item's selection state is changed. This event is fired both
  61  * when an item is selected or deselected. The `isSelected` detail property
  62  * contains the selection state.
  63  *
  64  * @event polymer-select
  65  * @param {Object} detail
  66  *   @param {boolean} detail.isSelected true for selection and false for deselection
  67  *   @param {Object} detail.item the item element
  68  */
  69 -->
  70 <link rel="import" href="../polymer/polymer.html">
  71
  72 <polymer-element name="polymer-selection" attributes="multi">
  73   <template>
  74     <style>
  75       :host {
  76         display: none !important;
  77       }
  78     </style>
  79   </template>
  80   <script>
  81     Polymer('polymer-selection', {
  82       /**
  83        * If true, multiple selections are allowed.
  84        *
  85        * @attribute multi
  86        * @type boolean
  87        * @default false
  88        */
  89       multi: false,
  90       ready: function() {
  91         this.clear();
  92       },
  93       clear: function() {
  94         this.selection = [];
  95       },
  96       /**
  97        * Retrieves the selected item(s).
  98        * @method getSelection
  99        * @returns Returns the selected item(s). If the multi property is true,
 100        * getSelection will return an array, otherwise it will return
 101        * the selected item or undefined if there is no selection.
 102       */
 103       getSelection: function() {
 104         return this.multi ? this.selection : this.selection[0];
 105       },
 106       /**
 107        * Indicates if a given item is selected.
 108        * @method isSelected
 109        * @param {any} item The item whose selection state should be checked.
 110        * @returns Returns true if `item` is selected.
 111       */
 112       isSelected: function(item) {
 113         return this.selection.indexOf(item) >= 0;
 114       },
 115       setItemSelected: function(item, isSelected) {
 116         if (item !== undefined && item !== null) {
 117           if (isSelected) {
 118             this.selection.push(item);
 119           } else {
 120             var i = this.selection.indexOf(item);
 121             if (i >= 0) {
 122               this.selection.splice(i, 1);
 123             }
 124           }
 125           this.fire("polymer-select", {isSelected: isSelected, item: item});
 126         }
 127       },
 128       /**
 129        * Set the selection state for a given `item`. If the multi property
 130        * is true, then the selected state of `item` will be toggled; otherwise
 131        * the `item` will be selected.
 132        * @method select
 133        * @param {any} item: The item to select.
 134       */
 135       select: function(item) {
 136         if (this.multi) {
 137           this.toggle(item);
 138         } else if (this.getSelection() !== item) {
 139           this.setItemSelected(this.getSelection(), false);
 140           this.setItemSelected(item, true);
 141         }
 142       },
 143       /**
 144        * Toggles the selection state for `item`.
 145        * @method toggle
 146        * @param {any} item: The item to toggle.
 147       */
 148       toggle: function(item) {
 149         this.setItemSelected(item, !this.isSelected(item));
 150       }
 151     });
 152   </script>
 153 </polymer-element>