WTableColumn
WTableColumn represents a column in a WTable.
- Creating a WTableColumn
- Accessibility
- Header
- Content
- Alignment
- Width
- Related components
- Further information
There are four constructors for WTableColumn and all are variations of arguments specifiying a header and a content component.
The header may be specified as a String (recommended) or WDecoratedLabel. The content is passed as a WComponent or a class (which must extend WComponent).
// a column holding simple text
// assume String TEXT_COL_HEADING from elsewhere...
WTableColumn textCol = new WTableColumn(TEXT_COL_HEADING, new WText());// a class to create a complex piece of content
public class SomeNewComponent extends WComponent {
// ...
}
// a table column may use a class in its constructor
WTableColumn someColumn = new WTableColumn("Some title", SomeNewComponent.class);To create a column which holds telephone numbers, for example, it is recommended that WPhoneNumberField be used, even if it is never editable, as the output will be formatted to create a tel: protocol link.
// onbly ever output read-only phone numbers
public class ReadOnlyPhoneField extends WPhoneNumberField {
@override
public bolean isReadOnly() {
return true;
}
}
// use the new class in a table column
WTableColumn phoneCol = new WTableColumn("Phone", ReadOnlyPhoneField.class);
// Or a really lazy way to the same thing:
WTableColumn phoneCol = new WTableColumn("Phone", new WPhoneNumberField() {
@Override
public boolean isReadOnly() {
return true;
}
});All columns in a WTable must be adequately labelled. The content must be adequate to identify the data in the column and must be palpable.
The column header for a WTableColumn is a WDecoratedLabel. Any other WComponent may be added to the WDecoratedLabel except a WApplication or another WTable. Given that the content must be palpable and should not normally be interactive itself then it is recommended that the header content be a simple WText or WAbbrText.
Use of interactive controls in a column heading is discouraged but some use-cases make this appropriate. If sorting is enabled the column heading also acts as the control to sort the table by that column and in this case the column heading should not include any interactive controls.
The column header may be moved out of viewport if all column headers in a given WTable are to be moved out of view. This is discouraged, see hiding column headings.
If an application needs to refer to the content of a column header it can do so by getting the WDecoratedLabel or, under what should be common circumstances, get the content as a String.
// get the header component from WTableColumn `col`
WDecoratedLabel header = col.getColumnLabel();The header content can be accessed as a String if:
- the column was originally created with a String as the label; or
- the WDecoratedLabel has a body component which is any one of:
In these cases getHeadingText() will return the value of the original String or the text content of the body component of the WDecoratedLabel. If the WDecoratedLabel was constructed in any other way then getHeadingText() will return null.
// assume WTableColumn `col` created using a WDecoratedLabel `header`
WDecoratedLabel header = new WDecoratedLabel(new WAbbrText("ID", "User ID"));
// ...
WTableColumn col = new WTableColumn(header, MyColumnContentRenderer.class);
// ...
// somewhere else, maybe a different class ...
// get the header component from WTableColumn `col`
String headerContent = col.getHeadingText();
// headerContent is "ID"The column content is based on a WComponent. It is passed to the constructor either as a WComponent or or a class which extends WComponent. The content rendered by this component is determined by the data passed to the WTableColumn instance for the row being rendered.
WTable is a repeated component. Each data column in the table contains the same type. It is up to the column renderer class or component to determine what to do with this data. This means complex tables, with variations on content in a column, are more difficult to create. This is done on purpose because a table which does not contain the same type of content (or nothing, being represented by null) in a column is possibly not really a table at all.
The horizontal alignment of content within a table column is set using the align property determined by a value from the WTablwColumn.Alignment enum. Available settings are:
-
Alignment.LEFT; -
Alignment.CENTER; and -
Alignment.RIGHT.
// center align WTableColumn `col`
col.setAlign(Alignment.CENTER);
// right align `col`
col.setAlign(Alignment.RIGHT);There is no Java-determined default alignment. The default is determined by Theme i18n. The theme default is LEFT. The alignment is held on the WTableColumn's model and so is able to be amended on a per-user basis.
The content of a row is always aligned to the top of the row.
It is possible to specify the preferred width for the column in percent. If you do not specify a width for a column it will be determined by the user agent based on the content of the most content-rich cell in the column. Colun width is specified as a percentage of the available space. To create a column width using any other means requires the use of custom CSS. The width of the column is held on the WTableColumn's model and so is able to be amended on a per-user basis.
// set the width of `col` to 18%
col.setWidth(18);