move polymer-selection into its own folder and add docs.

googlearchive · Aug 29, 2013 · fc7a303 · fc7a303
1 parent f9b466a
commit fc7a303
Show file tree

Hide file tree

Showing 4 changed files with 200 additions and 63 deletions.
diff --git a/polymer-selection/index.html b/polymer-selection/index.html
@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Selection</title>
+  <script src="../../polymer/polymer.js"></script>
+  <link rel="import" href="polymer-selection.html">
+</head>
+<body>
+<polymer-element name="selection-example">
+  <template>
+    <style>
+      /* @polyfill ul > * */
+      ::-webkit-distributed(> *) {
+        cursor: pointer;
+      }
+
+      /* @polyfill ul > .selected */
+      ::-webkit-distributed(> .selected) {
+        font-weight: bold;
+        font-style: italic;
+      }
+    </style>
+    <ul on-tap="itemTapAction">
+      <content></content>
+    </ul>
+    <polymer-selection id="selection" multi on-polymer-select="selectAction"></polymer-selection>
+    </template>
+    <script>
+    Polymer('selection-example', {
+      itemTapAction: function(e) {
+        this.$.selection.select(e.target);
+      },
+      selectAction: function(e, detail) {
+        detail.item.classList.toggle('selected', detail.isSelected);
+      }
+    });
+    </script>
+  </polymer-element>
+
+  <selection-example>
+    <li>Red</li>
+    <li>Green</li>
+    <li>Blue</li>
+  </selection-example>
+
+</body>
+</html>
diff --git a/polymer-selection/polymer-selection.html b/polymer-selection/polymer-selection.html
@@ -0,0 +1,152 @@
+<!--
+Copyright 2013 The Polymer Authors. All rights reserved.
+Use of this source code is governed by a BSD-style
+license that can be found in the LICENSE file.
+-->
+<!--
+/**
+ * @module Polymer Elements
+ */
+-->
+<!--
+/**
+ * The polymer-selection element is used to manage selection state. It has no
+ * visual appearance and is typically used in conjuneciton with another element.
+ * For example, <a href="polymer-selector.html">polymer-selector</a>
+ * use a polymer-selection to manage selection.
+ *
+ * To mark an item as selected, call the select(item) method on 
+ * polymer-selection. Notice that the item itself is an argument to this method.
+ * The polymer-selection element manages selection state for any given set of
+ * items. When an item is selected, the `polymer-select` event is fired.
+ * The attribute "multi" indicates if multiple items can be selected at once.
+ * 
+ * Example:
+ *   <polymer-element name="selection-example">
+ *     <template>
+ *       <style>
+ *         ::-webkit-distributed(> .selected) {
+ *           font-weight: bold;
+ *           font-style: italic;
+ *         }
+ *       </style>
+ *       <ul on-tap="itemTapAction">
+ *         <content></content>
+ *       </ul>
+ *       <polymer-selection id="selection" multi on-polymer-select="selectAction"></polymer-selection>
+ *     </template>
+ *     <sc ript>
+ *       Polymer('selection-example', {
+ *         itemTapAction: function(e) {
+ *           this.$.selection.select(e.target);
+ *         },
+ *         selectAction: function(e, detail) {
+ *           detail.item.classList.toggle('selected', detail.isSelected);
+ *         }
+ *       });
+ *     </sc ript>
+ *   </polymer-element>
+ *
+ *   <selection-example>
+ *     <li>Red</li>
+ *     <li>Green</li>
+ *     <li>Blue</li>
+ *   </selection-example>
+ *
+ * @class polymer-selection
+ */
+ /**
+ * Fired when an item's selection state is changed. This event is fired both
+ * when an item is selected or deselected. The `isSelected` detail property
+ * contains the selection state.
+ * 
+ * @event polymer-select
+ * @param {Object} detail
+ *   @param {boolean} detail.isSelected true for selection and false for deselection
+ *   @param {Object} detail.item the item element
+ */
+-->
+<polymer-element name="polymer-selection" attributes="multi">
+  <template>
+    <style>
+      @host {
+        * {
+          display: none !important;
+        }
+      }
+    </style>
+  </template>
+  <script>
+    Polymer('polymer-selection', {
+      /**
+       * If true, multiple selections are allowed.
+       *
+       * @attribute multi
+       * @type boolean
+       * @default false
+       */
+      multi: false,
+      created: function() {
+        this.clear();
+      },
+      clear: function() {
+        this.selection = [];
+      },
+      /**
+       * Retrieves the selected item(s).
+       * @method getSelection
+       * @returns Returns the selected item(s). If the multi property is true,
+       * getSelection will return an array, otherwise it will return 
+       * the selected item or undefined if there is no selection.
+      */
+      getSelection: function() {
+        return this.multi ? this.selection : this.selection[0];
+      },
+      /**
+       * Indicates if a given item is selected.
+       * @method isSelected
+       * @param {any} item: The item whose selection state should be checked.
+       * @returns Returns true if `item` is selected.
+      */
+      isSelected: function(item) {
+        return this.selection.indexOf(item) >= 0;
+      },
+      setItemSelected: function(item, isSelected) {
+        if (item) {
+          if (isSelected) {
+            this.selection.push(item);
+          } else {
+            var i = this.selection.indexOf(item);
+            if (i >= 0) {
+              this.selection.splice(i, 1);
+            }
+          }
+          this.fire("polymer-select", {isSelected: isSelected, item: item});
+        }
+      },
+      /**
+       * Set the selection state for a given `item`. If the multi property
+       * is true, then the selected state of `item` will be toggled; otherwise
+       * the `item` will be selected.
+       * @method select
+       * @param {any} item: The item to select.
+      */
+      select: function(item) {
+        if (this.multi) {
+          this.toggle(item);
+        } else if (this.getSelection() !== item) {
+          this.setItemSelected(this.getSelection(), false);
+          this.setItemSelected(item, true);
+        }
+      },
+      /**
+       * Toggles the selection state for `item`.
+       * @method toggle
+       * @param any} item: The item to toggle.
+      */
+      toggle: function(item) {
+        this.setItemSelected(item, !this.isSelected(item));
+      }
+    });
+  </script>
+</polymer-element>
diff --git a/polymer-selector/polymer-selection.html b/polymer-selector/polymer-selection.html
diff --git a/polymer-selector/polymer-selector.html b/polymer-selector/polymer-selector.html
@@ -54,7 +54,7 @@
  *   @param {Object} detail.item the item element
  */
 -->
-<link rel="import" href="polymer-selection.html">
+<link rel="import" href="../polymer-selection/polymer-selection.html">
 
 <polymer-element name="polymer-selector"
     attributes="selected multi valueattr selectedClass selectedProperty selectedItem selectedModel notap target itemsSelector activateEvent">