Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

refactor: move Selection section to separate page #4024

Merged
merged 4 commits into from
Dec 20, 2024
Merged

refactor: move Selection section to separate page #4024

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b7d477c
refactor: move Selection section to separate page
vursen Dec 19, 2024
6881ab2
raise headings level
vursen Dec 19, 2024
bca7125
Merge branch 'latest' into move-grid-selection-to-separate-page
vursen Dec 20, 2024
b029033
Merge branch 'latest' into move-grid-selection-to-separate-page
vursen Dec 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
148 changes: 1 addition & 147 deletions articles/components/grid/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)>>

Expand Down Expand Up @@ -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.
Expand Down
151 changes: 151 additions & 0 deletions articles/components/grid/selection.adoc
View file
Open in desktop
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.
Loading