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

5.5.2.1.26. OptionsGroup

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

XML-имя компонента: optionsGroup.

Компонент OptionsGroup реализован для блоков Web Client и Desktop Client.

Простейший вариант использования OptionsGroup - выбор значения перечисления (enum) для атрибута сущности. Например, сущность Role имеет атрибут type типа RoleType, который является перечислением. Тогда для редактирования этого атрибута можно использовать OptionsGroup следующим образом:
```
<dsContext>
    <datasource id="roleDs" class="com.haulmont.cuba.security.entity.Role" view="_local"/>
</dsContext>
<layout>
    <optionsGroup datasource="roleDs" property="type"/>
```
Как видно из примера, в экране описывается источник данных roleDs для сущности Role. В компоненте optionsGroup в атрибуте datasource указывается ссылка на источник данных, а в атрибуте property − название атрибута сущности, значение которого должно быть отображено.

В результате компонент примет следующий вид:
Список опций компонента может быть задан произвольно с помощью методов setOptionsList(), setOptionsMap() и setOptionsEnum(), либо с помощью XML-атрибута optionsDatasource.

Метод setOptionsList() позволяет программно задать список опций компонента. Для этого объявляем компонент в XML-дескрипторе:
```
<optionsGroup id="numberOfSeatsField"/>
```
Затем инжектируем компонент в контроллер и в методе init() задаем ему список опций:
```
@Inject
protected OptionsGroup numberOfSeatsField;

@Override
public void init(Map<String, Object> params) {
    List<Integer> list = new ArrayList<>();
    list.add(2);
    list.add(4);
    list.add(5);
    list.add(7);
    numberOfSeatsField.setOptionsList(list);
}
```
Компонент примет следующий вид:

При этом метод getValue() компонента в зависимости от выбранной опции будет возвращать Integer значения 2,4,5,7.

Метод setOptionsMap() позволяет задать строковые названия и значения опций по отдельности. Например, для описанного в XML-дескрипторе компонента numberOfSeatsField в методе init() контроллера задаем мэп опций:
```
@Inject
protected OptionsGroup numberOfSeatsField;

@Override
public void init(Map<String, Object> params) {
    Map<String, Object> map = new LinkedHashMap<>();
    map.put("two", 2);
    map.put("four", 4);
    map.put("five", 5);
    map.put("seven", 7);
    numberOfSeatsField.setOptionsMap(map);
}
```
Компонент примет следующий вид:

При этом метод getValue() компонента в зависимости от выбранной опции будет возвращать Integer значения 2,4,5,7, а не строки, отображаемые на экране.

setOptionsEnum() принимает в качестве параметра класс перечисления. Список опций будет состоять из локализованных названий значений перечисления, значением компонента будет являться выбранное значение перечисления.
Компонент может брать список опций из источника данных. Для этого используется атрибут optionsDatasource. Например:
```
<dsContext>
    <collectionDatasource id="coloursDs" class="com.company.sample.entity.Colour" view="_local">
        <query>select c from sample$Colour c</query>
    </collectionDatasource>
</dsContext>
<layout>
    <optionsGroup id="coloursField" optionsDatasource="coloursDs"/>
```
В данном случае компонент coloursField отобразит имена экземпляров сущности Colour, находящихся в источнике данных coloursDs, а его метод getValue() вернет выбранный экземпляр сущности.

С помощью атрибута captionProperty можно указать, какой атрибут сущности использовать вместо имени экземпляра для строковых названий опций.

С помощью атрибута multiselect можно переключить OptionsGroup в режим множественного выбора. Если multiselect включен, то компонент отображается как группа независимых флажков, а значением компонента является список выбранных опций.

Например, создадим в XML-дескрипторе экрана компонент:
```
<optionsGroup id="roleTypesField" multiselect="true"/>
```
И в контроллере зададим для него список опций - значения перечисления RoleType:
```
@Inject
protected OptionsGroup roleTypesField;

@Override
public void init(Map<String, Object> params) {
    roleTypesField.setOptionsList(Arrays.asList(RoleType.values()));
}
```
Компонент примет следующий вид:

В данном случае метод getValue() компонента вернет объект типа java.util.List, содержащий значения RoleType.READONLY и RoleType.DENYING.

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

Чтобы программно задать выбор некоторых значений OptionsGroup, нужно передать список значений в формате java.util.List в метод setValue():
```
optionsGroup.setValue(Arrays.asList(RoleType.STANDARD, RoleType.ADMIN));
```

Атрибут orientation задает расположение элементов группы. По умолчанию элементы располагаются по вертикали. Значение horizontal задает горизонтальное расположение.

Атрибуты optionsGroup: align - caption - captionProperty - contextHelpText - contextHelpTextHtmlEnabled - datasource - description - editable - enable - icon - id - multiselect - height - optionsDatasource - optionsEnum - orientation - property - required - requiredMessage - stylename - tabIndex - visible - width
Элементы optionsGroup: validator
API: addValueChangeListener - setContextHelpIconClickHandler - setOptionsEnum - setOptionsList - setOptionsMap