third_party/polymer/components/core-selection/core-selection.html

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