DataTable

DataTable<T> shows the rows of a model as a table, one page at a time.

SimpleSearchModel<Album> model = new SimpleSearchModel<>(this,
    QCriteria.create(Album.class).ascending(Album_.title()));

RowRenderer<Album> rr = new RowRenderer<>(Album.class);
rr.column(Album_.title()).label("Album").width(40).ascending().sortdefault();
rr.column(Album_.artist().name()).label("Artist").width(30).ascending();

DataTable<Album> table = new DataTable<>(model, rr);
cp.add(table);
table.setPageSize(10);
cp.add(new DataPager(table));

• The table itself
• Clicking
• Selecting rows
• Data binding in a table
• Every value cell is already bound
• A cell built by a renderer is not
• Editable cells
• Style bound to the row
• The footer binds to anything
• Binding the rows themselves: an observable list
• The special cases
• Column widths
• Letting the user resize columns

The table itself

Setting a new model is the normal way to run a new search: the table redraws itself from the new rows and the pager follows. The renderer stays.

Clicking

A click handler is set on the renderer, not on the table:

rr.setRowClicked(album -> UIGoto.moveSub(AlbumDetailPage.class, "id", album.getId()));
rr.column(Album_.title()).cellClicked(album -> rename(album));

A cell handler wins over the row handler for its own column, and cells that have one are marked (ui-cellsel) so the user can see that they do something.

Selecting rows

A table gets a selection column as soon as it has a selection model:

InstanceSelectionModel<Album> selection = new InstanceSelectionModel<>(true);
table.setSelectionModel(selection);
table.setSelectionAllHandler(new DefaultSelectAllHandler());
table.setShowSelection(true);

A row the acceptor refuses still gets a checkbox, but a dead one: DomUI turns a read-only checkbox into a disabled one, because html has no read-only checkbox. Select-all respects the acceptor too - in the demo it selects two albums out of 347.

selection.addListener(...) reports every change, through selectionChanged(row, on) and selectionAllChanged(); the table itself listens as well, which is how the checkboxes follow a selection made in code.

Data binding in a table

Binding in a table is not the same subject as binding on a form, because a table has many rows, only some of them on screen, and it builds their cells itself. This section is what that changes.

Every value cell is already bound

A column that shows a property does not render text: it renders a DisplaySpan bound to that property of that row object. So this is all it takes for the screen to follow the data:

rr.column("copies").label("Copies");        // A bound cell, like every other one
…
line.setCopies(line.getCopies() + 1);       // The cell updates. Nothing else is called.

No forceRebuild(), no telling the table, no re-query. The binding was made when the row was rendered and lives inside the cell, and the page's binding pass moves the value on every request.

A cell built by a renderer is not

A renderer builds content from whatever it likes, so there is no single value the binding could watch, and nothing updates it. Say rerenderOnBind() and the cell is redrawn once per request instead:

rr.column().label("Line total")
    .renderer((node, line) -> node.add(line.getCopies() + " x 14.95"))
    .rerenderOnBind();                       // ...or the cell keeps its first text

The demo above has the same column twice, with and without it: after pressing a button the bound one follows and the other still shows what it rendered when the page was built.

valueHint(QField) works the same way for the cell's tooltip - it binds the cell's title to a property of the row.

Editable cells

editable() puts a control in the cell and binds it to the row's property, which is what makes a table of input boxes work with no code at all:

rr.column("copies").label("Copies").editable();

Which control it is comes from the metadata of the property, exactly as in a form. factory(row -> …) makes the control yourself, and is asked once per row so the control can depend on what is in it.

An editable column cannot also have a renderer or a converter: a cell either shows a value or holds a control, and asking for both throws.

Style bound to the row

A column can bind a css class to a property of the row, which is how a table colours the rows that need attention:

rr.column("copies").label("Copies")
    .styleBinding(new StyleBinder()
        .define(Boolean.TRUE, "row-warning")
        .define(Boolean.FALSE, ""))
    .to("bulk");                              // A property of the row object

The footer binds to anything

getFooterBody() hands back an ordinary TBody under the rows, so a total is just a control bound to whatever holds it - usually the page or a controller rather than a row:

Text2<Integer> total = new Text2<>(Integer.class);
total.setReadOnly(true);
total.bind().to(this, "totalCopies");         // A property of the page

TR tr = table.getFooterBody().addRow();
tr.addCell().add("Copies in total");
tr.addCell().add(total);

Binding the rows themselves: an observable list

A table can be given an IObservableList<T> instead of a model:

DataTable<Album> table = new DataTable<>(rr);
table.setList(artist.getAlbumList());         // A Hibernate relation list is observable

The table then listens to the list, and changing the list changes the table: adding an album to the artist's list adds a row. What the table does with an event depends on how many changes arrive at once:

That is the natural way to write a master/detail screen: the detail table is bound to the relation of the master record, and nothing has to be told when the relation changes.

The special cases

The binding pass walks every control on the page once per request, so an editable table is that many comparisons per request: a hundred rows of five editable columns is five hundred. That is cheap, but it is not free, and it is a reason to page a large table rather than show it whole.

Column widths

Every column can be given a width in one of two ways, and the table treats them differently:

• width(int characters) - the default, and what metadata supplies. The renderer multiplies the character count by its emFactor (0.65) and renders an em width, because text is not all Ms.
• width(String css) - an explicit css width. If one column uses this, all of them should: only the css widths are then used.

The last column is special: in a table with setTableWidth("100%") it gets no width at all, so it takes up whatever is left. In a table with no width it does get one, and the table is then as wide as its columns.

Letting the user resize columns

A resize is reported to the server so an application can remember it, per renderer with rr.setColumnListener(...), or once for the whole application:

//-- In DomApplication.initialize()
setAttribute(RowRenderer.COLUMN_LISTENER, (IColumnListener<Object>) (tbl, newWidths) -> saveWidths(tbl, newWidths));