diff --git a/demo/selection.html b/demo/selection.html index 6fd040f7c..c8de287e2 100644 --- a/demo/selection.html +++ b/demo/selection.html @@ -175,8 +175,8 @@

Select All with Data Source

} }, - _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 index 8f3184fa2..8a1df7856 100644 --- a/docs/vaadin-grid-selection.adoc +++ b/docs/vaadin-grid-selection.adoc @@ -5,31 +5,48 @@ layout: page --- [[vaadin-grid.selection]] -= Selection +== Selection -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. +By default, any number of items in the grid can be marked as selected, either programmatically or through the user interaction. +The rows representing the selections are highlighted visually, and the selected items are bi-directionally bound to the `selectedItems` property of the grid. -[[vaadin-grid.selection.mode]] -== Selection Mode +The following sections cover the basics on how to set up a column that provides a UI for selecting items, how to programmatically modify the selections, and how to bind to the selected state of items in column templates. -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. +[[vaadin-grid.selection.binding]] +== Binding to the Selection State + +The Two-way binding `selected` property inside templates can be used to allow users to select rows. + +[source,html] +---- + + + + + + + + + +---- [[vaadin-grid.selection.column]] -== The Selection Column Helper element. +== Using the Selection Column + +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. -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. +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] ---- - - + ---- @@ -39,16 +56,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] ---- - - - + @@ -59,7 +74,6 @@ Eventually, you can customize the selection column by displaying it at any posit - ---- @@ -67,20 +81,18 @@ Eventually, you can customize the selection column by displaying it at any posit 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#:: + 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 +102,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] +---- + + + + + + +----