Cell Widgets

Cell<C> is an interface, but the Javadoc warns against implementing it directly: it may change in small but breaking ways as the library is tuned for speed, so extend AbstractCell<C> instead. These are its methods in 2.13.1.

Cell.Context carries three facts about the instance that is being rendered: getIndex() (the row, as an absolute index), getColumn() and getKey() (the row’s key from the ProvidesKey); a fourth, getSubIndex(), is 0 unless the row value renders to more than one row element (see the table builders below). Nothing else about the row is passed: a cell receives the value of its column, not the row object.

The value of a cell can be null. The official guide warns that cell widgets can pass null for rows that have no data yet, for example when data arrives in the middle of the visible range, so every render starts with a null check.

Source: GWT Javadoc — Cell

All of these live in com.google.gwt.cell.client; every class name in the table exists in 2.13.1.

The cells that take input (EditTextCell, TextInputCell, CheckboxCell, SelectionCell, DatePickerCell) extend AbstractEditableCell, which adds view data: a map from the row key to what the user typed but has not saved. That is the second reason a ProvidesKey matters (see below): with the default key (the row object itself) a re-fetched row looks like a new row and the pending edit is lost. The pending value stays until the row’s underlying value changes (a successful commit) or until AbstractEditableCell.clearViewData(key) is called, which is what a failed save should do. An editable cell object shared by two columns or two widgets shares that pending state too, and the other widget shows it when it is next redrawn.

A cell tells the outside world about a user action through a ValueUpdater<C>: its single method update(C newValue) is called with the new value (the text typed, the box state, the selected option; for a button, the same value again as a "something happened" signal). A cell widget with no columns, such as CellList, takes the updater directly with setValueUpdater. A table column wraps it: Column.setFieldUpdater(FieldUpdater<T, C>) provides update(int index, T row, C value), which is what you almost always want, because it knows the row.

An updater does not re-render anything. It is a notification. The code in it must change the model and then ask for the affected row to be drawn again, as the pitfalls table below shows with a measurement.

Source: GWT — Developer Guide: Cell Widgets, updating a database from changes in a cell

The example below shows a table of loans, with one column per interesting built-in cell. Loan is a client-side class here (title, due date, returned flag, status); the table itself would look the same with any row type.

Source: GWT — Developer Guide: Cell Tables

Loaded with three loans, the table produced the following markup (data URIs and class names shortened). Note the pieces the compiler and the widget add: a <colgroup> with one <col> per column (the first has the width set with setColumnWidth), __gwt_row and __gwt_cell attributes that route events to the right column, a <select> with the current value marked selected, a number formatted by the NumberFormat, and a <tfoot> whose cell under the "Fine" column holds the computed total.

What the experiment also showed:

Column.setCellStyleNames("name") sets a style for every cell of a column, and Column.getCellStyleNames(Cell.Context, T row) can return a style per cell, as the Bookshelf catalogue does for books with no copies left. AbstractCellTable.setRowStyles(RowStyles<T>) takes an object with getStyleNames(T row, int rowIndex) for the whole row. setColumnWidth(Column, double, Unit) and setColumnWidth(Column, String) control widths, Column.setHorizontalAlignment(...) and setVerticalAlignment(...) the alignment, and addColumnStyleName(int, String) a style on a <col>.

The widths need a fixed layout to be reliable. By default the columns grow to fit the contents of their cells, which looks jumpy when the content changes with paging; table.setWidth("100%", true) switches to the fixed table layout and lets you give the columns percentages (which should add up to 100%), pixels, or a mix: a narrow pixel column for a check box and percentages for the rest. The official guide adds that with table.setWidth("auto", true) a column without a width is invisible, because its width defaults to 0.

The look of the widget itself comes from its Resources bundle. CellTable.Resources defines cellTableStyle() (a CellTable.Style CssResource whose default stylesheet is CellTable.css) and the images for the header and footer backgrounds, the loading indicator and the sort arrows; CellTable.BasicResources is the variant for the GWT standard style theme and uses CellTableBasic.css. To restyle it, extend CellTable.Resources, re-declare cellTableStyle() with @Source({CellTable.Style.DEFAULT_CSS, "mytable.gss"}) and pass an instance to a constructor such as CellTable(int pageSize, Resources resources); the CSS and GSS directives are the subject of the Styling: CSS & GSS page.

For layouts the column model cannot express (several rows per item, a detail row under an expanded item, group headers) a table can be given its own markup builders: AbstractCellTable.setTableBuilder(CellTableBuilder), setHeaderBuilder(HeaderBuilder) and setFooterBuilder(FooterBuilder), with AbstractCellTableBuilder, DefaultCellTableBuilder and AbstractHeaderOrFooterBuilder as starting points. They came with GWT 2.5 (see the older-material section) and are the escape hatch to use instead of abandoning the cell table for a hand-made FlexTable.

Source: GWT Javadoc — CellTable

A cell widget exposes its paging state through HasRows: getVisibleRange(), setVisibleRange(int start, int length), getRowCount(), isRowCountExact(), setRowCount(int) and setRowCount(int, boolean), plus handlers for RangeChangeEvent and RowCountChangeEvent. HasData<T> adds setRowData(int start, List<? extends T>), getVisibleItem(int), getVisibleItems() and setSelectionModel. A Range is the pair start index, length (new Range(0, 10)), a plain serializable value class, so it can also be an argument of an RPC method.

The row count is separate from the rows: a widget can show rows 10 to 19 and still know that there are 25 in all. The count can be exact or an estimate: when a count is not exact, the pager shows "of over N" and lets the user keep going while data keeps arriving, which suits a stream or a server that cannot count cheaply.

ListDataProvider<T> is a provider whose data is a java.util.List in the browser. getList() returns a wrapper of the list: every change made through it (add, set, remove, clear, sort) is noticed and pushed to the displays, at the end of the current event loop, so several changes cost one refresh. flush() pushes immediately, refresh() re-sends every row, and setList(List) replaces the underlying list. The page size of the display decides which rows of the list are shown, so a list of 200 items and a CellList of 25 produce eight pages without further code.

The wrapper cannot see changes inside the items: the Javadoc says so, and the lab measured it with a CellList showing one Book.

getList().set(index, item) is the cheaper way when one row changed: the provider knows which rows were modified and pushes only those, while refresh() pushes all. After a FieldUpdater changed an item in place, either of the two (or display.redrawRow(index) for one row, as the pitfalls table shows) is needed.

Source: GWT source (2.13.1) — ListDataProvider.java

AsyncDataProvider<T> is for data that lives on a server or is expensive to produce. It is deliberately small: you subclass it and implement a single method.

GWT calls that method whenever a display needs a different range: the moment the display is added with addDataDisplay (the display’s current visible range is "initialised" right away, which is why adding the display is the signal to load the first page), when the user pages, when the page size changes, and after a sort when AsyncHandler clears the data. The method’s job is to read display.getVisibleRange(), start the request and, when the answer comes, call two methods that AsyncDataProvider makes public:

The provider does not hold on to the data: it forwards to each display only the rows that fall inside that display’s visible range (an empty list that starts at the page start is delivered too) and ignores the rest, so a late answer for an old range does not put foreign rows on the page. The only state it keeps is the last row count it was told, which it passes to a display that is added later.

Source: GWT — Developer Guide: Cell Widgets, AsyncDataProvider

The guide’s own example simulates the server with a Timer and ends with cellList.setRowData(start, dataInRange) on the widget. That works for one display, but updateRowData on the provider is the call that serves every display attached to it (a table and a list showing the same query) and applies the range check, so use it in real code.

The guide also describes a provider-less way: a widget fires RangeChangeEvent`s, so a presenter can listen with `addRangeChangeHandler, send a request and push rows with setRowData; force the first event with setVisibleRangeAndClearData(new Range(0, 25), true). A data provider is just that code, written once.

A pager is a widget that is connected to any HasRows with setDisplay(HasRows) and calls setVisibleRange on it. Because it listens to RangeChangeEvent and RowCountChangeEvent, it works the same on a CellList, a CellTable, a DataGrid, a custom HasRows, and when the data comes from either provider.

AbstractPager.setRangeLimited(boolean) decides whether the paging operations adjust so that there is always data visible on the page ("range limited") or not.

The label depends on whether the provider told the widget the exact row count. The lab connected a SimplePager to a CellTable of page size 5 over five books, once with an AsyncDataProvider that called only updateRowData, and once with updateRowCount(5, true) first:

Without the count the pager has no way to know that the data ends, and the next-page button stays enabled. Always call updateRowCount with the real total as soon as the server knows it (the Bookshelf page carries the total in BookPage).

Every selection model, data provider and cell widget can be given a ProvidesKey<T>, whose single method Object getKey(T item) returns the identity of an item. Without one, an item is its own key and the model uses equals and hashCode (SimpleKeyProvider is that default). The keys matter in three places:

The lab compared two SingleSelectionModel<Book> instances, one without and one with a key provider that returns the id, after setSelected(book) and then isSelected(sameBookAgain) with a new Book object with the same id:

Give the same key provider to the widget, the data provider and the selection model, and make getKey null-safe, because widgets call it with null for filler rows (the guide says "always do a null check"). The Book::getId method reference used in the Bookshelf DataGrid constructor is not null-safe, but there it only ever receives books that the grid is rendering.

setKeyboardSelectionPolicy takes a KeyboardSelectionPolicy: DISABLED, ENABLED (the default: the arrow keys move a focus highlight, the first row has tabindex="0") or BOUND_TO_SELECTION (the arrow keys also change the selection). setKeyboardPagingPolicy takes CURRENT_PAGE, CHANGE_PAGE (the default: the arrow keys can move into the next page) or INCREASE_RANGE (the page grows). The focus highlight is a style of its own (cellListKeyboardSelectedItem in the CellList output above), separate from the selected style, which is what the tabindex="0" row and the role="button" headers make reachable without a mouse. A cell that handles the Enter key through onEnterKeyDown (see below) is activated from the keyboard the same way.

The HTML a cell appends is assigned to the page without any further escaping, so the cell is where cross-site scripting is prevented or allowed. SafeHtmlBuilder supports the safe habit: appendEscaped(String) turns < and & into entities, appendHtmlConstant(String) is for literals written by the developer (never for data) and append(SafeHtml) adds something already known to be safe (the SafeHtml & XSS page covers the type system behind it). The lab fed the title <script>alert(1)</script> Tricks to a cell that used appendEscaped, and the browser received <script>alert(1)</script> Tricks, displayed as text.

For anything with attributes, string concatenation quickly gets unreadable and unsafe, so GWT generates the code from a template: an interface that extends SafeHtmlTemplates, with one method per fragment and the HTML in an annotation. The type of each parameter says how it is escaped: a String is escaped as text or as an attribute value, a SafeHtml is inserted as is, SafeStyles goes in a style attribute and SafeUri in a href or src.

The lab’s CopiesBadgeCell shows the number of copies of a book as a small badge; clicking it (or pressing Enter on it) asks to borrow a copy.

Source: GWT — Developer Guide: Custom Cells

The pieces to notice:

The cell is used like any other:

Source: GWT — Developer Guide: Cell Widgets, updating a database from a CellTable

and rendered, for the first two books of the lab (the second has no copies left), as this:

A cell widget does not attach a handler to each cell. When a column (or a CellList) is created, the widget asks every cell for getConsumedEvents() once and sinks exactly those events on its root element. When the browser delivers one, the widget finds the row and column from the attributes in the markup (__idx, __gwt_row, __gwt_cell), builds the Context, offers the event to the selection manager as a CellPreviewEvent, and hands it to the cell.

Source: GWT — Developer Guide: Custom Cells, handling events

Because the event list is read once, a cell that returns a different set later gets no new events: the guide’s warning is that the value of getConsumedEvents() must not change. A cell that does not list an event type never receives it, however its HTML looks, and a Column whose cell takes events needs the FieldUpdater for a change to reach the row. The lab clicked the badge of a table (the FieldUpdater only stored the new count) and of a second table (the updater also called redrawRow(index)), and read the cell right after:

One table cell can hold several cells. CompositeCell<C> takes a List<HasCell<C, ?>>; each HasCell<C, X> names a Cell<X>, how to get its value X from the cell’s value C and an optional FieldUpdater<C, X>. Each part is rendered in a <span> of its own, and the composite hands every event to the part that rendered the target. The loan table above ends with an "Actions" column built this way (rendered <span>#3</span><span><button …>Renew</button></span>): a TextCell that shows the loan number and an ActionCell whose Delegate extends the due date. IdentityColumn<T> is the column to use with it, because the composite’s value is the whole row.

IconCellDecorator<C> wraps one cell and puts an ImageResource in front of it (the constructor can also set the vertical alignment); it is the lightweight way to add an icon to a built-in cell without writing a new one.

The RPC contract carries the range and the sort order; the answer carries one page and the total. (The XSRF protection of the service, and the serialisation rules, belong to the GWT-RPC and XSRF, RPC & Server Security pages.)

Source: GWT — Developer Guide: Communicating with a Server

The server maps the client’s text to a comparator from a fixed list, never to a property name chosen by the client, so a forged sortField cannot reach anything else, and it limits length so a client cannot ask for the whole table in one call. (Authorisation of the call belongs on the server too, as always.)

Source: GWT — Developer Guide: Communicating with a Server

The tie-break by id makes the order total: without it, two rows with the same author could swap places between two requests, and a row would appear on two pages or on none. In a real application the sort would be a database ORDER BY with the same whitelist, and start and length a LIMIT and OFFSET (or, better for large tables, a keyset condition).

The presenter is plain Java: it has no GWT.create call, so a JVM unit test runs it with a fake service. It numbers the requests and ignores the answer of a request that is no longer the latest (the out-of-order problem described with the provider).

Source: GWT Javadoc — AsyncCallback

The view owns the DataGrid and the AsyncDataProvider; its onRangeChanged is the only place that knows about sorting. The key provider (Book::getId) is given to the grid.

Source: GWT source (2.13.1) — ColumnSortEvent.java

Three details are easy to get wrong and were all exercised:

The scratch application ran with mvn package and the Jetty 12 plugin (jetty-ee10-maven-plugin) with the XSRF flow in place. Three interactions in the browser produced these requests: a click on "Title", then the next-page button, then a click on "Copies" while on page 2:

In the first line the four arguments are I, I, String and Z (the types are listed after the method name), then four values: 0 (start), 10 (length), the string number 10 (title) and 1 (ascending is true). The second line is the request for page 2 (start 10, length 10, then 0 for the null sort field, ascending). The third is the click on "Copies" while on page 2: start 10, length 10, copies, ascending, as noted above. Each answer was //OK[…] with a BookPage of ten books and the total 25.

The grid’s markup is what the earlier excerpts showed, with a sort arrow image in the sorted header, a row per book and the Open button column:

Source: GWT — Developer Guide: Cell Widgets

The scratch application’s tests ran with mvn verify on JDK 21: 4 GWTTestCase tests of the client (HtmlUnit), 1 for Spanish messages, 4 plain JUnit tests of the presenter and 3 of the server, with no failures. The ones that matter for this page are

The Testing page describes GWTTestCase, HtmlUnit and the Maven setup.