# Меню приложения

Интерфейс главной формы приложения, представленный на следующем скриншоте, включает «Начальную страницу», состоящую из панели разделов и панели навигации. В панели разделов отображаются основные пункты меню 1-го уровня, в панели навигации отображаются дочерние пункты меню 2-го уровня, связанные с модулями. То есть, интерфейсные модули объединяются в разделы; при выделении одного из разделов в панели навигации отображается список модулей раздела. Так, на следующем скриншоте выделен раздел «Справочники»; в панели навигации отображаются пункты меню, связанные со справочной информацией. Представленный подход формирования интерфейса «Начальной страницы» позволяет пользователям в два нажатия открыть нужную форму (модуль) и получить необходимую информацию.

Представленное на «Начальной странице» форма построения меню приложения определяется согласно внешним конфигурационным файлам, которые позволяют не только менять структуру, но и расширять сервисные возможности приложения.

## Файлы конфигурации

Файлы конфигурации приложения располагаются в поддиректории configuration и включают :

- ресурсные файлы главного модуля приложения;
- файл с описанием структуры меню menu-main.xml.

#### Ресурсные файлы

Ресурсы главного меню, согласно принципу локализации, включают несколько файлов, расположенных в поддиректории «configuration/resources/properties». Начальные символы наименования ресурсных файлов соответствует наименования главного модуля приложения (ca-jframe). Суффиксы наименований (_ru, _en, _de и т.д.) соответствуют определенному языку локализации. Ресурсы по умолчанию находятся в файле, имя которого не содержит суффикса, т.е. соответствуют наименованию главного бандла : ca-jframe.properties.

#### Меню приложения

Меню приложения, представленное на «Начальной странице» формируется согласно описанию конфигурационного файла menu-main.xml. XML-формат позволяет создавать многоуровневую структуру описания объекта. В приложение используется двухуровневая структура описания меню. На первом уровне располагаются пункты меню, размещаемые в панели разделов. При выделении одного из разделов, связанные с ним пункты меню 2-го уровня, отображаются в панели навигации в трех колонках.

Интерфейсные модули приложения могут быть открыты в отдельном окне, как, например, модуль О программе, Настройка приложения, либо интегрироваться в интерфейс главной формы в виде вкладок, которые при необходимости можно закрыть.

### Структура menu-main.xml

В листинге представлена структура XML-описания меню 1-го уровня. Секция <menubar> определяет общую структуру меню, которая включает секции <menu> – это и есть пункты меню 1-го уровня. Атрибут «name» определяет наименование пункта меню, которое используется для его локализации. Т.е. по наименованию пункта меню name приложение определяет локализованный текст, отображаемый в интерфейсе. Атрибут «image» определяет наименование файла с изображением, которое отображается рядом с пунктом меню. Файлы изображений располагаются в поддиректории «configuration/resources/images/».

    <?xml version="1.0" encoding="UTF-8"?>
    <menubar name="mainMenu">
        <menu name="menu.storage" image="store.png">
            <!-- пункты меню 2-го уровня -->
        </menu>

        <menu name="menu.references" image="references.png">
            <!-- пункты меню 2-го уровня -->
        </menu>

        <menu name="menu.help" image="help16.png">
            <!-- пункты меню 2-го уровня -->
        </menu>
    </menubar>

### Пункты меню 2-го уровня

Секция <menu> включает теги <menuitem>, атрибуты которой определяют описания пунктов меню 2-го уровня. В таблице представлены атрибуты тега <menuitem> с описанием.

Атрибут | Пример | Описание
--- | --- | ---
name | menu.references.goods | Наименование; ключевое слово (key) для получения локализованного текста пункта меню.
isTitle | true | Флаг выделения шрифта пункта меню. Значение равное 'true' используется для представления подзаголовка синего цвета, bold.
linkable | false | Флаг связи пункта меню с модулем (бандлом). Для интерфейсного модуля/бандла значение должно быть 'true'; кроме этого необходимо указать параметры (groupId, artifactId, version). Подзаголовок имеет значение 'false'.
colNum | 0 | Номер колонки отображения пункта меню; отсчет от 0. Максимальное значение 2, т.е. всего 3 колонки.
guimode | jpanel | Режим представления интерфейса модуля (бандла). При значении равном 'jpanel' интерейс модуля интегрируется в панель вкладок, в противном случае будет представлен отдельным всплывающим окном.
groupId | org.jabricks.about | Групповой идентификатор бандла. В качестве примера приведен groupId бандла «О программе».
artifactId | form-about | Артифакт бандла. В качестве примера приведен artifactId бандла «О программе».
version | 1.0.0 | Версия бандла. Приложение позволяет использовать одинаковые бандлы разных версий.
visible | true | Флаг видимости. При значении равным false пункт меню не отображается.
help | journal-tasks.html | Наименование HTML-страницы документации, расположенной в поддиректории /doc.

На заметку.
1. По умолчанию значение флага visible равно true; его можно не включать в список атрибутов. При значении равным false, пункт меню не отображается в панели Навигации. Если подзаголовок (isTitle=true) не содержит дочерних записей, то он также не отображается в панели Навигации.
2. Если параллельно может работать несколько пользователей, то целесообразно использовать общую систему безопасности, в которой доступ пользователей к информации и видимость пунктов панелей Разделов и Навигации определяется централизованно.

## Примеры пунктов меню 2-го уровня

Согласно атрибутам тега menuitem структура описания меню может включать пункты, отличные по назначению. Ниже приводятся 4 варианта использования menuitem.

#### Связь с модулем

В следующем примере приводятся описания двух пунктов меню для открытия интерфейсов модулей ( Скидки, Наценки) в контейнере главного фрейма в виде вкладок, и пункта меню открытия формы «О программе» в отдельном окне. Значение атрибута guimode, равное jpanel, указывает главному фрейму на необходимость использования своего контейнера (панели вкладок) для размещения интерфейса. Значения атрибутов groupId, artifactId и version определяют параметры модуля/бандла. Приложение позволяет подключать одновременно модули разных версий.

    <!-- модуль Скидки -->
    <menuitem name="menu.references.discounts" guimode="jpanel"
              groupId="org.jabricks.ca" artifactId="list-discounts" version="1.0.0" />
    <!-- модуль Наценки -->
    <menuitem name="menu.references.markups" guimode="jpanel"
              groupId="org.jabricks.ca" artifactId="list-markups" version="1.0.0" />
    <!-- модуль О программе -->
    <menuitem name="menu.about"
              groupId="org.jabricks.about" artifactId="form-about" version="1.0.1" />

#### Подзаголовок

Для выделения пункта меню в виде подзаголовка используются атрибуты isTitle с логическим значение «true» и colNum с номером колонки (отсчет от нуля, максимальное значение 2). В атрибуте name определяется ключ к ресурсному тексту заголовка. Атрибут linkable со значением "false" исключает представление пункта меню в качестве ссылки; т.е. при наведении на пункт меню курсора мыши его вид и вид текста не изменяется.

      <menuitem name="menu.help.references" isTitle="true" linkable="false" colNum="1" />

#### Справка

Чтобы из меню открывать страницы в браузере необходимо в теге menuitem использовать атрибут help, значением которого определить HTML-страницу.

      <menuitem name="menu.references.okato" help="list-okato.html" />

#### Разделитель

Пункты меню в одной колонке можно отделить друг от друга по вертикали пробелом. Для этого наименованию пункта меню присваивается значение "separator".

      <menuitem name="separator"/>

## Пример описания раздела меню

Ниже в свернутом виде представлен листинг описания раздела меню Справочники.

| Листинг раздела Справочники

    <menu name="menu.references" image="references.png">
        <menu name="menu.references.goods"  fontBold="true" linkable="false" colNum="0">
            <menuitem name="menu.references.list.products" guimode="jpanel"
                      groupId="org.jabricks.ca" artifactId="list-products" version="1.0.0" />
            <menuitem name="menu.references.list.nomenclatures" guimode="jpanel"
                      groupId="org.jabricks.ca" artifactId="list-nomenclatures" version="1.0.0" />
            <menuitem name="menu.references.list.nomenclatures.specification" guimode="jpanel"
                      groupId="org.jabricks.ca" artifactId="list-complete-sets" version="1.0.0" />
            <menuitem name="menu.references.packagings" guimode="jpanel"
                      groupId="org.jabricks.ca" artifactId="list-packagings" version="1.0.0" />
            <menuitem name="menu.references.measures" guimode="jpanel"
                      groupId="org.jabricks.ca" artifactId="list-measures" version="3.0.3" />
        </menu>

        <menu name="menu.references.prices.policy" fontBold="true" linkable="false" colNum="1">
            <menuitem name="menu.references.price-types" guimode="jpanel"
                      groupId="org.jabricks.ca" artifactId="list-price-types" version="1.0.0" />
            <menuitem name="menu.references.discounts" guimode="jpanel"
                      groupId="org.jabricks.ca" artifactId="list-discounts" version="1.0.0" />
            <menuitem name="menu.references.markups" guimode="jpanel"
                      groupId="org.jabricks.ca" artifactId="list-markups" version="1.0.0" />

            <menuitem name="separator"/>

            <menuitem name="menu.references.rounding" guimode="jpanel"
                      groupId="org.jabricks.ca" artifactId="list-roundings" version="1.0.0" />
        </menu>
        <menu name="menu.references.documentation" fontBold="true" linkable="false" colNum="1">
            <menuitem name="menu.references.trade.documents" guimode="jpanel"
                      groupId="org.jabricks.ca" artifactId="list-trade-documents" version="1.0.0" />
            <menuitem name="menu.references.trading.operations" guimode="jpanel"
                      groupId="org.jabricks.ca" artifactId="list-trading-operations" version="1.0.0" />
            <menuitem name="menu.references.commodity.operations" guimode="jpanel"
                      groupId="org.jabricks.ca" artifactId="list-commodity-operations" version="1.0.0" />

            <menuitem name="separator"/>

            <menuitem name="menu.references.vat.rates" guimode="jpanel"
                      groupId="org.jabricks.ca" artifactId="list-vat-rates" version="1.0.0" />
            <menuitem name="menu.references.vat.documents" guimode="jpanel"
                     groupId="org.jabricks.ca" artifactId="list-vat-documents" version="1.0.0" />

            <menuitem name="separator"/>

            <menuitem name="menu.references.payment.states" guimode="jpanel"
                     groupId="org.jabricks.ca" artifactId="list-payment-state" version="1.0.0" />
            <menuitem name="menu.references.order.states" guimode="jpanel"
                     groupId="org.jabricks.ca" artifactId="list-order-state" version="1.0.0" />
            <menuitem name="menu.references.payment.docs" guimode="jpanel"
                     groupId="org.jabricks.ca" artifactId="list-payment-docs" version="1.0.0" />
            <menuitem name="menu.references.payment.forms" guimode="jpanel"
                     groupId="org.jabricks.ca" artifactId="list-payment-forms" version="1.0.0" />
        </menu>

        <menu name="menu.references.classifiers" fontBold="true" linkable="false" colNum="2">
            <menuitem name="menu.references.okcm" guimode="jpanel"
                      groupId="org.jabricks.ca" artifactId="list-okcm" version="1.0.0" />
            <menuitem name="menu.references.okato" guimode="jpanel"
                      groupId="org.jabricks.ca" artifactId="list-okato" version="1.0.0" />
            <menuitem name="menu.references.okolf" guimode="jpanel"
                      groupId="org.jabricks.ca" artifactId="list-okolf" version="1.0.0" />
            <menuitem name="menu.references.okw" guimode="jpanel"
                      groupId="org.jabricks.ca" artifactId="list-okw" version="1.0.0" />
            <menuitem name="menu.references.okfc" guimode="jpanel"
                      groupId="org.jabricks.ca" artifactId="list-okfc" version="1.0.0" />
            <menuitem name="menu.references.okpdtr" guimode="jpanel"
                      groupId="org.jabricks.ca" artifactId="list-okpdtr" version="1.0.0" />
        </menu>
    </menu>