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

align

Атрибут, задающий расположение компонента относительно вышестоящего контейнера. Возможные значения:

TOP_RIGHT
TOP_LEFT
TOP_CENTER
MIDDLE_RIGHT
MIDDLE_LEFT
MIDDLE_CENTER
BOTTOM_RIGHT
BOTTOM_LEFT
BOTTOM_CENTER

box.expandRatio

В контейнерах vbox и hbox компоненты размещаются в слотах. Атрибут box.expandRatio определяет относительную длину для каждого слота. Принимает значение большее или равное 0.

<hbox width="500px" expand="button1" spacing="true">
    <button id="button1" box.expandRatio="1"/>
    <button id="button2" width="100%" box.expandRatio="3"/>
    <button id="button3" width="100%" box.expandRatio="2"/>
</hbox>

Если для компонента указать box.expandRatio=1, а его высота или ширина (в зависимости от типа контейнера) составляет 100%, компонент будет расширен на всё доступное пространство в направлении размещения компонентов.

По умолчанию слоты для компонентов, в зависимости от типа контейнера, имеют одинаковую высоту или ширину (т.е. box.expandRatio=1). Если хотя бы одному компоненту установлено иное значение, все неявные значения игнорируются и учитываются только явно присвоенные значения.

См. также атрибут expand.

caption

Атрибут, устанавливающий заголовок для визуального компонента.

Значением атрибута должна быть либо строка сообщения, либо ключ в пакете сообщений. В случае ключа значение должно начинаться с префикса msg://

Способы задания ключа:

Короткий ключ − при этом сообщение ищется в пакете, заданном для данного экрана:
```
caption="msg://infoFieldCaption"
```

Полный ключ, с заданием пакета:

caption="msg://com.company.sample.gui.screen/infoFieldCaption"

captionAsHtml: Определяет, разрешена ли HTML-разметка в заголовке компонента. Если выбрано значение true, заголовки отображаются в браузере как HTML, при этом ответственность за безопасность используемого HTML-кода несёт сам разработчик. Если выбрано значение false, содержимое заголовка отображается как обычный текст.

Возможные значения − true, false. По умолчанию false.

captionProperty: Задает имя атрибута сущности, отображаемого компонентом. Используется только для сущностей, находящихся в источнике данных (например заданном для LookupField свойством optionsDatasource).

Если captionProperty не задан, будет отображаться имя экземпляра.

colspan: Указывает, сколько колонок сетки должен занять компонент (по умолчанию 1).

Данный атрибут может быть назначен любому компоненту, находящемуся непосредственно внутри контейнера GridLayout.

contextHelpText

Since7.0

Атрибут, задающий текст контекстной подсказки для компонента. Если установлено значение, рядом с полем будет отображаться специальный значок ?. Если поле имеет отдельный заголовок, то есть, установлены атрибуты caption или icon, значок подсказки будет отображаться рядом с заголовком, в противном случае - рядом с самим полем:

В web-клиенте подсказка отображается при наведении курсора мыши на значок ?.

<textField id="textField"
           contextHelpText="msg://contextHelp"/>

contextHelpTextHtmlEnabled

Since7.0

Указывает, может ли текст контекстной подсказки быть обработан как HTML.

<textField id="textField"
           description="Description"
           contextHelpText="<p><h1>Lorem ipsum dolor</h1> sit amet, <b>consectetur</b> adipiscing elit.</p><p>Donec a lobortis nisl.</p>"
           contextHelpTextHtmlEnabled="true"/>

Возможные значения − true, false.

css

Since7.0

Позволяет декларативно указывать CSS-свойства для визуальных UI. Может использоваться совместно с атрибутом stylename, см. пример ниже.

Описание компонента в XML:

<cssLayout css="display: grid; grid-gap: 10px; grid-template-columns: 33% 33% 33%"
           stylename="demo"
           width="100%"
           height="100%">
    <label value="A" css="grid-column: 1 / 3; grid-row: 1"/>
    <label value="B" css="grid-column: 3; grid-row: 1 / 3;"/>
    <label value="C" css="grid-column: 1; grid-row: 2;"/>
    <label value="D" css="grid-column: 2; grid-row: 2;"/>
</cssLayout>

Дополнительный CSS:

  .demo > .v-label {
    display: block;
    background-color: #444;
    color: #fff;
    border-radius: 5px;
    padding: 20px;
    font-size: 150%;
  }

dataContainer: Предназначен для задания data container, описанного в секции data XML-дескриптора экрана.

При указании атрибута dataContainer для компонента необходимо также задать атрибут property.

dataLoader: Предназначен для задания data loader, описанного в секции data XML-дескриптора экрана для data container.

datasource: Предназначен для задания источника данных, описанного в секции dsContext XML-дескриптора экрана.

При указании атрибута datasource для компонента, реализующего интерфейс DatasourceComponent, необходимо также задать атрибут property.

datatype: Предназначен для задания типа данных, если поле не связано с атрибутом сущности (то есть не указан контейнер данных и название атрибута). В качестве значения атрибута указывается имя типа данных, зарегистрированного в метаданных приложения − см. Datatype.

Атрибут используется для компонентов TextField, DateField, DatePicker, TimeField, Slider.

description: Атрибут, задающий текст подсказки для компонента, отображаемой при наведении курсора мыши или клике в области компонента.

descriptionAsHtml: Определяет, разрешена ли HTML-разметка в описании компонента. Если выбрано значение true, заголовки отображаются в браузере как HTML, при этом ответственность за безопасность используемого HTML-кода несёт сам разработчик. Если выбрано значение false, содержимое заголовка отображается как обычный текст.

Возможные значения − true, false. По умолчанию false.

editable: Атрибут, указывающий на возможность редактирования содержимого компонента (не путать с enable).

Возможные значения − true, false. По умолчанию true.

На возможность редактирования содержимого для компонента, связанного с данными (наследника DatasourceComponent или ListComponent), влияет также подсистема безопасности. Если по данным подсистемы безопасности данный компонент должен быть недоступен для редактирования, значение атрибута editable не принимается во внимание.

enable: Атрибут компонента, устанавливающий его состояние: доступен, недоступен.

Если компонент недоступен, то он не принимает фокус ввода. Недоступность контейнера приводит к тому, что все его компоненты также становятся недоступными. Возможные значения − true, false. По умолчанию все компоненты доступны.

expand: Атрибут контейнера для управления его внутренней компоновкой.

Задает компонент внутри контейнера, который необходимо расширить на все доступное пространство в направлении размещения компонентов. Для контейнера с вертикальным размещением устанавливает компоненту 100% высоту, для контейнера с горизонтальным размещением - 100% ширину. Кроме того, при изменении размера контейнера изменять размер будет именно этот компонент.

См.также box.expandRatio.

height: Атрибут, устанавливающий высоту компонента. Высота может быть задана в пикселях либо в процентах от высоты вышестоящего контейнера. Например: 100px, 100%, 50. Если единица измерения не указана, подразумевается высота в пикселях.

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

При выборе значения AUTO или -1px для компонента устанавливается высота по умолчанию, для контейнера высота определяется по содержимому, то есть суммарной высотой вложенных компонентов.

htmlSanitizerEnabled

Определяет, доступна ли HTML-санитизация для содержимого компонента (атрибуты caption, description, contextHelpText). Если атрибут htmlSanitizerEnabled установлен в значение true, а также соответствующие атрибуты (captionAsHtml, descriptionAsHtml, contextHelpTextHtmlEnabled) установлены в значение true, значение атрибутов caption, description и contextHelpText будет санитизировано.

protected static final String UNSAFE_HTML = "<i>Jackdaws </i><u>love</u> <font size=\"javascript:alert(1)\" " +
            "color=\"moccasin\">my</font> " +
            "<font size=\"7\">big</font> <sup>sphinx</sup> " +
            "<font face=\"Verdana\">of</font> <span style=\"background-color: " +
            "red;\">quartz</span><svg/onload=alert(\"XSS\")>";

@Inject
private TextField<String> textFieldOn;
@Inject
private TextField<String> textFieldOff;

@Subscribe
public void onInit(InitEvent event) {
    textFieldOn.setCaption(UNSAFE_HTML);
    textFieldOn.setCaptionAsHtml(true);
    textFieldOn.setHtmlSanitizerEnabled(true); (1)

    textFieldOff.setCaption(UNSAFE_HTML);
    textFieldOff.setCaptionAsHtml(true);
    textFieldOff.setHtmlSanitizerEnabled(false); (2)
}

1	– `TextField` содержит в себе безопасный HTML в качестве заголовка.
2	– `TextField` содержит в себе небезопасный HTML в качестве заголовка.

Значение атрибута htmlSanitizerEnabled имеет приоритет над значением глобального свойства cuba.web.htmlSanitizerEnabled.

icon

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

Значением атрибута должен быть путь к файлу значка относительно каталога темы:

icon="icons/create.png"

либо его имя в используемом наборе значков:

icon="CREATE_ACTION"

Если значок должен быть выбран в зависимости от языка пользователя, можно указать путь к нему в пакете сообщений, а в атрибуте icon − ключ сообщения, например:

icon="msg://addIcon"

В веб-клиенте с темой Halo (или производной от нее) вместо файлов можно использовать элементы шрифта Font Awesome. Для этого достаточно указать константу из класса com.vaadin.server.FontAwesome с префиксом font-icon: например:

icon="font-icon:BOOK"

Подробнее об использовании значков можно прочитать в разделе Значки.

id: Идентификатор компонента.

Рекомендуется формировать значение по правилам Java-идентификаторов и использовать camelСase, например, userGrid, filterPanel.Может быть указан для любого компонента и должен быть уникальным в пределах экрана.

inputPrompt

Атрибут inputPrompt задает строку, отображаемую в поле, если его значение равно null.

<suggestionField inputPrompt="Let's search something!"/>

Атрибут используется для компонентов TextField, LookupField, LookupPickerField, SearchPickerField, SuggestionPickerField только в веб-клиенте.

margin

Атрибут margin устанавливает наличие отступа между внешними границами и содержимым контейнера.

Может иметь два вида значений:

margin="true" − установить отступ со всех сторон сразу
margin="true,false,true,false" − установить отступ только сверху и снизу (формат значения "сверху,справа,снизу,слева")

По умолчанию отступы отсутствуют.

metaClass

Задает тип колонок таблицы в случае, если не задано значение атрибутов dataContainer или datasource. Определение атрибута metaClass в XML эквивалентно заданию пустых значений для табличных компонентов DataGrid, GroupTable, Table, TreeDataGrid и TreeTable. Таким образом, вы можете указать данные для компонента программно в контроллере экрана.

 <table id="table" metaClass="sec$User">
       <actions>
             <action id="refresh" type="refresh"/>
       </actions>
 </table>

nullName

Идентификатор опции, выбор которой будет равносилен установке значения в null.

Атрибут используется для компонентов LookupField, LookupPickerField, SearchPickerField.

Пример для компонента LookupField, установка значения атрибута в XML-дескрипторе:

<lookupField datasource="orderDs"
             property="customer"
             nullName="(none)"
             optionsDatasource="customersDs" width="200px"/>

Пример для компонента LookupField, установка значения атрибута в контроллере:

<lookupField id="customerLookupField" optionsDatasource="customersDs"
             width="200px" datasource="orderDs" property="customer"/>

customerLookupField.setNullOption("<null>");

openType: Задает режим открытия связанного экрана. Соответствует перечислению WindowManager.OpenType со значениями NEW_TAB, THIS_TAB, NEW_WINDOW, DIALOG. По умолчанию THIS_TAB.

optionsContainer: Задает имя контейнера data container, используемого для формирования списка опций.

Совместно с optionsContainer может использоваться атрибут captionProperty.

optionsDatasource: Задает имя источника данных, используемого для формирования списка опций.

Совместно с optionsDatasource может использоваться атрибут captionProperty.

optionsEnum: Задаёт полное имя класса перечисления, используемого для формирования списка опций.

property: Атрибут компонента, реализующего интерфейс DatasourceComponent.

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

Используется всегда совместно с атрибутом datasource.

required: Атрибут визуального компонента, реализующего интерфейс Field. Указывает, что в данное поле обязательно должно быть введено значение.

Возможные значения атрибута − true, false. По умолчанию false.

Совместно с required может использоваться атрибут requiredMessage.

requiredMessage: XML-атрибут, используемый совместно с атрибутом required. Позволяет установить сообщение, выводимое пользователю в случае нарушения требования required.

Атрибут может содержать сообщение или ключ в пакете сообщений, например: requiredMessage="msg://infoTextField.requiredMessage"

responsive: Определяет, должен ли компонент реагировать на изменения размеров доступной области. Реакцию можно задать с помощью стилей.

Возможные значения атрибута − true, false. По умолчанию false.

rowspan: Указывает, сколько строк сетки должен занять компонент (по умолчанию 1).

Данный атрибут может быть назначен любому компоненту, находящемуся непосредственно внутри контейнера GridLayout.

settingsEnabled: Определяет, нужно ли сохранять пользовательские настройки отображения компонента. Настройки сохраняются только для компонентов, имеющих id.

Возможные значения атрибута − true, false. По умолчанию true.

showOrphans

Since7.2.8

Атрибут showOrphans используется для управления видимостью сиротских записей древовидных компонентов, то есть записей, родители которых недоступны в текущем наборе данных. Если атрибут showOrphans имеет значение false, компонент не отображает сиротские записи. Если атрибут showOrphans имеет значение true, компонент ведет себя как и раньше, то есть сиротские записи отображаются на верхнем уровне в виде корневых записей.

Значение по умолчанию: true.

Сокрытие сиротских записей выглядит как естественный выбор при использовании фильтров. Однако это не помогает при постраничном отображении (некоторые страницы будут пустыми или наполовину заполненными), поэтому при использовании древовидных компонентов постраничное отображение следует отключить:

Установите значение атрибута useMaxResults у фильтра в значение false;
Удалите элемент rowsCount из таблиц.

Этот атрибут используется для компонентов Tree, TreeDataGrid, TreeTable.

spacing: Атрибут spacing устанавливает наличие отступов между компонентами внутри контейнера.

Возможные значения − true, false.

По умолчанию отступы отсутствуют.

stylename

Атрибут, задающий имя стиля компонента. Подробнее см. Темы приложения.

В теме halo определено несколько стандартных стилей для компонентов:

huge - устанавливает размер поля 160% от его размера по умолчанию.

large - устанавливает размер поля 120% от его размера по умолчанию.

small - устанавливает размер поля 85% от его размера по умолчанию.

tiny - устанавливает размер поля 75% от его размера по умолчанию.

tabCaptionsAsHtml: Определяет, разрешена ли HTML-разметка в заголовках вкладок. Если выбрано значение true, заголовки отображаются в браузере как HTML, при этом ответственность за безопасность используемого HTML-кода несёт сам разработчик. Если выбрано значение false, содержимое заголовка отображается как обычный текст.

Возможные значения − true, false. По умолчанию false.

tabIndex

Определяет, может ли компонент принимать фокус, и задаёт относительный порядок перехода фокуса между компонентами экрана.

Может принимать положительное или отрицательное целочисленное значение:

отрицательное значение означает, что компонент может принимать фокус, но будет пропущен при последовательном перемещении фокуса с клавиатуры;
0 означает, что компонент может принимать фокус, в том числе и при его перемещении с клавиатуры, но его относительный порядковый номер будет совпадать с его расположением на экране относительно других компонентов.
положительное значение означает, что компонент может принимать фокус, в том числе и при его перемещении с клавиатуры. Относительный порядковый номер компонента будет совпадать со значением атрибута: фокус будет перемещаться от меньшего значения tabIndex к большему. Если для нескольких компонентов установлено одинаковое значение tabIndex, порядок их фокуса будет совпадать с их расположением на экране относительно друг друга.

tabsVisible: Определяет, должна ли область выбора вкладок отображаться в UI.

Возможные значения − true, false. По умолчанию true.

textSelectionEnabled: Определяет, разрешено ли выделение текста в ячейках таблицы.

Возможные значения атрибута − true, false. По умолчанию false.

visible: Атрибут, устанавливающий видимость компонента. Возможные значения − true, false.

Если контейнер невидим, не видны и все его компоненты. По умолчанию все компоненты видимы.

width: Атрибут, устанавливающий ширину компонента.

Значение может быть задано в пикселях или в процентах от ширины вышестоящего контейнера. Например: 100px, 100%, 50. Если единица измерения не указана, подразумевается ширина в пикселях. Простановка значения в % означает, что компонент по ширине займет соответствующую часть пространства, предоставляемого контейнером более высокого уровня.

При выборе значения AUTO или -1px для компонента устанавливается ширина по умолчанию, для контейнера ширина определяется по содержимому, то есть суммарной шириной вложенных компонентов.

3.5.2.6. XML-атрибуты компонентов