Skip to content

Commit 7b19232

Browse files
vursenvursen
committed
improve examples
1 parent 354bf8f commit 7b19232

File tree

2 files changed

+146
-22
lines changed

2 files changed

+146
-22
lines changed

‎articles/components/grid/data-binding.adoc‎

Lines changed: 144 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -13,43 +13,163 @@ Grid supports connecting to various types of data sources through data providers
1313

1414
== Binding Items via `setItems`
1515

16-
The `setItems` method in Grid is a convenience API that allows you to bind and display data from in-memory collections and simple lazy-loaded data sources without explicitly creating a data provider. This method offers several overloads for different use cases, and returns either a `GridListDataView` or `GridLazyDataView` instance, which you can use to add filtering, sorting, and other configurations to the resulting list of displayed items.
16+
The simplest way to bind data to a Grid is by using the `setItems` convenience method. It lets you bind an in-memory collection or provide callbacks for lazy loading from a backend service without explicitly creating a data provider.
17+
18+
*Example:* Binding items from an in-memory collection.
19+
20+
[.example]
21+
--
1722

18-
.Example: Binding a collection of items
1923
[source,java]
24+
.PeopleView.java
2025
----
26+
Grid<Person> grid = new Grid<>(Person.class);
27+
28+
// Binding
2129
GridListDataView dataView = grid.setItems(
22-
new Person("George Washington", 1732),
23-
new Person("John Adams", 1735),
24-
new Person("Thomas Jefferson", 1743),
25-
new Person("James Madison", 1751)
30+
new Person("Michael Chen"),
31+
new Person("Sarah Johnson"),
32+
new Person("David Rodriguez"),
33+
new Person("Emma Wilson")
2634
);
35+
36+
// Filtering
37+
TextField searchInput = new TextField("Search", event -> {
38+
if (!event.getValue().isEmpty()) {
39+
// Set a filter to show only persons whose name contains the search term
40+
dataView.setFilter(person ->
41+
person.name().toLowerCase().contains(event.getValue().toLowerCase()));
42+
} else {
43+
// Clear the filter if the search term is empty
44+
dataView.removeFilters();
45+
}
46+
});
47+
48+
// Sorting
49+
Select<String> sortBySelect = new Select<>("Sort by", event -> {
50+
switch (event.getValue()) {
51+
case "Name (A-Z)" ->
52+
// Set sort order to ascending by name
53+
dataView.setSortOrder(Person::name, SortDirection.ASCENDING);
54+
case "Name (Z-A)" ->
55+
// Set sort order to descending by name
56+
dataView.setSortOrder(Person::name, SortDirection.DESCENDING);
57+
default ->
58+
// Clear sorting
59+
dataView.removeSorting();
60+
}
61+
});
62+
sortBySelect.setItems("", "Name (A-Z)", "Name (Z-A)");
2763
----
2864

29-
.Example: Binding items from a data service with lazy loading
3065
[source,java]
66+
.Person.java
67+
----
68+
public record Person(String name) {
69+
}
3170
----
32-
GridLazyDataView dataView = grid.setItems(
33-
// Callback for fetching items, expected to return a stream of items
34-
query -> personService.fetch(query.getOffset(), query.getLimit()),
35-
// Callback for counting items, expected to return a number of items
36-
query -> personService.count()
71+
72+
--
73+
74+
*Example:* Binding items from a data service via callbacks.
75+
76+
[.example]
77+
--
78+
79+
[source,java]
80+
.PeopleView.java
81+
----
82+
Grid<Person> grid = new Grid<>(Person.class);
83+
84+
// Filtering
85+
TextField searchInput = new TextField("Search", event -> {
86+
grid.getLazyDataView().refreshAll();
87+
});
88+
89+
// Sorting
90+
Select<String> sortBySelect = new Select<>("Sort by", event -> {
91+
grid.getLazyDataView().refreshAll();
92+
});
93+
sortBySelect.setItems("", "Name (A-Z)", "Name (Z-A)");
94+
95+
// Binding
96+
grid.setItems(
97+
(query) ->
98+
PersonService.fetch(
99+
searchInput.getValue(),
100+
sortBySelect.getValue(),
101+
query.getOffset(),
102+
query.getLimit()),
103+
(query) ->
104+
PersonService.count(searchInput.getValue())
37105
);
38106
----
39107

40-
.Example: Filtering and sorting the resulting data view
41108
[source,java]
109+
.PersonService.java
42110
----
43-
dataView
44-
.addFilter(person -> person.getAge() >= 18)
45-
.setSortOrder(Comparator.comparing(Person::getName));
111+
public class PersonService {
112+
private static final List<Person> PEOPLE = Arrays.asList(
113+
new Person("Michael Chen"),
114+
new Person("Sarah Johnson"),
115+
new Person("David Rodriguez"),
116+
new Person("Emma Wilson");
117+
118+
public static Stream<Person> fetch(
119+
String searchTerm, String sortOrder, int offset, int limit) {
120+
return PEOPLE.stream()
121+
.filter(person -> {
122+
if (searchTerm == null || searchTerm.isEmpty()) {
123+
return true;
124+
}
125+
126+
return person.name().toLowerCase().contains(searchTerm.toLowerCase());
127+
})
128+
.sorted((person0, person1) -> {
129+
if (sortOrder == null) {
130+
return 0;
131+
}
132+
return switch (sortOrder) {
133+
case "Name (A-Z)" ->
134+
Comparator.comparing(Person::name).compare(person0, person1);
135+
case "Name (Z-A)" ->
136+
Comparator.comparing(Person::name).reversed().compare(person0, person1);
137+
default ->
138+
0;
139+
};
140+
})
141+
.skip(offset)
142+
.limit(limit);
143+
}
144+
145+
public static int count(String searchTerm) {
146+
return (int) PEOPLE.stream()
147+
.filter(person -> {
148+
if (searchTerm == null || searchTerm.isEmpty()) {
149+
return true;
150+
}
151+
152+
return person.name().toLowerCase().contains(searchTerm.toLowerCase());
153+
})
154+
.count();
155+
}
156+
}
46157
----
47158

48-
For more documentation and examples, see the <<{articles}/flow/binding-data/data-provider#,Binding Items To Components>> article.
159+
[source,java]
160+
.Person.java
161+
----
162+
public record Person(String name) {
163+
}
164+
----
165+
166+
--
167+
168+
More documentation and examples for using the `setItems` method are available in the <<{articles}/flow/binding-data/data-provider#,Binding Items To Components>> article.
49169

50170
== Custom Data Providers
51171

52-
Alternatively, you can provide a custom data provider via the `setDataProvider(DataProvider<T, ?>)` method, passing your own class that implements the [interfacename]`DataProvider` interface.
172+
Alternatively, you can supply a custom data provider via the `setDataProvider(DataProvider<T, ?>)` method, passing your own class that implements the [interfacename]`DataProvider` interface:
53173

54174
[source,java]
55175
----
@@ -83,7 +203,7 @@ public class CustomDataProvider extends AbstractDataProvider<T, F> {
83203

84204
The `Query<T, F>` parameter in the `size` and `fetch` methods provides information about the requested data such as pagination details (offset and limit), sorting orders, and an optional filter object of type `F`.
85205

86-
Below is a practical example of a custom data provider that extends the `AbstractDataProvider` class and uses a fake database to return `Person` records. It supports filtering with a `PersonFilter` object and sorting using a list of `QuerySortOrder` objects from the Grid. The example also includes a simple view that uses the data provider with a Grid and filter components:
206+
Below is a practical example of a custom data provider that extends the `AbstractDataProvider` class and uses a fake database to return `Person` records. It supports filtering with a `PersonFilter` object and sorting using `QuerySortOrder` objects from the Grid. The example also includes a simple view that uses the data provider with a Grid and filter components:
87207

88208
[.example]
89209
--
@@ -99,7 +219,6 @@ public class PersonDataProvider extends AbstractDataProvider<Person, PersonFilte
99219
new Person("Sarah Johnson", "Engineering"),
100220
new Person("David Rodriguez", "Marketing"),
101221
new Person("Emma Wilson", "HR"),
102-
new Person("James Patterson", "Marketing"));
103222
104223
@Override
105224
public boolean isInMemory() {
@@ -203,10 +322,13 @@ public class PeopleView extends VerticalLayout {
203322
public PeopleView() {
204323
Grid<Person> grid = new Grid<>(Person.class);
205324
206-
// Enable sorting for the columns
325+
// Enable sorting for the columns. This will send sorting information
326+
// to the data provider as List<QuerySortOrder> when the user sorts
327+
// the columns in the Grid.
207328
grid.setSortableColumns("name", "department");
208329
209-
// Create a data provider instance with a configurable filter.
330+
// Create a data provider instance with a configurable filter,
331+
// as it doesn't provide filtering capabilities by default.
210332
// The returned wrapper allows setting the filter dynamically
211333
// using the ConfigurableFilterDataProvider#setFilter() method
212334
dataProvider = new PersonDataProvider().withConfigurableFilter();

‎articles/components/grid/index.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -325,6 +325,8 @@ endif::[]
325325

326326
--
327327

328+
See the <<../grid/data-binding#custom-data-providers,Data Binding>> page for more information about creating data providers for Grid.
329+
328330
=== Lazy Column Rendering
329331

330332
Grids containing a large number of columns can sometimes exhibit performance issues. If many of the columns are typically outside the visible viewport, rendering performance can be optimized by using "lazy column rendering" mode.

0 commit comments

Comments
 (0)