-
Notifications
You must be signed in to change notification settings - Fork 201
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
refactor: move Grid Selection section to separate page (#4024)
- Loading branch information
Showing
2 changed files
with
152 additions
and
147 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -22,6 +22,7 @@ Some of the more complex features of this component are described on separate ta | |
| * <<columns#, Columns>> | ||
| * <<renderers#, Renderers>> | ||
| * <<styling#, Styling>> | ||
| * <<selection#, Selection>> | ||
| * <<drag-drop#, Drag & Drop>> | ||
| * <<inline-editing#, Inline Editing (Flow)>> | ||
|
|
||
|
|
@@ -98,153 +99,6 @@ endif::[] | |
| -- | ||
|
|
||
|
|
||
| == Selection | ||
|
|
||
| Grid supports single and multi-select modes. Neither is enabled by default. | ||
|
|
||
|
|
||
| === Single-Selection Mode | ||
|
|
||
| In single-selection mode, the user can select and deselect rows by clicking anywhere on the row. | ||
|
|
||
| [.example] | ||
| -- | ||
|
|
||
| ifdef::lit[] | ||
| [source,typescript] | ||
| ---- | ||
| include::{root}/frontend/demo/component/grid/grid-single-selection-mode.ts[render,tags=snippet,indent=0,group=Lit] | ||
| ---- | ||
| endif::[] | ||
|
|
||
| ifdef::flow[] | ||
| [source,java] | ||
| ---- | ||
| include::{root}/src/main/java/com/vaadin/demo/component/grid/GridSingleSelectionMode.java[render,tags=snippet,indent=0,group=Flow] | ||
| ---- | ||
| endif::[] | ||
|
|
||
| ifdef::react[] | ||
| [source,tsx] | ||
| ---- | ||
| include::{root}/frontend/demo/component/grid/react/grid-single-selection-mode.tsx[render,tags=snippet,indent=0,group=React] | ||
| ---- | ||
| endif::[] | ||
| -- | ||
|
|
||
|
|
||
| === Multi-Select Mode | ||
|
|
||
| In multi-select mode, the user can use a checkbox column to select and deselect more than one row -- not necessarily contiguous rows. Or the user can select all rows by clicking on the checkbox in the header row -- and then un-check the ones they don't want to be selected, rather than check many, individually. | ||
|
|
||
| [.example] | ||
| -- | ||
|
|
||
| ifdef::lit[] | ||
| [source,typescript] | ||
| ---- | ||
| include::{root}/frontend/demo/component/grid/grid-multi-select-mode.ts[render,tags=snippet,indent=0,group=Lit] | ||
| ---- | ||
| endif::[] | ||
|
|
||
| ifdef::flow[] | ||
| [source,java] | ||
| ---- | ||
| include::{root}/src/main/java/com/vaadin/demo/component/grid/GridMultiSelectionMode.java[render,tags=snippet,indent=0,group=Flow] | ||
| ---- | ||
| endif::[] | ||
|
|
||
| ifdef::react[] | ||
| [source,tsx] | ||
| ---- | ||
| include::{root}/frontend/demo/component/grid/react/grid-multi-select-mode.tsx[render,tags=snippet,indent=0,group=React] | ||
| ---- | ||
| endif::[] | ||
| -- | ||
|
|
||
| In addition to selecting rows individually, a range of rows can be selected by dragging from one selection checkbox to another, if enabled: | ||
|
|
||
| [.example] | ||
| -- | ||
|
|
||
| [source,typescript] | ||
| ---- | ||
| <source-info group="Lit"></source-info> | ||
| <vaadin-grid .items="${this.items}"> | ||
| <vaadin-grid-selection-column drag-select></vaadin-grid-selection-column> | ||
| ... | ||
| </vaadin-grid> | ||
| ---- | ||
| [source,java] | ||
| ---- | ||
| <source-info group="Flow"></source-info> | ||
| Grid<Person> g = new Grid<>(); | ||
| g.setSelectionMode(SelectionMode.MULTI); | ||
| GridMultiSelectionModel<Person> selectionModel = (GridMultiSelectionModel<Person>)g.getSelectionModel(); | ||
| selectionModel.setDragSelect(true); | ||
| ---- | ||
| [source,tsx] | ||
| ---- | ||
| <source-info group="React"></source-info> | ||
| <Grid items={items}> | ||
| <GridSelectionColumn dragSelect /> | ||
| ... | ||
| </Grid> | ||
| ---- | ||
|
|
||
| -- | ||
|
|
||
| === Selection Modes in Flow | ||
|
|
||
| Each selection mode is represented by a [classname]`GridSelectionModel`, accessible through the [methodname]`getSelectionModel()` method, which can be cast that to the specific selection model type, [classname]`SingleSelectionModel` or [classname]`MultiSelectionModel`. These interfaces provide selection mode specific APIs for configuration and selection events. | ||
|
|
||
| To use Grid with [classname]`Binder` in Flow, you can use [methodname]`asSingleSelect()` or [methodname]`asMultiSelect()`, depending on the currently defined selection mode. Both methods return interfaces that implement the [interfacename]`HasValue` interface for use with `Binder`. | ||
|
|
||
|
|
||
| [role="since:com.vaadin:[email protected]"] | ||
| === Conditional Selection | ||
|
|
||
| Grid allows you to configure a predicate to control which rows users may select or deselect. The predicate receives an item and must return `true` to allow selection -- `false` to prevent it. This doesn't, however, prohibit programmatic selection changes. | ||
|
|
||
| [.example] | ||
| -- | ||
|
|
||
| [source,typescript] | ||
| ---- | ||
| <source-info group="Lit"></source-info> | ||
| // Example predicate function that only allows selecting orders that are not complete | ||
| // Consider storing the function in a class property to avoid changing the property on each render | ||
| const isItemSelectable = (order: Order) => order.status !== 'complete'; | ||
| <vaadin-grid .isItemSelectable=${isItemSelectable}> | ||
| ... | ||
| </vaadin-grid> | ||
| ---- | ||
| [source,java] | ||
| ---- | ||
| <source-info group="Flow"></source-info> | ||
| Grid<Order> grid = new Grid<>(); | ||
| // Example predicate that only allows selecting orders that are not complete | ||
| grid.setItemSelectableProvider(order -> order.getStatus() != Order.State.COMPLETE); | ||
| ---- | ||
| [source,tsx] | ||
| ---- | ||
| <source-info group="React"></source-info> | ||
| // Example predicate function that only allows selecting orders that are not complete | ||
| // Consider memoizing the function with useCallback to avoid changing the prop on each render | ||
| const isItemSelectable = (order: Order) => order.status !== 'complete'; | ||
| <Grid isItemSelectable={isItemSelectable}> | ||
| ... | ||
| </Grid> | ||
| ---- | ||
|
|
||
| -- | ||
|
|
||
| [NOTE] | ||
| In multi-select mode, the _Select All_ checkbox is hidden when using conditional selection. This is because determining the state of the checkbox would require checking all items whenever the selection changes. That could be a performance issue with large data sets or when using lazy data providers. | ||
|
|
||
|
|
||
| == Sorting | ||
|
|
||
| Any column can be used for sorting the data displayed. Enable sorting to allow the user to sort items alphabetically, numerically, by date, or by some other method. | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,151 @@ | ||
| --- | ||
| title: Selection | ||
| order: 40 | ||
| --- | ||
|
|
||
|
|
||
| = Selection | ||
|
|
||
| Grid supports single and multi-select modes. Neither is enabled by default. | ||
|
|
||
|
|
||
| == Single-Selection Mode | ||
|
|
||
| In single-selection mode, the user can select and deselect rows by clicking anywhere on the row. | ||
|
|
||
| [.example] | ||
| -- | ||
|
|
||
| ifdef::lit[] | ||
| [source,typescript] | ||
| ---- | ||
| include::{root}/frontend/demo/component/grid/grid-single-selection-mode.ts[render,tags=snippet,indent=0,group=Lit] | ||
| ---- | ||
| endif::[] | ||
|
|
||
| ifdef::flow[] | ||
| [source,java] | ||
| ---- | ||
| include::{root}/src/main/java/com/vaadin/demo/component/grid/GridSingleSelectionMode.java[render,tags=snippet,indent=0,group=Flow] | ||
| ---- | ||
| endif::[] | ||
|
|
||
| ifdef::react[] | ||
| [source,tsx] | ||
| ---- | ||
| include::{root}/frontend/demo/component/grid/react/grid-single-selection-mode.tsx[render,tags=snippet,indent=0,group=React] | ||
| ---- | ||
| endif::[] | ||
| -- | ||
|
|
||
|
|
||
| == Multi-Select Mode | ||
|
|
||
| In multi-select mode, the user can use a checkbox column to select and deselect more than one row -- not necessarily contiguous rows. Or the user can select all rows by clicking on the checkbox in the header row -- and then un-check the ones they don't want to be selected, rather than check many, individually. | ||
|
|
||
| [.example] | ||
| -- | ||
|
|
||
| ifdef::lit[] | ||
| [source,typescript] | ||
| ---- | ||
| include::{root}/frontend/demo/component/grid/grid-multi-select-mode.ts[render,tags=snippet,indent=0,group=Lit] | ||
| ---- | ||
| endif::[] | ||
|
|
||
| ifdef::flow[] | ||
| [source,java] | ||
| ---- | ||
| include::{root}/src/main/java/com/vaadin/demo/component/grid/GridMultiSelectionMode.java[render,tags=snippet,indent=0,group=Flow] | ||
| ---- | ||
| endif::[] | ||
|
|
||
| ifdef::react[] | ||
| [source,tsx] | ||
| ---- | ||
| include::{root}/frontend/demo/component/grid/react/grid-multi-select-mode.tsx[render,tags=snippet,indent=0,group=React] | ||
| ---- | ||
| endif::[] | ||
| -- | ||
|
|
||
| In addition to selecting rows individually, a range of rows can be selected by dragging from one selection checkbox to another, if enabled: | ||
|
|
||
| [.example] | ||
| -- | ||
|
|
||
| [source,typescript] | ||
| ---- | ||
| <source-info group="Lit"></source-info> | ||
| <vaadin-grid .items="${this.items}"> | ||
| <vaadin-grid-selection-column drag-select></vaadin-grid-selection-column> | ||
| ... | ||
| </vaadin-grid> | ||
| ---- | ||
| [source,java] | ||
| ---- | ||
| <source-info group="Flow"></source-info> | ||
| Grid<Person> g = new Grid<>(); | ||
| g.setSelectionMode(SelectionMode.MULTI); | ||
| GridMultiSelectionModel<Person> selectionModel = (GridMultiSelectionModel<Person>)g.getSelectionModel(); | ||
| selectionModel.setDragSelect(true); | ||
| ---- | ||
| [source,tsx] | ||
| ---- | ||
| <source-info group="React"></source-info> | ||
| <Grid items={items}> | ||
| <GridSelectionColumn dragSelect /> | ||
| ... | ||
| </Grid> | ||
| ---- | ||
|
|
||
| -- | ||
|
|
||
| == Selection Modes in Flow | ||
|
|
||
| Each selection mode is represented by a [classname]`GridSelectionModel`, accessible through the [methodname]`getSelectionModel()` method, which can be cast that to the specific selection model type, [classname]`SingleSelectionModel` or [classname]`MultiSelectionModel`. These interfaces provide selection mode specific APIs for configuration and selection events. | ||
|
|
||
| To use Grid with [classname]`Binder` in Flow, you can use [methodname]`asSingleSelect()` or [methodname]`asMultiSelect()`, depending on the currently defined selection mode. Both methods return interfaces that implement the [interfacename]`HasValue` interface for use with `Binder`. | ||
|
|
||
|
|
||
| [role="since:com.vaadin:[email protected]"] | ||
| == Conditional Selection | ||
|
|
||
| Grid allows you to configure a predicate to control which rows users may select or deselect. The predicate receives an item and must return `true` to allow selection -- `false` to prevent it. This doesn't, however, prohibit programmatic selection changes. | ||
|
|
||
| [.example] | ||
| -- | ||
|
|
||
| [source,typescript] | ||
| ---- | ||
| <source-info group="Lit"></source-info> | ||
| // Example predicate function that only allows selecting orders that are not complete | ||
| // Consider storing the function in a class property to avoid changing the property on each render | ||
| const isItemSelectable = (order: Order) => order.status !== 'complete'; | ||
| <vaadin-grid .isItemSelectable=${isItemSelectable}> | ||
| ... | ||
| </vaadin-grid> | ||
| ---- | ||
| [source,java] | ||
| ---- | ||
| <source-info group="Flow"></source-info> | ||
| Grid<Order> grid = new Grid<>(); | ||
| // Example predicate that only allows selecting orders that are not complete | ||
| grid.setItemSelectableProvider(order -> order.getStatus() != Order.State.COMPLETE); | ||
| ---- | ||
| [source,tsx] | ||
| ---- | ||
| <source-info group="React"></source-info> | ||
| // Example predicate function that only allows selecting orders that are not complete | ||
| // Consider memoizing the function with useCallback to avoid changing the prop on each render | ||
| const isItemSelectable = (order: Order) => order.status !== 'complete'; | ||
| <Grid isItemSelectable={isItemSelectable}> | ||
| ... | ||
| </Grid> | ||
| ---- | ||
|
|
||
| -- | ||
|
|
||
| [NOTE] | ||
| In multi-select mode, the _Select All_ checkbox is hidden when using conditional selection. This is because determining the state of the checkbox would require checking all items whenever the selection changes. That could be a performance issue with large data sets or when using lazy data providers. |