Reviewer suggestions

vaadin · Dec 15, 2016 · 2964b6f · 2964b6f
1 parent caebe0c
commit 2964b6f
Show file tree

Hide file tree

Showing 2 changed files with 71 additions and 26 deletions.
diff --git a/demo/selection.html b/demo/selection.html
@@ -175,8 +175,8 @@ <h3>Select All with Data Source</h3>
                 }
               },
 
-              _isSelected: function(selectAll, selected) {
-                return this.inverted != selected;
+              _isSelected: function(inverted, selected) {
+                return inverted != selected;
               }
             });
           });

diff --git a/docs/vaadin-grid-selection.adoc b/docs/vaadin-grid-selection.adoc
@@ -4,32 +4,42 @@ order: 3
 layout: page
 ---
 
-[[vaadin-grid.selection]]
-= Selection
+[[vaadin-grid.selection.binding]]
+== Binding to the Selection State
 
-Grid allows item based selection of data rows either through UI interaction or using the JavaScript API.
-The selection behavior depends on the currently active selection mode.
+[vaadinelement]#vaadin-grid# includes a multi selection behavior by default.
+Two-way binding selected variable inside templates can be used to allow users to select rows.
 
-[[vaadin-grid.selection.mode]]
-== Selection Mode
-
-The [vaadinelement]#vaadin-grid# implements multi selection behavior by default. But you need a mechanisim to allow the user to select rows. The easier way is to use the [vaadinelement]#vaadin-grid-selection-column# helper element.
+[source,html]
+----
+<vaadin-grid items='["One", "Two", "Tree"]'>
+  <vaadin-grid-column>
+    <template>
+      <paper-checkbox checked="{{selected}}"></paper-checkbox>
+    </template>
+  </vaadin-grid-column>
+  <vaadin-grid-column width="50px">
+    <template class="header">Number</template>
+    <template>[[item]]</template>
+  </vaadin-grid-column>
+</vaadin-grid>
+----
 
 [[vaadin-grid.selection.column]]
-== The Selection Column Helper element.
+== Using the Selection Column
 
-The [vaadinelement]#vaadin-grid-selection-column# provides a selection model that helps the user to select rows using checkboxes displayed in a specific column.
-In the case that the grid use an array of items as the data source, it provides the ability of selecting all the items by clicking on the checkbox at the header.
+You can use the [vaadinelement]#vaadin-grid-selection-column# helper element to get default templates and functionality for the selection. With it the user can select rows using checkboxes displayed in a column.
+
+When [vaadinelement]#vaadin-grid# is configured with an array of items as the data source, the [vaadinelement]#vaadin-grid-selection-column# provides the feature of selecting all the items by clicking on the checkbox in the header.
 
 [source,html]
 ----
-<link rel="import" href="../vaadin-grid-selection-column.html">
-
 <vaadin-grid items='["One", "Two", "Tree"]'>
   <vaadin-grid-selection-column>
   </vaadin-grid-selection-column>
   <vaadin-grid-column width="50px">
     <template class="header">Number</template>
+    <template>[[item]]</template>
   </vaadin-grid-column>
 </vaadin-grid>
 ----
@@ -39,16 +49,14 @@ NOTE: that you have to explicitly import the element in your component in order
 [[figure.vaadin-grid.selection.column]]
 image::img/vaadin-grid-selection-column.png[]
 
-Eventually, you can customize the selection column by displaying it at any position in the grid, changing it size, or even providing a different template for checkboxes.
+In addition, you can customize the selection column by changing its width, flex, frozen properties, or by providing your own templates.
 
 [source,html]
 ----
-<link rel="import" href="../vaadin-grid/vaadin-grid-selection-column.html">
-<link rel="import" href="../polymer-checkbox/polymer-checkbox.html">
-
 <vaadin-grid items='["One", "Two", "Tree"]'>
   <vaadin-grid-column width="50px">
     <template class="header">Number</template>
+    <template>[[item]]</template>
   </vaadin-grid-column>
 
   <vaadin-grid-selection-column width="40px" flex="0" select-all="[[selectAll]]">
@@ -59,28 +67,25 @@ Eventually, you can customize the selection column by displaying it at any posit
       <paper-checkbox checked="{{selected}}"></paper-checkbox>
     </template>
   </vaadin-grid-selection-column>
-
 </vaadin-grid>
 ----
 
 [[figure.vaadin-grid.selection.column]]
 image::img/vaadin-grid-selection-column-custom.png[]
 
 [[vaadin-grid.selection.api]]
-== Selection API
+== Using the Selection API
 
 This section explains the basic operations available through the selection API.
 
 [methodname]#grid.selectItem(item)#::
-  Selects the row with the given item. If the selection mode is `single`, the method deselects the previously selected row.
+  Selects the row with the given item.
 
 [methodname]#grid.deselectItem(item)#::
   Deselects the row with the given item.
 
-[[vaadin-grid.selection.selected]]
-== Accessing the Selected Rows
-
-The [vaadinelement]#vaadin-grid# defines a property [propertyname]#selectedItems# that represents the list of selected items. It also notifies changes to it by firing a 'selected-items-changed' -event.
+[propertyname]#selectedItems#::
+  It's the property that represents the Array of currently selected items. You can either use `selectItem` or `deselectItem` methods to modify the Array, or modify the `selectedItems` array directly by using Polymer's array mutation API.
 
 [source,javascript]
 ----
@@ -90,3 +95,43 @@ grid.addEventListener('selected-items-changed', function() {
   console.log('Selected: ' + grid.selectedItems);
 });
 ----
+
+[[vaadin-grid.selection.selecteditems]]
+== Customizing the Selection behavior
+
+In case you want to modify the default selection behavior, you can interact directly with the `selectedItems` array.
+
+For instance in the next example, we implement a single selection model by setting the `selectedItems` property with the last selected item.
+
+[source,javascript]
+----
+<grid-single-selection></grid-single-selection>
+
+<dom-module id="grid-single-selection">
+  <template>
+    <vaadin-grid id="grid" items='["One", "Two", "Tree"]'>
+      <vaadin-grid-column width="50px">
+        <template class="header">Number</template>
+        <template>[[item]]</template>
+      </vaadin-grid-column>
+
+      <vaadin-grid-column width="40px" flex="0">
+        <template>
+          <input type="checkbox" on-change="_onSelectionChange" checked="[[selected]]"></input>
+        </template>
+      </vaadin-grid-column>
+    </vaadin-grid>
+  </template>
+  <script>
+  document.addEventListener('WebComponentsReady', function() {
+    Polymer({
+      is: 'grid-single-selection',
+
+      _onSelectionChange: function(e) {
+        this.$.grid.selectedItems = e.target.checked ? [e.model.item] : [];
+      }
+    });
+  });
+  </script>
+</dom-module>
+----