1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
|
---
title: Grid
order: 24
layout: page
---
[[components.grid]]
= Grid
ifdef::web[]
[.sampler]
image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/grids-and-trees/grid"]
endif::web[]
[[components.grid.overview]]
== Overview
[classname]#Grid# is for displaying and editing tabular data laid out in rows
and columns. At the top, a __header__ can be shown, and a __footer__ at the
bottom. In addition to plain text, the header and footer can contain HTML and
components. Having components in the header allows implementing filtering
easily. The grid data can be sorted by clicking on a column header;
shift-clicking a column header enables secondary sorting criteria.
[[figure.components.grid.features]]
.A [classname]#Grid#
image::img/grid-features.png[width=70%, scaledwidth=100%]
The data area can be scrolled both vertically and horizontally. The leftmost
columns can be frozen, so that they are never scrolled out of the view. The data
is loaded lazily from the server, so that only the visible data is loaded. The
smart lazy loading functionality gives excellent user experience even with low
bandwidth, such as mobile devices.
The grid data can be edited with a row-based editor after double-clicking a row.
The fields are set explicitly, and bound to data.
Grid is fully themeable with CSS and style names can be set for all grid
elements. For data rows and cells, the styles can be generated with a row or
cell style generator.
[[components.grid.data]]
== Binding to Data
[classname]#Grid# is normally used by binding it to a data provider,
described in
<<dummy/../../../framework/datamodel/datamodel-providers.asciidoc#datamodel.dataproviders,"Showing Many Items in a Listing">>.
By default, it is bound to List of items. You can set the items with the
[methodname]#setItems()# method.
For example, if you have a list of beans, you show them in a [classname]#Grid# as follows
[source, java]
----
// Have some data
List<Person> people = Arrays.asList(
new Person("Nicolaus Copernicus", 1543),
new Person("Galileo Galilei", 1564),
new Person("Johannes Kepler", 1571));
// Create a grid bound to the list
Grid<Person> grid = new Grid<>();
grid.setItems(people);
grid.addColumn(Person::getName).setCaption("Name");
grid.addColumn(Person::getBirthYear).setCaption("Year of birth");
layout.addComponent(grid);
----
[[components.grid.selection]]
== Handling Selection Changes
Selection in [classname]#Grid# is handled a bit differently from other selection
components, as it is not a [classname]#HasValue#. Grid supports
single, multiple, or no-selection, each defined by a specific selection model. Each
selection model has a specific API depending on the type of the selection.
For basic usage, switching between the built-in selection models is possible by using the
[method]#setSelectionMode(SelectionMode)#. Possible options are [literal]#++SINGLE++# (default),
[literal]#++MULTI++#, or [literal]#++NONE++#.
Listening to selection changes in any selection model is possible with a [classname]#SelectionListener#,
which provides a generic [classname]#SelectionEvent# which for getting the selected value or values.
Note that the listener is actually attached to the selection model and not the grid,
and will stop getting any events if the selection mode is changed.
[source, java]
----
Grid<Person> grid = new Grid<>();
// switch to multiselect mode
grid.setSelectionMode(SelectionMode.MULTI);
grid.addSelectionListener(event -> {
Set<Person> selected = event.getAllSelectedItems();
Notification.show(selected.size() + " items selected");
});
----
Programmatically selecting the value is possible via [methodname]#select(T)#.
In multiselect mode, this will add the given item to the selection.
[source, java]
----
// in single-select, only one item is selected
grid.select(defaultPerson);
// switch to multi select, clears selection
grid.setSelectionMode(SelectionMode.MULTI);
// Select items 2-4
people.subList(2,3).forEach(grid::select);
----
The current selection can be obtained from the [classname]#Grid# by
[methodname]#getSelectedItems()#, and the returned [classname]#Set# contains either
only one item (in single-selection mode) or several items (in multi-selection mode).
[WARNING]
====
If you change selection mode for a grid, it will clear the selection
and fire a selection event. To keep the previous selection you must
reset the selection afterwards using the [methodname]#select()# method.
====
[WARNING]
====
If you change the grid's items with [methodname]#setItems()# or the used
[classname]#DataProvider#, it will clear the selection and fire a selection event.
To keep the previous selection you must reset the selection afterwards
using the [methodname]#select()# method.
====
[[components.grid.selection.mode]]
=== Selection Models
For more control over the selection, you can access the used selection model with
[methodname]#getSelectionModel()#. The return type is [classname]#GridSelectionModel#
which has generic selection model API, but you can cast that to the specific selection model type,
typically either [classname]#SingleSelectionModel# or [classname]#MultiSelectionModel#.
The selection model is also returned by the [methodname]#setSelectionMode(SelectionMode)# method.
[source, java]
----
// the default selection model
SingleSelectionModel<Person> defaultModel =
(SingleSelectionModel<Person>) grid.getSelectionModel();
// Use multi-selection mode
MultiSelectionModel<Person> selectionModel =
(MultiSelectionModel<Person>) grid.setSelectionMode(SelectionMode.MULTI);
----
==== Single Selection Model
By obtaining a reference to the [classname]#SingleSelectionModel#,
you can access more fine grained API for the single-select case.
The [methodname]#addSingleSelect(SingleSelectionListener)# method provides access to
[classname]#SingleSelectionEvent#, which has some extra API for more convenience.
In single-select mode, it is possible to control whether the empty (null) selection is allowed.
By default it is enabled, but can be disabled with [methodname]#setDeselectAllowed()#.
[source, java]
----
// preselect value
grid.select(defaultItem);
SingleSelectionModel<Person> singleSelect =
(SingleSelectionModel<Person>) grid.getSelectionModel();
// disallow empty selection
singleSelect.setDeselectAllowed(false);
----
[[components.grid.selection.multi]]
=== Multi-Selection Model
In the multi-selection mode, a user can select multiple items by clicking on
the checkboxes in the leftmost column, or by using the kbd:[Space] to select/deselect the currently focused row.
Space bar is the default key for toggling the selection, but it can be customized.
[[figure.components.grid.selection.multi]]
.Multiple Selection in [classname]#Grid#
image::img/grid-selection-multi.png[width=50%, scaledwidth=75%]
By obtaining a reference to the [classname]#MultiSelectionModel#,
you can access more fine grained API for the multi-select case.
The [classname]#MultiSelectionModel# provides [methodname]#addMultiSelectionListener(MultiSelectionListener)#
access to [classname]#MultiSelectionEvent#, which allows to easily access differences in the selection change.
[source, java]
----
// Grid in multi-selection mode
Grid<Person> grid = Grid<>()
grid.setItems(people);
MultiSelectionModel<Person> selectionModel
= (MultiSelectionModel<Person>) grid.setSelectionMode(SelectionMode.MULTI);
selectionModel.selectAll();
selectionModel.addMultiSelectionListener(event -> {
Notification.show(selection.getAddedSelection().size()
+ " items added, "
+ selection.getRemovedSelection().size()
+ " removed.");
// Allow deleting only if there's any selected
deleteSelected.setEnabled(
event.getNewSelection().size() > 0);
});
----
[[components.grid.selection.clicks]]
=== Focus and Clicks
In addition to selecting rows, you can focus individual cells. The focus can be
moved with arrow keys and, if editing is enabled, pressing kbd:[Enter] opens the
editor. Normally, pressing kbd:[Tab] or kbd:[Shift+Tab] moves the focus to another component,
as usual.
When editing or in unbuffered mode, kbd:[Tab] or kbd:[Shift+Tab] moves the focus to the next or
previous cell. The focus moves from the last cell of a row forward to the
beginning of the next row, and likewise, from the first cell backward to the
end of the previous row. Note that you can extend [classname]#DefaultEditorEventHandler#
to change this behavior.
With the mouse, you can focus a cell by clicking on it. The clicks can be handled
with an [interfacename]#ItemClickListener#. The [classname]#ItemClickEvent#
object contains various information, most importantly the ID of the clicked row
and column.
[source, java]
----
grid.addCellClickListener(event ->
Notification.show("Value: " + event.getItem()));
----
The clicked grid cell is also automatically focused.
The focus indication is themed so that the focused cell has a visible focus
indicator style by default, while the row does not. You can enable row focus, as
well as disable cell focus, in a custom theme. See <<components.grid.css>>.
[[components.grid.columns]]
== Configuring Columns
The [methodname]#addColumn()# method can be used to add columns to [classname]#Grid#.
Column configuration is defined in [classname]#Grid.Column# objects, which are returned by `addColumn` and can also be obtained from the grid with [methodname]#getColumns()#.
The setter methods in [classname]#Column# have _fluent API_, so you can easily chain the configuration calls for columns if you want to.
[source, java]
----
grid.addColumn(Person::getBirthDate, new DateRenderer())
.setCaption("Birth Date")
.setWidth("100px")
.setResizable(false);
----
In the following, we describe the basic column configuration.
[[components.grid.columns.automatic]]
=== Automatically Adding Columns
You can configure `Grid` to automatically add columns based on the properties in a bean.
To do this, you need to pass the `Class` of the bean type to the constructor when creating a grid.
You can then further configure the columns based on the bean property name.
[source, java]
----
Grid<Person> grid = new Grid<>(Person.class);
grid.getColumn("birthDate").setWidth("100px");
grid.setItems(people);
----
[[components.grid.columns.order]]
=== Column Order
You can set the order of columns with [methodname]#setColumnOrder()# for the
grid. Columns that are not given for the method are placed after the specified
columns in their natural order.
[source, java]
----
grid.setColumnOrder(firstnameColumn, lastnameColumn,
bornColumn, birthplaceColumn,
diedColumn);
----
Note that the method can not be used to hide columns. You can hide columns with
the [methodname]#removeColumn()#, as described later.
[[components.grid.columns.removing]]
=== Hiding and Removing Columns
Columns can be hidden by calling [methodname]#setHidden()# in [classname]#Column#.
Furthermore, you can set the columns user hidable using method
[methodname]#setHidable()#.
Columns can be removed with [methodname]#removeColumn()# and
[methodname]#removeAllColumns()#. To restore a previously removed column,
you can call [methodname]#addColumn()#.
[[components.grid.columns.captions]]
=== Column Captions
Column captions are displayed in the grid header. You can set the header caption
explicitly through the column object with [methodname]#setCaption()#.
[source, java]
----
Column<Date> bornColumn = grid.addColumn(Person::getBirthDate);
bornColumn.setCaption("Born date");
----
This is equivalent to setting it with [methodname]#setText()# for the header
cell; the [classname]#HeaderCell# also allows setting the caption in HTML or as
a component, as well as styling it, as described later in
<<components.grid.headerfooter>>.
[[components.grid.columns.width]]
=== Column Widths
Columns have by default undefined width, which causes automatic sizing based on
the widths of the displayed data. You can set column widths explicitly by pixel
value with [methodname]#setWidth()#, or relatively using expand ratios with
[methodname]#setExpandRatio()#.
When using expand ratios, the columns with a non-zero expand ratio use the extra
space remaining from other columns, in proportion to the defined ratios.
You can specify minimum and maximum widths for the expanding columns with
[methodname]#setMinimumWidth()# and [methodname]#setMaximumWidth()#,
respectively.
The user can resize columns by dragging their separators with the mouse. When resized manually,
all the columns widths are set to explicit pixel values, even if they had
relative values before.
[[components.grid.columns.frozen]]
=== Frozen Columns
You can set the number of columns to be frozen with
[methodname]#setFrozenColumnCount()#, so that they are not scrolled off when
scrolling horizontally.
[source, java]
----
grid.setFrozenColumnCount(2);
----
Setting the count to [parameter]#0# disables frozen data columns; setting it to
[parameter]#-1# also disables the selection column in multi-selection mode.
[[components.grid.generatedcolumns]]
== Generating Columns
Columns with values computed from other columns can be simply added by using
lambdas:
[source, java]
----
// Add generated full name column
Column<String> fullNameColumn = grid.addColumn(person ->
person.getFirstName() + " " + person.getLastName());
fullNameColumn.setCaption("Full name");
----
[[components.grid.renderer]]
== Column Renderers
A __renderer__ is a feature that draws the client-side representation of a data
value. This allows having images, HTML, and buttons in grid cells.
[[figure.components.grid.renderer]]
.Column renderers: image, date, HTML, and button
image::img/grid-renderers.png[width=75%, scaledwidth=100%]
Renderers implement the [interfacename]#Renderer# interface.
Renderers require a specific data type for the column.
You set the column renderer in the [classname]#Grid.Column# object as follows:
[source, java]
----
// the type of birthYear is a number
Column<Person, Integer> bornColumn = grid.addColumn(Person::getBirthYear,
new NumberRenderer("born in %d AD"));
----
Changing the renderer during runtime is also possible, but for type safety
you should store the column reference with data types for doing this.
When you change the renderer, the content of Grid is refreshed.
[source, java]
----
Column<Person, Integer> ageColumn = grid.addColumn(Person::getBirthYear);
// The default renderer is TextRenderer
addComponent(new Button("Change renderer",
clickEvent -> ageColumn.setRenderer(new NumberRenderer())
));
----
The following renderers are available, as defined in the server-side
[package]#com.vaadin.ui.renderers# package:
[classname]#TextRenderer#:: The default renderer, displays plain text as is. Any HTML markup is quoted.
[classname]#ButtonRenderer#:: Renders the data value as the caption of a button. A [interfacename]#RendererClickListener# can be given to handle the button clicks.
+
Typically, a button renderer is used to display buttons for operating on a data
item, such as edit, view, delete, etc. It is not meaningful to store the button
captions in the data source, rather you want to generate them, and they are
usually all identical.
+
[source, java]
----
List<Person> people = new ArrayList<>();
people.add(new Person("Nicolaus Copernicus", 1473));
people.add(new Person("Galileo Galilei", 1564));
people.add(new Person("Johannes Kepler", 1571));
// Create a grid
Grid<Person> grid = new Grid<>(people);
// Render a button that deletes the data row (item)
grid.addColumn(person -> "Delete",
new ButtonRenderer(clickEvent -> {
people.remove(clickEvent.getValue());
grid.setItems(people);
}));
----
[classname]#ImageRenderer#:: Renders the cell as an image.
The column type must be a [interfacename]#Resource#, as described in
<<dummy/../../../framework/application/application-resources#application.resources,"Images and Other Resources">>; only [classname]#ThemeResource# and
[classname]#ExternalResource# are currently supported for images in
[classname]#Grid#.
+
[source, java]
----
Column<Person, ThemeResource> imageColumn = grid.addColumn(
p -> new ThemeResource("img/"+p.getLastname()+".jpg"),
new ImageRenderer());
----
[classname]#DateRenderer#:: Formats a column with a [classname]#Date# type using string formatter. The
format string is same as for [methodname]#String.format()# in Java API. The date
is passed in the parameter index 1, which can be omitted if there is only one
format specifier, such as "[literal]#++%tF++#".
+
[source, java]
----
Column<Person, Date> bornColumn = grid.addColumn(Person::getBirthDate,
new DateRenderer("%1$tB %1$te, %1$tY",
Locale.ENGLISH));
----
+
Optionally, a locale can be given. Otherwise, the default locale (in the
component tree) is used.
[classname]#HTMLRenderer#:: Renders the cell as HTML.
This allows formatting the cell content, as well as using HTML features such as hyperlinks.
+
Set the renderer in the [classname]#Grid.Column# object:
+
[source, java]
----
Column<Person, String> htmlColumn grid.addColumn(person ->
"<a href='" + person.getDetailsUrl() + "' target='_top'>info</a>",
new HtmlRenderer());
----
[classname]#NumberRenderer#:: Formats column values with a numeric type extending [classname]#Number#:
[classname]#Integer#, [classname]#Double#, etc. The format can be specified
either by the subclasses of [classname]#java.text.NumberFormat#, namely
[classname]#DecimalFormat# and [classname]#ChoiceFormat#, or by
[methodname]#String.format()#.
+
For example:
+
[source, java]
----
// Use decimal format
Column<Integer> birthYear = grid.addColumn(Person::getBirthYear,
new NumberRenderer(new DecimalFormat("in #### AD")));
----
[classname]#ProgressBarRenderer#:: Renders a progress bar in a column with a [classname]#Double# type. The value
must be between 0.0 and 1.0.
IMPORTANT: The following renderers are to be released in version 8.1 and are currently only available in link:https://vaadin.com/releases[pre-release versions] of the framework, starting from 8.1.0.alpha3.
[classname]#LocalDateRenderer#::
Formats a column with the [classname]#LocalDate# type.
The renderer can be constructed with a [classname]#DateTimeFormatter#, or with a custom pattern string.
The locale is either given explicitly with the pattern, resolved from the given [classname]#DateTimeFormatter# or from the grid the renderer is attached to, if neither of the previous are given.
For the pattern string syntax, refer to the following documentation: link:https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#patterns[docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#patterns].
+
[source, java]
----
DateTimeFormatter formatter = DateTimeFormatter
.ofLocalizedDate(FormatStyle.LONG)
.withLocale(Locale.ENGLISH);
Column<Person, LocalDate> bornColumn =
grid.addColumn(
Person::getBirthDate,
new LocalDateRenderer(formatter));
// Alternatively, with a custom pattern:
Column<Person, LocalDate> bornColumn =
grid.addColumn(
Person::getBirthDate,
new LocalDateRenderer("yyyy MM dd"));
----
[classname]#LocalDateTimeRenderer#::
Otherwise the same as [classname]#LocalDateRenderer#, except for the [classname]#LocalDateTime# type.
+
[source, java]
----
DateTimeFormatter formatter = DateTimeFormatter
.ofLocalizedDate(FormatStyle.LONG, FormatStyle.SHORT)
.withLocale(Locale.ENGLISH);
Column<Person, LocalDateTime> bornColumn =
grid.addColumn(
Person::getBirthDateAndTime,
new LocalDateTimeRenderer(formatter));
// Alternatively, with a custom pattern:
Column<Person, LocalDateTime> bornColumn =
grid.addColumn(
Person::getBirthDateAndTime,
new LocalDateTimeRenderer("yyyy.MM.dd 'at' hh:mm"));
----
[classname]#ComponentRenderer#:: Renders a Vaadin [classname]#Component# in a column. Since components
are quite complex, the [classname]#ComponentRenderer# comes with possible performance issues.
To use it efficiently you should use as few nested components as possible. If the components used are
of a different size than the default row height, [methodname]#Grid.setRowHeight()# can be used to adjust
the height of all rows in the Grid.
+
Use [classname]#Button# in [classname]#Grid#:
+
----
grid.addColumn(person -> {
Button button = new Button("Click me!");
button.addClickListener(click ->
Notification.show("Clicked: " + person.toString()));
return button;
}, new ComponentRenderer());
// make sure the buttons fit in the cells of the Grid
grid.setRowHeight(40);
----
+
Components will occasionally be generated again during runtime. If you have a state in your
component and not in the data object, you need to handle storing it yourself. Below is a simple
example on how to achieve this.
+
Store a [classname]#TextField# with changed value.
+
----
Map<Person, TextField> textFields = new HashMap<>();
grid.addColumn(person -> {
// Check for existing text field
if (textFields.containsKey(person)) {
return textFields.get(person);
}
// Create a new one
TextField textField = new TextField();
textField.setValue(person.getLastname());
// Store the text field when user updates the value
textField.addValueChangeListener(change ->
textFields.put(person, textField));
return textField;
}, new ComponentRenderer());
----
[[components.grid.renderer.custom]]
=== Custom Renderers
Renderers are component extensions that require a client-side counterpart. See
<<dummy/../../../framework/clientsidewidgets/clientsidewidgets-grid#clientsidewidgets.grid.renderers,"Renderers">>
for information on implementing custom renderers.
[[components.grid.headerfooter]]
== Header and Footer
A grid by default has a header, which displays column names, and can have a
footer. Both can have multiple rows and neighbouring header row cells can be
joined to feature column groups.
[[components.grid.headerfooter.adding]]
=== Adding and Removing Header and Footer Rows
A new header row is added with [methodname]#prependHeaderRow()#, which adds it
at the top of the header, [methodname]#appendHeaderRow()#, which adds it at the
bottom of the header, or with [methodname]#addHeaderRowAt()#, which inserts it
at the specified 0-base index. All of the methods return a
[classname]#HeaderRow# object, which you can use to work on the header further.
[source, java]
----
// Group headers by joining the cells
HeaderRow groupingHeader = grid.prependHeaderRow();
...
// Create a header row to hold column filters
HeaderRow filterRow = grid.appendHeaderRow();
...
----
Similarly, you can add footer rows with [methodname]#appendFooterRow()#,
[methodname]#prependFooterRow()#, and [methodname]#addFooterRowAt()#.
[[components.grid.headerfooter.joining]]
=== Joining Header and Footer Cells
You can join two or more header or footer cells with the [methodname]#join()#
method. For header cells, the intention is usually to create column grouping,
while for footer cells, you typically calculate sums or averages.
[source, java]
----
// Group headers by joining the cells
HeaderRow groupingHeader = grid.prependHeaderRow();
HeaderCell namesCell = groupingHeader.join(
groupingHeader.getCell("firstname"),
groupingHeader.getCell("lastname")).setText("Person");
HeaderCell yearsCell = groupingHeader.join(
groupingHeader.getCell("born"),
groupingHeader.getCell("died"),
groupingHeader.getCell("lived")).setText("Dates of Life");
----
[[components.grid.headerfooter.content]]
=== Text and HTML Content
You can set the header caption with [methodname]#setText()#, in which case any
HTML formatting characters are quoted to ensure security.
[source, java]
----
HeaderRow mainHeader = grid.getDefaultHeaderRow();
mainHeader.getCell("firstname").setText("First Name");
mainHeader.getCell("lastname").setText("Last Name");
mainHeader.getCell("born").setText("Born In");
mainHeader.getCell("died").setText("Died In");
mainHeader.getCell("lived").setText("Lived For");
----
To use raw HTML in the captions, you can use [methodname]#setHtml()#.
[source, java]
----
namesCell.setHtml("<b>Names</b>");
yearsCell.setHtml("<b>Years</b>");
----
[[components.grid.headerfooter.components]]
=== Components in Header or Footer
You can set a component in a header or footer cell with
[methodname]#setComponent()#. Often, this feature is used to allow filtering.
////
// commented out until filtering is sorted for 8
[[components.grid.filtering]]
== Filtering
The ability to include components in the grid header can be used to create
filters for the grid data. Filtering is done in the container data source, so
the container must be of type that implements
[interfacename]#Container.Filterable#.
[[figure.components.grid.filtering]]
.Filtering Grid
image::img/grid-filtering.png[width=50%, scaledwidth=80%]
The filtering illustrated in <<figure.components.grid.filtering>> can be created
as follows:
[source, java]
----
// Have a list of persons
List<Person> people = getPeople();
// Create a grid bound to it
Grid<Person> grid = new Grid<>();
grid.setItems(people);
grid.setSelectionMode(SelectionMode.NONE);
grid.setWidth("500px");
grid.setHeight("300px");
// Create a header row to hold column filters
HeaderRow filterRow = grid.appendHeaderRow();
// Set up a filter for all columns
for (Column<?> col: grid.getColumns()) {
HeaderCell cell = filterRow.getCell(col);
// Have an input field to use for filter
TextField filterField = new TextField();
// Update filter When the filter input is changed
filterField.addValueChangeListener(event -> {
// Filter the list of items
List<String> filteredList =
// XXX shouldn't use Lists here since it's from Guava instead of the vanilla JRE. Revise when updating this code example for the new filtering API!
Lists.newArrayList(personList.filter(persons,
Predicates.containsPattern(event.getValue())));
// Apply filtered data
grid.setItems(filteredList);
});
cell.setComponent(filterField);
}
----
////
[[components.grid.sorting]]
== Sorting
A user can sort the data in a grid on a column by clicking the column header.
Clicking another time on the current sort column reverses the sort direction.
Clicking on other column headers while keeping the Shift key pressed adds a
secondary or more sort criteria.
[[figure.components.grid.sorting]]
.Sorting Grid on Multiple Columns
image::img/grid-sorting.png[width=50%, scaledwidth=75%]
Defining sort criteria programmatically can be done with the various
alternatives of the [methodname]#sort()# method. You can sort on a specific
column with [methodname]#sort(Column column)#, which defaults to ascending
sorting order, or [methodname]#sort(Column column, SortDirection
direction)#, which allows specifying the sort direction.
[source, java]
----
grid.sort(nameColumn, SortDirection.DESCENDING);
----
To sort by multiple columns, you need to use the fluid sort builder API
[classname]#GridSortOrderBuilder#, which allows you to easily construct sorting information to be passed to grid's [methodname]#setSortOrder()# method.
A sort builder is created with the static methods [methodname]#asc()# and [methodname]#desc()#,
and additional sorting information can by chained with [methodname]#thenAsc()# and [methodname]#thenDesc()#.
[source, java]
----
// Sort first by city (ascending) and then by name (descending)
grid.setSortOrder(GridSortOrder.asc(cityColumn).thenDesc(nameColumn))
----
[[components.grid.editing]]
== Editing Items Inside Grid
Grid supports line-based editing, where double-clicking a row opens the row
editor. In the editor, the input fields can be edited, as well as navigated with
kbd:[Tab] and kbd:[Shift+Tab] keys. If validation fails, an error is displayed and the user
can correct the inputs.
The [classname]#Editor# is accessible via [methodname]#getEditor()#, and to enable editing, you need to call [methodname]#setEnabled(true)# on it.
The editor is based on [classname]#Binder# which is used to bind the data to the editor.
See <<dummy/../../../framework/datamodel/datamodel-forms.asciidoc#datamodel.forms.beans,"Binding Beans to Forms">> for more information on setting up field components and validation by using [classname]#Binder#.
For each column that should be editable, a binding should be created in the editor binder and then the column is configured to use that binding.
For simple cases where no conversion or validation is needed, it is also possible to directly use `setEditorComponent` on a `Column` to only define the editor component and a setter that updates the row object when saving.
[source, java]
----
List<Todo> items = Arrays.asList(new Todo("Done task", true),
new Todo("Not done", false));
Grid<Todo> grid = new Grid<>();
TextField taskField = new TextField();
CheckBox doneField = new CheckBox();
Binder<Todo> binder = grid.getEditor().getBinder();
Binding<Todo, Boolean> doneBinding = binder.bind(
doneField, Todo::isDone, Todo::setDone);
Column<Todo, String> column = grid.addColumn(
todo -> String.valueOf(todo.isDone()));
column.setWidth(75);
column.setEditorBinding(doneBinding);
grid.addColumn(Todo::getTask).setEditorComponent(
taskField, Todo::setTask).setExpandRatio(1);
grid.getEditor().setEnabled(true);
----
[[components.grid.editing.buffered]]
=== Buffered / Unbuffered Mode
Grid supports two editor modes - buffered and unbuffered. The default mode is
buffered. The mode can be changed with [methodname]#setBuffered(false)#.
In the buffered mode, editor has two buttons visible: a [guibutton]#Save# button that commits
the modifications to the bean and closes the editor and a [guibutton]#Cancel# button
discards the changes and exits the editor.
Editor in buffered mode is illustrated in <<figure.components.grid.editing>>.
[[figure.components.grid.editing]]
.Editing a Grid Row
image::img/grid-editor-basic.png[width=50%, scaledwidth=75%]
In the unbuffered mode, the editor has no buttons and all changed data is committed directly
to the data provider. If another row is clicked, the editor for the current row is closed and
a row editor for the clicked row is opened.
[[components.grid.editing.captions]]
=== Customizing Editor Buttons
In the buffered mode, the editor has two buttons: [guibutton]#Save# and [guibutton]#Cancel#. You can
set their captions with [methodname]#setEditorSaveCaption()# and
[methodname]#setEditorCancelCaption()#, respectively.
In the following example, we demonstrate one way to translate the captions:
[source, java]
----
// Localize the editor button captions
grid.getEditor().setSaveCaption("Tallenna");
grid.getEditor().setCancelCaption("Peruuta"));
----
[[components.grid.editing.validation]]
=== Handling Validation Errors
The input fields are validated when the value is updated. The default
error handler displays error indicators in the invalid fields, as well as the
first error in the editor.
[[figure.components.grid.errors]]
.Editing a Grid Row
image::img/grid-editor-errors.png[width=50%, scaledwidth=75%]
You can modify the error message by implementing a custom
[interfacename]#EditorErrorGenerator# with for the [classname]#Editor#.
////
// Not supported in 8
[[components.grid.scrolling]]
== Programmatic Scrolling
You can scroll to first item with [methodname]#scrollToStart()#, to end with
[methodname]#scrollToEnd()#, or to a specific row with [methodname]#scrollTo()#.
////
== Drag and Drop of Rows
Please refer to the
<<dummy/../../../framework/advanced/advanced-dragndrop#advanced.dragndrop.grid,"Drag and Drop Rows in Grid">> documentation.
[[advanced.dragndrop.grid]]
[[components.grid.stylegeneration]]
== Generating Row or Cell Styles
You can style entire rows or individual cells with a
[interfacename]#StyleGenerator#, typically used through Java lambdas.
[[components.grid.stylegeneration.row]]
=== Generating Row Styles
You set a [interfacename]#StyleGenerator# to a grid with
[methodname]#setStyleGenerator()#. The [methodname]#getStyle()# method gets a
date item, and should return a style name or [parameter]#null# if
no style is generated.
For example, to add a style names to rows having certain values in one
property of an item, you can style them as follows:
[source, java]
----
grid.setStyleGenerator(person -> {
// Style based on alive status
person.isAlive() ? null : "dead";
});
----
You could then style the rows with CSS as follows:
[source, css]
----
.v-grid-row.dead {
color: gray;
}
----
[[components.grid.stylegeneration.cell]]
=== Generating Cell Styles
You set a [interfacename]#StyleGenerator# to a grid with
[methodname]#setStyleGenerator()#. The [methodname]#getStyle()# method gets
a [classname]#CellReference#, which contains various information about the cell
and a reference to the grid, and should return a style name or [parameter]#null#
if no style is generated.
For example, to add a style name to a specific column, you can match on
the column as follows:
[source, java]
----
// Static style based on column
bornColumn.setStyleGenerator(person -> "rightalign");
----
You could then style the cells with a CSS rule as follows:
[source, css]
----
.v-grid-cell.rightalign {
text-align: right;
}
----
[[components.grid.css]]
== Styling with CSS
[source, css]
----
.v-grid {
.v-grid-scroller, .v-grid-scroller-horizontal { }
.v-grid-tablewrapper {
.v-grid-header {
.v-grid-row {
.v-grid-cell, .frozen, .v-grid-cell-focused { }
}
}
.v-grid-body {
.v-grid-row,
.v-grid-row-stripe,
.v-grid-row-has-data {
.v-grid-cell, .frozen, .v-grid-cell-focused { }
}
}
.v-grid-footer {
.v-grid-row {
.v-grid-cell, .frozen, .v-grid-cell-focused { }
}
}
}
.v-grid-header-deco { }
.v-grid-footer-deco { }
.v-grid-horizontal-scrollbar-deco { }
.v-grid-editor {
.v-grid-editor-cells { }
.v-grid-editor-footer {
.v-grid-editor-message { }
.v-grid-editor-buttons {
.v-grid-editor-save { }
.v-grid-editor-cancel { }
}
}
}
}
----
A [classname]#Grid# has an overall [literal]#++v-grid++# style. The actual grid
has three parts: a header, a body, and a footer. The scrollbar is a custom
element with [literal]#++v-grid-scroller++# style. In addition, there are some
decoration elements.
Grid cells, whether thay are in the header, body, or footer, have a basic
[literal]#++v-grid-cell++# style. Cells in a frozen column additionally have a
[literal]#++frozen++# style. Rows have [literal]#++v-grid-row++# style, and
every other row has additionally a [literal]#++v-grid-row-stripe++# style.
The focused row has additionally [literal]#++v-grid-row-focused++# style and
focused cell [literal]#++v-grid-cell-focused++#. By default, cell focus is
visible, with the border stylable with [parameter]#$v-grid-cell-focused-border#
parameter in Sass. Row focus has no visible styling, but can be made visible
with the [parameter]#$v-grid-row-focused-background-color# parameter or with a
custom style rule.
In editing mode, a [literal]#++v-grid-editor++# overlay is placed on the row
under editing. In addition to the editor field cells, it has an error message
element, as well as the buttons.
((()))
|