Платформа CUBA. Руководство по разработке приложений
4.5.2.1. Компоненты

rows - обязательный элемент, в атрибуте datasource которого необходимо объявить используемый таблицей источник данных.

Для строк можно настроить отображение заголовков - задать каждой строке свой значок в дополнительной колонке слева. Для этого в контроллере экрана необходимо реализовать интерфейс Table.IconProvider и установить его таблице:

@Inject
protected Table customersTable;
...
    customersTable.setIconProvider(new Table.IconProvider() {
        @Nullable
        @Override
        public String getItemIcon(Entity entity) {
            CustomerGrade grade = ((Customer) entity).getGrade();
            switch (grade) {
                case PREMIUM: return "icons/premium_grade.png";
                case HIGH: return "icons/high_grade.png";
                case MEDIUM: return "icons/medium_grade.png";
                default: return null;
            }
        }
    });

columns - обязательный элемент, определяет набор колонок таблицы.

Каждая колонка описывается во вложенном элементе column со следующими атрибутами:

rowsCount − необязательный элемент, создающий для таблицы компонент RowsCount, который позволяет загружать в таблицу данные постранично. Размер страницы задается путем ограничения количества записей в источнике данных методом CollectionDatasource.setMaxResults(). Как правило, это делает связанный с источником данных таблицы компонент Filter, однако при отсутствии универсального фильтра можно вызвать этот метод и напрямую из контроллера экрана.

Компонент RowsCount может также отобразить общее число записей, возвращаемых текущим запросом в источнике данных, без извлечения этих записей. Для этого при щелчке пользователя на знаке "?" он вызывает метод AbstractCollectionDatasource.getCount(), что приводит к выполнению в БД запроса с такими же, как у текущего запроса условиями, но с агрегатной функцией COUNT(*) вместо результатов. Полученное число отображается вместо знака "?".

actions − необязательный элемент для описания действий, связанных с таблицей. Кроме описания произвольных действия поддерживаются следующие стандартные действия, определяемые перечислением ListActionType: create, edit, remove, refresh, add, exclude, excel.

buttonsPanel - необязательный элемент, создающий над таблицей контейнер ButtonsPanel для отображения кнопок действий.

Атрибут multiselect позволяет задать режим множественного выделения строк в таблице. Если multiselect равен true, то пользователь может выделить несколько строк с помощью клавиатуры или мыши, удерживая клавиши Ctrl или Shift. По умолчанию режим множественного выделения отключен.

Атрибут sortable разрешает или запрещает сортировку в таблице. По умолчанию имеет значение true. Если сортировка разрешена, то при нажатии на название колонки справа от названия появляется значок /.

При включенной с помощью элемента rowsCount (см. выше) страничной загрузке таблицы сортировка производится разными способами в зависимости от того, умещаются ли все записи на одной странице. Если умещаются, то сортировка производится в памяти, без обращений к БД. Если же страниц больше одной, то сортировка производится на базе данных путем отправки нового запроса с соответствующимORDER BY.

Колонка таблицы может ссылаться на локальный атрибут или на связанную сущность. Например:

<table id="ordersTable">
    <columns>
        <column id="customer.name"/> <!-- the 'name' attribute of the 'Customer' entity -->
        <column id="contract"/>      <!-- the 'Contract' entity -->
    </columns>
    <rows datasource="ordersDs"/>
</table>

В последнем случае, сортировка на базе данных производится по атрибутам, указанным в аннотации @NamePattern связанной сущности. Если у связанной сущности нет такой аннотации, то сортировка производится в памяти только в пределах текущей страницы.

Если колонка таблицы ссылается на неперсистентный атрибут, то сортировка на базе данных производится по атрибутам, указанным в параметре related() аннотации @MetaProperty. Если такой параметр не указан, то сортировка производится в памяти только в пределах текущей страницы.

Атрибут presentations управляет механизмом представлений. Значение по умолчанию равно false. Когда значение атрибута равно true, то в верхнем правом углу таблицы появляется значок . Механизм представлений реализован только для блока Web Client.

Установка атрибута columnControlVisible в false запрещает пользователю скрывать колонки с помощью меню, выпадающего при нажатия на кнопку в правой части шапки таблицы. Флажками в меню отмечаются отображаемые в данный момент колонки.

Установка атрибута reorderingAllowed в false запрещает пользователю менять местами колонки, перетаскивая их с помощью мыши.

Атрибут contextMenuEnabled разрешает или запрещает показывать контекстное меню. По умолчанию атрибут имеет значение true. В контекстном меню отображаются действия таблицы (если они есть), и пункт Системная информация, содержащий информацию о выбранной сущности (если у пользователя есть разрешение cuba.gui.showInfo, см. руководство по подсистеме безопасности).

Если атрибуту multiLineCells таблицы присвоить значение true, то ячейки, содержащие текст с переносами строк, будут отображать его в несколько строк. В таком режиме в веб клиенте для правильной работы полосы прокрутки все строки текущей страницы таблицы будут загружены веб-браузером сразу, без ленивой загрузки видимой части таблицы. По умолчанию атрибут имеет значение false.

Атрибут aggregatable включает режим агрегации строк таблицы. Поддерживаются следующие операции:

Для агрегируемых колонок необходимо указать элемент aggregation с атрибутом type, задающим функцию агрегации. Агрегированные значения столбцов выводятся в дополнительной строке вверху таблицы. Пример описания таблицы с агрегацией:

<table id="itemsTable" aggregatable="true">
    <columns>
        <column id="product"/>
        <column id="quantity"/>
        <column id="amount">
            <aggregation type="SUM"/>
        </column>
    </columns>
    <rows datasource="itemsDs"/>
</table>

Для отображения агрегированного значения в виде, отличном от стандартного для данного Datatype, для него можно указать Formatter:

<column id="amount">
    <aggregation type="SUM">
        <formatter class="com.company.sample.MyFormatter"/>
    </aggregation>
</column>

В дополнение к операциям, перечисленным выше, можно задать собственную стратегию агрегации путем создания класса, реализующего интерфейс AggregationStrategy, и передачи его методу setAggregation() класса Table.Column в составе экземпляра AggregationInfo. Например:

public class TimeEntryAggregation implements AggregationStrategy<List<TimeEntry>, String> {
    @Override
    public String aggregate(Collection<List<TimeEntry>> propertyValues) {
        HoursAndMinutes total = new HoursAndMinutes();
        for (List<TimeEntry> list : propertyValues) {
            for (TimeEntry timeEntry : list) {
                total.add(HoursAndMinutes.fromTimeEntry(timeEntry));
            }
        }
        return StringFormatHelper.getTotalDayAggregationString(total);
    }
    @Override
    public Class<String> getResultClass() {
        return String.class;
    }
}

AggregationInfo info = new AggregationInfo();
info.setPropertyPath(metaPropertyPath);
info.setStrategy(new TimeEntryAggregation());

Table.Column column = weeklyReportsTable.getColumn(columnId);
column.setAggregation(info);

Атрибут editable позволяет перевести таблицу в режим in-place редактирования ячеек. В этом режиме в колонках, имеющих атрибут editable = true, отображаются компоненты для редактирования значений атрибутов сущности, находящейся в источнике данных.

Тип компонента для каждой редактируемой колонки выбирается автоматически на основании типа атрибута сущности. Например, для строковых и числовых атрибутов используется TextField, для Date - DateField, для перечислений - LookupField, для ссылок на другие сущности - PickerField.

Для редактируемой колонки типа Date можно дополнительно указать атрибуты dateFormat или resolution аналогично описанным для DateField.

Для редактируемой колонки, отображающей связанную сущность, можно дополнительно указать атрибуты optionsDatasource и captionProperty. При указании optionsDatasource вместо PickerField используется компонент LookupField.

Произвольно настроить отображение ячеек, в том числе для редактирования содержимого, можно с помощью метода Table.addGeneratedColumn() - см. ниже.

getSelected(), getSingleSelected() - возвращают экземпляры сущностей, соответствующие выделенным в таблице строкам. Коллекцию можно получить вызовом метода getSelected(). Если ничего не выбрано, возвращается пустой набор. Если multiselect отключен, удобно пользоваться методом getSingleSelected(), возвращающим одну выбранную сущность или null, если ничего не выбрано.

Метод addGeneratedColumn() позволяет задать собственное представление данных в колонке. Он принимает два параметра: идентификатор колонки и реализацию интерфейсаTable.ColumnGenerator. Идентификатор может совпадать с одним из идентификаторов, указанных для колонок таблицы в XML-дескрипторе - в этом случае новая колонка вставляется вместо заданной в XML. Если идентификатор не совпадает ни с одной колонкой, создается новая справа.

Метод generateCell() интерфейса Table.ColumnGenerator вызывается таблицей для каждой строки, и в него передается экземпляр сущности, отображаемой в данной строке. Метод generateCell() должен вернуть визуальный компонент, который и будет отображаться в ячейке.

Пример использования:

@Inject
protected Table carsTable;

@Inject
protected ComponentsFactory componentsFactory;

@Override
public void init(Map<String, Object> params) {
    carsTable.addGeneratedColumn("colour", new Table.ColumnGenerator() {
        @Override
        public Component generateCell(Entity entity) {
            LookupPickerField field = componentsFactory.createComponent(LookupPickerField.NAME);
            field.setDatasource(carsTable.getItemDatasource(entity), "colour");
            field.setOptionsDatasource(coloursDs);
            field.addLookupAction();
            field.addOpenAction();
            return field;
        }
    });
}

В данном случае в ячейках колонки colour таблицы отображается компонент LookupPickerField. Компонент должен сохранять свое значение в атрибут colour сущности, экземпляр которой отображается в данной строке. Для этого у таблицы методом getItemDatasource() запрашивается источник данных для текущего экземпляра сущности, и передается компоненту LookupPickerField.

Если в ячейке необходимо отобразить просто динамически сформированный текст, вместо компонента Label используйте класс Table.PlainTextCell. Это упростит отрисовку и сделает таблицу быстрее.

Если в метод addGeneratedColumn() передан идентификатор колонки, не объявленной в XML-дескрипторе, то может понадобиться установить заголовок новой колонки следующим образом:

carsTable.getColumn("colour").setCaption("Colour");

Метод setClickListener() может избавить от необходимости добавлять генерируемые колонки с компонентами, если нужно нарисовать что-либо в ячейках и получать оповещения когда пользователь кликает на эти ячейки. Имплементация класса CellClickListener, передаваемая в данный метод, получает текущий экземпляр сущности и идентификатор колонки. Содержимое ячеек будет завернуто в элемент span со стилем cuba-table-clickable-cell, который можно использовать для задания отображения ячеек.

Метод setStyleProvider() позволяет задать стиль отображения ячеек таблицы. Параметром метода должна быть реализация интерфейса Table.StyleProvider. Метод getStyleName() этого интерфейса вызывается таблицей отдельно для каждой строки и для каждой ячейки. Если метод вызван для строки, то первый параметр содержит экземпляр сущности, отображаемый этой строкой, а второй параметр null. Если же метод вызван для ячейки, то второй параметр содержит имя атрибута, отображаемого этой ячейкой.

Пример задания стилей:

@Inject
protected Table customersTable;

@Override
public void init(Map<String, Object> params) {
    customersTable.setStyleProvider(new Table.StyleProvider() {
        @Nullable
        @Override
        public String getStyleName(Entity entity, @Nullable String property) {
            Customer customer = (Customer) entity;
            if (property == null) {
                // style for row
                if (hasComplaints(customer)) {
                    return"unsatisfied-customer";
                }
            } else if (property.equals("grade")) {
                // style for column "grade"
                switch (customer.getGrade()) {
                    case PREMIUM: return "premium-grade";
                    case HIGH: return "high-grade";
                    case MEDIUM: return "medium-grade";
                    default: return null;
                }
            }
            return null;
        }
    });
}

Далее нужно определить заданные для строк и ячеек стили в теме приложения. Подробная информация о создании темы находится вРаздел 4.5.7, «Создание темы приложения». Для веб-клиента новые стили определяются в файле styles.scss. Имена стилей, заданные в контроллере, совместно с префиксами, обозначающими строку или колонку таблицы, образуют CSS-селекторы. Например:

.v-table-row-unsatisfied-customer {
  font-weight: bold;
}

.v-table-cell-content-premium-grade {
  background-color: red;
}

.v-table-cell-content-high-grade {
  background-color: green;
}

.v-table-cell-content-medium-grade {
  background-color: blue;
}

Метод addPrintable() позволяет задать специфическое представление данных колонки при выводе в XLS-файл, осуществляемом стандартным действием excel или напрямую с помощью класса ExcelExporter. Метод принимает идентификатор колонки и реализацию интерфейса Table.Printable для нее. Например:

ordersTable.addPrintable("customer", new Table.Printable<Customer, String>() {
    @Override
    public String getValue(Customer customer) {
        return "Name: " + customer.getName;
    }
});

Метод getValue() интерфейса Table.Printable должен возвращать данные, которые будут находиться в ячейке таблицы. Это может быть не только строка - метод может возвращать значения других типов, например, числовые данные или даты, и они будут представлены в XLS-файле соответствующим образом.

Если форматированный вывод в XLS необходим для генерируемой колонки, нужно использовать реализацию интерфейса Table.PrintableColumnGenerator, передавая ее методу addGeneratedColumn(). Значение для вывода в ячейку XLS-документа задается в методе getValue() этого интерфейса:

ordersTable.addGeneratedColumn("product", new Table.PrintableColumnGenerator<Order, String>() {
    @Override
    public Component generateCell(Order entity) {
        Label label = componentsFactory.createComponent(Label.NAME);
        Product product = order.getProduct();
        label.setValue(product.getName() + ", " + product.getCost());
        return label;
    }

    @Override
    public String getValue(Order entity) {
        Product product = order.getProduct();
        return product.getName() + ", " + product.getCost();
    }
});

Если генерируемой колонке тем или иным способом не задано представления Printable, то в случае, если колонке соответствует атрибут сущности, будет выведено его значение, в противном случае не будет выведено ничего.

Метод setItemClickAction() позволяет задать действие, выполняемое при двойном клике на строке таблицы. Если такое действие не задано, при двойном клике таблица пытается найти среди своих действий подходящее в следующем порядке:

Если такое действие найдено и имеет свойство enabled = true, оно выполняется.

Метод setEnterPressAction() позволяет задать действие, выполняемое при нажатии клавиши Enter. Если такое действие не задано, таблица пытается найти среди своих действий подходящее в следующем порядке:

Если такое действие найдено и имеет свойство enabled = true, оно выполняется.