Введение

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

CUBA Studio основана на платформе IntelliJ IDEA Platform с открытым исходным кодом и дополняет её функциональность следующими возможностями, специфичными для платформы:

  • Автоматическая генерация скриптов сборки Gradle.

  • Генерация модели данных, схемы БД и CRUD UI.

  • Визуальный WYSIWYG-дизайнер компоновки экрана.

  • Удобные приёмы и функции интерфейса, которые упрощают и ускоряют процесс кодирования: действия (actions), подсказки (intentions), проверки (inspections), внутренние ссылки (references).

  • Простые средства для интернационализации приложений.

  • Создание модели данных и экранов UI поверх существующей (legacy) базы данных.

  • Hot (re)deploy - мгновенное отображение сделанных в проекте изменений в работающем приложении без необходимости перезапускать сервер.

  • Удобная миграция на более новые версии платформы и дополнений (Add-ons).

Release Notes

Версия 11
  1. Добавлен экран "CUBA Add-ons", позволяющий управлять аддонами, подключенными к вашему проекту. Экран можно открыть двойным кликом по ProjectAdd-ons в дереве проекта CUBA, или через главное меню: CUBAMarketplace. Детальное описание экрана находится в соответствующем разделе.

    addons market small
  2. Добавлен экран приветствия. Он предоставляет быстрый доступ к общим настройкам проекта и типовым действиям, содержит ссылки на страницы документации и сообщества.

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

  4. Дизайнер сущностей переработан с использованием UI компонентов платформы IntelliJ. У нового дизайнера следующие преимущества:

    1. Более отзывчивый интерфейс, быстрее скорость открытия

    2. Изменения свойств сущности и ее атрибутов немедленно применяются к исходному коду

    3. Интеграция с рефакторингами IntelliJ, такими как Safe Delete атрибутов сущности

      v 11 entity designer
  5. Реализован рефакторинг Safe Delete атрибутов сущности. Чтобы запустить этот рефакторинг, удалите атрибут через дизайнер сущности или выберите пункт RefactorSafe Delete…​ в контекстном меню, открывающемся при правом клике мыши по определению атрибута. Этот рефакторинг находит использования атрибута в представлениях, экранах и других конфигурационных файлах. Он автоматически удаляет те использования, которые удаляются безопасно, и предупреждает о тех использованиях в коде, которые потребуют ручного исправления.

    v 11 safe delete attr
  6. Настройки хранилищ данных были вынесены из экрана Project Properties. Теперь эти настройки отображаются и редактируются в секции Data Stores дерева проекта CUBA. Настройки основного хранилища также можно открыть через главное меню: CUBAMain Data Store Settings. Подробное описание находится в главе Управление хранилищами данных.

  7. Добавлена поддержка HSQLDB InMemory как дополнительного хранилища данных.

  8. Добавлена поддержка MariaDB как основного или дополнительного хранилища данных.

  9. Добавлена поддержка Amazon Redshift как дополнительного хранилища данных.

  10. Действие Add attribute добавлено на панель действий в редакторе кода сущностей.

    v 11 add attr
  11. На панель действий в редакторе кода сущностей добавлены действия по работе со слушателями события EntityChangedEvent. Они позволяют сгенерировать новый слушатель или перейти к уже существующим методам-слушателям.

    v 11 entity changed action panel
  12. Улучшен диалог генерации кода Create CUBA EntityChangedEvent Listener. Теперь он позволяет сгенерировать несколько методов-слушателей в одном классе, также можно выбрать две дополнительные фазы события.

    v 11 new entity changed dialog
  13. В дизайнер сущностей добавлена поддержка новых аннотаций BeanValidation 2.0: @NotEmpty, @Positive, @PastOrPresent и др.

  14. Теперь при добавлении новых атрибутов к сущности, дизайнер сущностей автоматически распознаёт атрибут с именем, которое можно отображать как имя экземпляра (name, caption, title и т.д.) и генерирует аннотацию @NamePattern , если она еще не создана.

  15. В дизайнер представлений добавлена функция, позволяющая переименовать уже существующеее представление (view) и заменить его использования в коде.

  16. Действие Quick fix-а Inject 'xxx', который позволяет инжектировать Spring-бин по названию переменной, было расширено, и теперь он срабатывает как в коде контроллеров экранов, так и в коде Spring-бинов. Ниже представлен пример, как воспользоваться этим quick fix:

    v 11 inject before
    v 11 inject after

    Чтобы воспользоваться этой функцией, наберите название переменной интересующего бина в коде Spring-бина или контроллера экрана. Затем нажмите Alt+Enter и выберите в выпадающем списке вариант Inject 'beanName'. Название класса бина определяется автоматически на основании имени переменной, которое должно точно соответствовать имени интерфейса (класса) бина. Например: названия переменных dataManager, fileStorageService, messageBundle и clusterManagerAPI будут распознаны и успешно инжектированы как соответствующие бины CUBA.

  17. Добавлена инспекция Java кода, проверяющая что локализованные сообщения, на которые указывают вызовы методов getMessage и formatMessage, существуют.

    v 11 message quick fix

    Проверяются вызовы методов getMessage и formatMessage классов MessageBundle, Messages и AbstractWindow. Если сообщение с данным ключом в данном пакете сообщений отсутствует, то ключ сообщения подсвечивается красным цветом.

    Если нажать Alt+Enter и выбрать quick fix Create message in the message bundle, то Studio откроет диалог Localization Message, чтобы можно было задать локализованные сообщения для всех локалей, настроенных в проекте.

  18. Версия Studio, устанавливаемая как отдельная IDE, обновлена до платформы IntelliJ Community 2019.1. Если у вас уже была установлена отдельная Studio IDE, то она не будет обновлена; вам следует скачать новую версию с сайта CUBA Platform.

  19. Плагин CUBA для IntelliJ IDEA, содержащий данный релиз Studio, загружен в основной (Stable) канал плагинов. Поэтому настраивать дополнительный репозиторий плагинов больше не требуется. Если вы использовали предыдущие версии плагина CUBA Studio, то вы можете удалить репозиторий https://plugins.jetbrains.com/plugins/haulmont/list из списка Custom Plugin Repositories. Список сторонних репозиториев настраивается здесь: FileSettingsPlugins → значок "шестеренка" → Manage Plugin Repositories.

  20. Небольшие улучшения и исправления:

Версия 10
  1. В редакторы кода сущностей, контроллеров и дескрипторов экранов добавлена панель, предоставляющая быстрый доступ к относящимся к CUBA действиям и позволяющая переходить к связанным файлам. Например, так выглядит панель в редакторе класса сущности:

    v 10 actions panel

    Используя кнопки панели, можно быстро перейти к DDL-скриптам данной сущности, представлениям и экранам. Кроме того, можно создавать новые представления, экраны и методы обратного вызова JPA.

    Действия также продублированы в контекстном меню "intentions", которое вызывается нажатием Alt+Enter (Option+Enter):

    v 10 actions menu
  2. Реализована генерация кода слушателей EntityChangedEvent. Для ее запуска выберите в дереве проекта CUBA класс сущности, пакет или узел верхнего уровня Middleware, и щелкните в контекстном меню пункт New > EntityChangedEvent Listener. Studio создаст в модуле core Spring-бин с двумя методами-слушателями: один будет вызываться до коммита транзакции, второй после коммита.

  3. Реализована генерация кода JMX-бинов. Для ее запуска выберите в дереве проекта CUBA узел Middleware, или один из пакетов в узле Beans, и щелкните в контекстном меню пункт New > JMX Bean.

  4. Реализована генерация кода конфигурационных интерфейсов. Для ее запуска выберите в дереве проекта CUBA узел Project > Config Interfaces и щелкните в контекстном меню пункт New > Configuration Interface.

  5. Диалог Inject теперь содержит раздел Project Beans, который позволяет инжектировать все Spring-бины, доступные в проекте.

  6. Диалог Inject теперь работает и в контроллерах экранов, написанных на Groovy.

  7. Усовершенствовано поведение системы при инжектировании: если поместить курсор внутри метода и вызвать диалог Inject, то результирующее поле будет сгенерировано вверху определения класса, и имя поля будет автоматически скопировано в позицию курсора.

  8. На XML-элементах компонентов экранов доступна подсказка (intention) Inject component into controller. Она вызывается нажатием Alt+Enter (Option+Enter) когда курсор находится на XML-элементе компонента.

  9. Реализован визуальный дизайнер индексов и ограничений уникальности для сущностей. См. вкладку Indexes внизу редактора сущности.

  10. Реализованы проверки (inspections) дубликатов имен сущностей и таблиц базы данных. Они отображаются как предупреждения в классе сущности, если в проекте присутствует сущность с таким же именем или таким же именем таблицы.

  11. Реализованы подсказки (intentions) для добавления корректных JPA-аннотаций полям сущностей. Они упрощают ручное кодирование атрибутов сущностей: достаточно добавить поле в класс, сгенерировать getters/setters и затем нажать Alt+Enter (Option+Enter) на поле для генерации аннотаций.

  12. В коде контроллера экрана выдается предупреждение, если инжектирован компонент, не объявленный в XML-дескрипторе:

    v 10 warn nonexisting
  13. В коде класса сущности выдается предупреждение, если у класса нет аннотации @NamePattern:

    v 10 warn namepattern

    Проблему можно исправить, или подавить предупреждение, нажав Alt+Enter (Option+Enter) на имени класса.

  14. Редактор представлений теперь имеет компоновку master-detail со списком представлений слева и выбранным представлением справа.

  15. Для проектов, основанных на CUBA 7.1 и выше, реализованы следующие возможности:

    1. Шаблоны главного экрана с side menu и responsive side menu.

    2. Поддержка передачи свойств в экраны и фрагменты, открываемые декларативно.

    3. Поддержка аддона REST API.

  16. Все завершенные задачи:

Версия 9
  1. BREAKING CHANGE: Studio теперь включает HSQL версии 2.4.1. При первом открытии проекта, использующего базу данных HSQL, Studio предлагает обновить версию HSQL в файле build.gradle проекта. После обновления, проект будет корректно работать в Studio версии 9+. Однако, имейте в виду следующие возможные проблемы:

    1. Приложение не сможет стартовать, если проект с новым драйвером HSQL будет открыт в предыдущей версии Studio, содержащей старый сервер HSQL;

    2. В проектах с HSQL на базе CUBA версии ниже 7.1, Scheduled Tasks не работают, так как их таблица содержит колонку с именем PERIOD, которое является зарезервированным словом в HSQL 2.4.1. Колонка переименована в CUBA 7.1.

      Tip

      Если вы используете CUBA 7.0 или ниже, и вам нужно работать с HSQL и Scheduled Tasks во время разработки, вы можете заставить Studio использовать HSQL 2.2.9 следующим образом:

      1. Закройте Studio.

      2. Скопируйте каталог cuba-studio:

        • на Windows из C:\Program Files\Haulmont\CUBA Studio 2018.3\plugins\ в %userprofile%\.CubaStudio2018.3\config\plugins\

        • на macOS из /Applications/CUBA Studio.app/Contents/plugins/ в ~/Library/Application Support/CubaStudio2018.3/

      3. Замените в скопированном каталоге cuba-studio/lib файл hsqldb-2.4.1.jar файлом hsqldb-2.2.9.jar. Его можно загрузить отсюда.

      4. Запустите Studio и откройте проект.

      5. Замените строку def hsql = 'org.hsqldb:hsqldb:2.4.1' на def hsql = 'org.hsqldb:hsqldb:2.2.9' в файле build.gradle.

      Теперь и Studio, и ваш проект будут использовать HSQL 2.2.9, так что приложение на CUBA 7.0 или ниже сможет работать с Scheduled Tasks на базе данных HSQL.

  2. Механизм Hot deploy теперь деплоит все зависимые классы вместе с измененным, что исключает ClassCastException при открытии измененных экранов.

  3. При выборе базы данных MySQL или Oracle, Studio отображает диалог, из которого можно перейти по ссылке на сайт поставщика для загрузки драйвера, а затем загрузить его из локальной файловой системы в нужный каталог проекта в саму Studio. После загрузки драйвера перезапустите Studio.

    Драйверы могут быть удалены из Studio с помощью страницы настроек CUBA > Database Proprietary Drivers.

  4. Для шаблонов browser и master-detail мастера Create CUBA Screen можно выбрать компоненты DataGrid или TreeDataGrid.

  5. В мастер Create CUBA Screen добавлены шаблоны Extend an existing screen и Entity fragment.

  6. Действия Undo/Redo теперь корректно работают в дизайнере экранов.

  7. Реализовано автодополнение для запросов загрузчиков данных в дизайнере экранов.

  8. В дизайнер экранов добавлена кнопка для быстрого переключения на контроллер, см. верхний правый угол холста.

  9. Добавлены предупреждения об использовании атрибутов invoke и datasource в экранах основанных на новом API.

  10. Если поддержка Groovy выбрана в окне Project Properties, Groovy может быть выбран в поле Advanced > Controller language мастера Create CUBA Screen.

  11. Сервисы, написанные на Groovy, отображаются в дереве проекта CUBA.

  12. Добавлено оповещение о доступности новых версий платформы при открытии проекта.

  13. Улучшены gutter icons в редакторе исходного кода.

  14. Тип атрибута сущности может быть произвольно изменен в дизайнере сущности с запуском рефакторинга или без него.

  15. Реализован дизайнер Enumeration.

  16. Дизайнер представлений переписан на нативный IntelliJ UI.

  17. Генератор модели данных теперь содержит шаблоны экранов с новым API.

  18. Все завершенные задачи:

Версия 8
  1. Первое открытие проекта теперь выполняется с помощью мастера импорта проектов. См. Открытие существующего проекта для подробной информации.

  2. Модель проекта теперь сохраняется в файле внутри каталога .idea проекта, поэтому синхронизация Gradle не запускается каждый раз при открытии проекта.

  3. Редактор Run/Debug Configuration теперь позволяет выбрать JDK, который должен использоваться для запуска сервера приложения: см. поле JVM на вкладке Configuration. По умолчанию используется значение переменной окружения JAVA_HOME.

  4. Представления (views) можно переименовывать с помощью стандартного действия Refactor > Rename. Это действие можно вызвать в дереве проекта CUBA, на атрибуте name XML-элемента view в файле views.xml, а также на любой ссылке на представление в XML-дескрипторах экранов.

  5. Редактор представления можно вызвать из поля view контейнера данных в дизайнере экрана.

  6. Реализовано автодополнение и поиск ссылок для атрибута screen XML-элемента <fragment> в дескрипторах экранов.

  7. Реализован редактор локализованных сообщений для заголовков меню. Щелкните Generic UI > Web Menu в дереве проекта CUBA, переключитесь на вкладку Structure, выберите пункт меню и нажмите edit в поле Caption.

  8. Реализовано предупреждение для значений перечислений, не имеющих локализованных заголовков. Если вы увидели предупреждение, используйте quick fix Create message in the message bundle для создания заголовка по умолчанию.

  9. Реализовано автодополнение для имен свойств приложения, декларированных в конфигурационных интерфейсах. Нажмите Ctrl+Space при задании свойства в файлах app.properties или web-app.properties.

  10. Все завершенные задачи:

Версия 7
  1. Если ваш проект базируется на CUBA 6.10 и использует премиум-дополнения BPM, Charts, Full-Text Search или Reports, необходимо установить имя и пароль доступа к репозиторию в файле ~/.gradle/gradle.properties, как описано в Руководстве по разработке приложений. Studio не передает имя и пароль доступа к репозиторию в Gradle.

  2. Все завершенные задачи:

1. Установка

Перед установкой CUBA Studio убедитесь, что на вашей рабочей машине установлено и настроено необходимое программное обеспечение, описанное в разделе Установка и настройка основного Руководства по разработке.

CUBA Studio можно установить в двух различных формах: как отдельную IDE для вашей операционной системы, или как плагин для имеющейся IntelliJ IDEA. Отдельная IDE представляет собой специальную сборку IntelliJ IDEA Community Edition, включающую в себя плагин CUBA. Если вы ранее не использовали IntelliJ IDEA, мы рекомендуем установить Studio как отдельную IDE.

IDE имеет версию, соответствующую используемой версии IntelliJ IDEA, например 2019.1. Плагин CUBA имеет свою собственную версию, начинающуюся с 11.

Установочные файлы IDE для Windows, macOS и Linux доступны по адресу https://www.cuba-platform.ru/download. Плагин доступен в репозитории плагинов IntelliJ (см. ниже).

Установка на Windows
  1. Скачайте программу установки cuba-studio-VERSION.exe.

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

  3. Запустите установленное приложение и см. ниже для дальнейших инструкций.

Установка на macOS
  1. Скачайте программу установки cuba-studio-VERSION.dmg.

  2. Дважды щёлкните на программы установки, затем перетащите файл CUBA Studio.app в каталог Applications. Если на вашем компьютере установлена более старая версия Studio, которую вы хотели бы сохранить, выберите Keep Both в появившемся диалоговом окне.

  3. Запустите приложение CUBA Studio и см. ниже для дальнейших инструкций.

Установка на Linux
  1. Установите необходимые зависимости:

    $ sudo apt-get install libgconf-2-4
  2. Скачайте архив cuba-studio-VERSION.tar.gz.

  3. Перенесите архив в подходящий каталог, например, ~/lib, и распакуйте его:

    $ tar -xvf cuba-studio-VERSION.tar.gz
  4. Перейдите в подкаталог bin и запустите приложение:

    $ cd ~/lib/cuba-studio-VERSION/bin
    $ ./cuba-studio.sh
Первый запуск IDE

При первом запуске CUBA Studio IDE вам необходимо ответить на несколько вопросов:

  • В первом диалоге Complete Installation, выберите Do not import settings и нажмите OK.

  • В следующем диалоге Customize CUBA Studio, щелкните Skip Remaining and Set Defaults чтобы применить параметры по умолчанию. Вы сможете изменить их в любое время позже.

  • Далее см. раздел Приступая к работе для информации о том как создать новый или открыть существующий проект.

Установка плагина для IntelliJ IDEA
  1. Запустите IntelliJ IDEA 2018.3 или более новую версию.

  2. Откройте диалог Plugins.

  3. Переключитесь на вкладку Marketplace.

  4. Введите "CUBA" в поле поиска. Вы увидите плагин CUBA в результатах поиска.

  5. Нажмите Install и следуйте инструкциям IDE.

2. Обновление

Обновление IDE

Вы можете просто загрузить новую версию Studio IDE с веб-сайта и установить ее поверх имеющейся версии. Все настройки будут сохранены.

Вместо загрузки и инсталляции IDE целиком, можно настроить автоматическое обновление плагина CUBA из репозитория плагинов:

  1. Откройте диалог Plugins.

  2. Переключитесь на вкладку Updates.

  3. Если есть доступные обновления, вы увидите их в списке. Нажмите Update для плагина CUBA, и IDE загрузит новую версию.

  4. После завершения процесса загрузки необходимо перезапустить IDE для применения новой версии плагина.

Обновление плагина в IntelliJ IDEA
  1. Выберите Help > Check for Update на Windows и Linux, или IntelliJ IDEA > Check for Updates на macOS.

  2. Если есть доступные обновления, вы увидите их в списке. Выберите плагин CUBA и нажмите Update. IDE загрузит новую версию.

  3. После завершения процесса загрузки необходимо перезапустить IDE для применения новой версии плагина.

3. Приступая к работе

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

3.1. Создание нового проекта

С помощью CUBA Studio легко создавать приложения на платформе с нуля. Запустите мастер New Project и выполняйте шаги, описанные ниже:

  1. В окне Welcome to CUBA Studio выберите Create New Project.

  2. Выберите CUBA Project.

  3. В поле Project SDK выберите JDK, соответствующий переменной окружения JAVA_HOME, установленной в вашей операционной системе. Если вы видите значение <No SDK>, то нажмите New и выберите каталог установки нужного JDK, например C:\Java\jdk8u202-b08 на Windows или /Library/Java/JavaVirtualMachines/jdk8u202-b08/Contents/Home на macOS.

  4. Вы можете принять настройки доступа к репозиториям платформы по умолчанию или изменить их для конкретного проекта. Затем нажмите Next.

  5. Введите имя нового проекта в поле Project name. Имя должно содержать только латинские буквы, цифры и знак подчеркивания. Тщательно продумайте имя проекта на данном этапе, так как в дальнейшем изменить его будет достаточно сложно.

  6. В полях ниже автоматически сгенерируются:

    • Project location – путь к каталогу нового проекта. Путь можно изменить, введя адрес каталога вручную или нажав на кнопку с многоточием рядом с полем.

    • Project namespace – пространство имен, которое будет использоваться как префикс имен сущностей и таблиц базы данных. Пространство имен может состоять только из латинских букв и должно быть как можно короче.

    • Root package − корневой (или основной) пакет Java-классов проекта. Может быть скорректирован позже, однако сгенерированные на этапе создания классы перемещены не будут.

    • Platform version – используемая в проекте версия платформы. Если у вас нет особых требований, выбирайте последнюю релизную версию, т.е. с номером без суффиксов BETA или SNAPSHOT. Артефакты платформы будут автоматически загружены из репозитория при сборке проекта.

  7. Нажмите Finish. В указанном каталоге будет создан пустой проект, и в главном окне Studio начнётся сборка проекта по скриптам Gradle и индексирование файлов проекта.

  8. После окончания процессов синхронизации и индексации вы увидите дерево проекта CUBA в боковой панели Project.

  9. Откройте боковую панель Gradle, которая по умолчанию находится справа. Щелкните по значку "гаечный ключ" (Gradle Settings) и выберите Use JAVA_HOME в поле Gradle JVM. Если вы не видите такого пункта в выпадающем списке, убедитесь, что вы правильно настроили окружение согласно инструкции в разделе Установка и настройка руководства по разработке приложений. Нажмите OK.

  10. Теперь можно начинать работу с проектом.

3.2. Открытие существующего проекта

Открытие уже импортированного проекта

Если проект ранее уже был открыт в CUBA Studio на данном компьютере, достаточно сделать следующее:

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

  2. Дождитесь завершения синхронизации Gradle и индексации файлов проекта. Когда откроется дерево проекта CUBA в окне инструментов Project, можно начинать работу с проектом.

Первое открытие проекта

Если проект ранее не был открыт в CUBA Studio на данном компьютере (например, вы только что импортировали его из VCS), необходимо сделать следующее:

  1. В окне Welcome нажмите Import Project. Если какой-либо проект уже открыт, то выберите File > New > Project from Existing Sources в главном меню.

  2. В диалоговом окне файловой системы выберите корневую папку проекта, содержащую файл build.gradle, и нажмите на кнопку Open.

  3. В окне Import Project выберите переключатель Import project from external model и пункт CUBA в списке ниже, затем нажмите Next.

  4. На следующей странице мастера импорта просто нажмите Finish.

  5. Дождитесь завершения синхронизации Gradle и индексации файлов проекта. В окне инструментов Project должно появиться дерево проекта CUBA.

  6. Выберите File > Project Structure в главном меню.

    • Убедитесь, что поле Project SDK имеет значение, соответствующее переменной окружения JAVA_HOME установленной в вашей операционной системе. Если вы видите значение <No SDK>, то нажмите New и выберите каталог установки нужного JDK, например C:\Java\jdk8u202-b08 на Windows или /Library/Java/JavaVirtualMachines/jdk8u202-b08/Contents/Home на macOS.

    • Убедитесь, что поле Project language level имеет значение, соответствующее версии выбранного JDK. Например, если JDK версии 1.8, то уровень языка должен быть 8 - Lambdas, type annotations, etc.

Первое открытие проекта на платформе CUBA версии 6.10

CUBA Studio поддерживает работу с проектами, использующими версии платформы 6.10+ и 7.0. Вы можете открыть проект, созданный в предыдущей версии Studio, и импортировать его в новую Studio.

Имейте в виду, что CUBA 6 поддерживает только Java 8, поэтому ваша переменная JAVA_HOME должна указывать на каталог установки JDK 8. Позже, после миграции на CUBA 7, вы сможете выбрать более новый JDK, если это необходимо.

Выполните следующие шаги для первого открытия проекта, использующего CUBA 6.10:

  1. Если ваш проект использует премиум-дополнения (Reports, BPM, etc.) и у вас есть подписка, необходимо прописать имя и пароль доступа к репозиторию в файле ~/.gradle/gradle.properties как описано в документации.

  2. Удалите старые файлы IntelliJ с помощью задачи gradlew cleanIdea в командной строке.

  3. Если проект находится под управлением Git, добавьте строку .idea в файл .gitignore, расположенный в корневом каталоге проекта. Так вы избежите попадания локальных настроек IDE в рабочую среду других разработчиков вашего проекта.

  4. Импортируйте проект как описано выше в секции Первое открытие проекта.

3.3. Обновление проекта

В этом разделе описан процесс обновления проекта до более новой версии платформы.

Tip

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

  • Откройте проект, следуя инструкции в предыдущем разделе.

  • Выберите CUBA > Project Properties в основном меню либо дважды нажмите на Project > Properties в дереве проекта CUBA.

  • В открывшемся окне CUBA Project Properties выберите желаемую версию платформы в поле Platform version.

    Warning

    Если вы используете репозиторий repo.cuba-platform.com, вам будут доступны SNAPSHOT-версии платформы. Мы категорически не рекомендуем использовать эти версии в промышленной эксплуатации.

  • Нажмите OK, затем подтвердите изменения.

  • Если вы обновляетесь до нового feature release (к примеру, с 6.10.X до 7.0.X или с 7.0.Y до 7.1.Y), появится диалоговое окно Migration Required. В этом окне содержится информация об этапах миграции, которые Studio выполнит автоматически. Ознакомьтесь с этой информацией и нажмите Migrate.

  • Studio выполнит автоматическую миграцию (при необходимости) и выполнит задачи Gradle clean и undeploy.

  • Если вы обнрвляетесь до нового feature release, просмотрите раздел Breaking Changes в Release Notes и при необходимости внесите соответствующие изменения в ваш проект.

  • Попробуйте собрать проект, выполнив команду CUBA > Build Tasks > Assemble. Просмотрите журнал вывода и поправьте код, если в логах есть сообщения об ошибках компиляции.

  • Выполните команду CUBA > Update Database, чтобы применить возможные изменения в системных таблицах платформы к базе данных вашего проекта.

3.4. Запуск приложения

Когда Studio импортирует проект CUBA-приложения, автоматически создается Run/Debug Configuration, предназначенная для запуска локального сервера Tomcat. Поэтому для того, чтобы запустить приложение и подключиться к нему отладчиком, достаточно кликнуть на кнопку "debug" рядом с выбранной конфигурацией CUBA Application в главной панели инструментов:

app start 1

Статус запуска отображается во вкладке Console окна инструментов Debug. Для того, чтобы открыть UI приложения в браузере, щелкните по ссылке, выведенной в сообщении Server started at.

app start 2

Вы также можете открыть запущенное приложение в браузере, используя элемент дерева CUBA Runs At…​:

runs at

Для того, чтобы увидеть вывод сервера, переключитесь на вкладку catalina.out:

app start 3

Остановить сервер можно, выбрав команду Run > Stop 'CUBA Application' главного меню, или щелкнув по кнопке в окне инструментов Debug:

app start 4

Рекомендуемый способ запуска приложения при разработке - описанное выше использование Run/Debug Configuration, однако вы также можете управлять локальным сервером Tomcat с помощью команд меню CUBA:

cuba menu appserver

При запуске сервера командой Start Application Server, в Windows вы увидите консольное окно с выводом сервера. В Linux и macOS консоль не отображается, однако логи сервера можно увидеть, выполнив tail -f deploy/tomcat/logs/app.log в окне инструментов Terminal. Команда Stop Application Server останавливает сервер Tomcat, посылая сигнал SHUTDOWN на shutdown port, указанный в свойствах проекта (8005 по умолчанию).

4. Пользовательский интерфейс Studio

В данном разделе описываются элементы пользовательского интерфейса IDE, специфичные для платформы CUBA. Для знакомства с остальными особенностями IntelliJ IDEA рекомендуем обратиться к её документации.

4.1. Дерево проекта CUBA

Дерево проекта CUBA отображает структуру проекта и его важные элементы. По умолчанию оно открывается в окне инструментов Project в левой части IDE. Чтобы переключиться на представление в виде дерева, выполните команду CUBA > Project Tree в главном меню или выберите вариант CUBA в выпадающем списке в верхней части окна инструментов Project.

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

cuba tree
  1. Project

    • Properties - позволяет настроить основные параметры проекта.

    • Add-ons - открывает экран управления аддонами CUBA, используемыми в проекте

    • Build Script - содержит два основных скрипта проекта: build.gradle (определяет конфигурацию сборки) и settings.gradle (задаёт имя проекта и набор модулей).

    • Modules - отображает все модули проекта.

    • Data Stores - отображает и позволяет настраивать список хранилищ данных, подключенных к проекту. По умолчанию здесь отображается единственное хранилище Main.

    • Deployment - позволяет настроить варианты развёртывания проекта.

  2. Data model - отображает модель данных проекта.

  3. Middleware - отображает сервисы и управляемые бины.

  4. Generic UI - включает в себя всё, что относится к пользовательскому интерфейсу проекта: экраны, темы и т.д.

  5. REST API - позволяет настроить функциональность REST API.

  6. Runs At…​ - позволяет открыть запущенное приложение во внешнем или встроенном веб-браузере.

Используйте контекстное меню, открывающееся по щелчку правой кнопки мыши на элементах дерева, чтобы выполнять действия, которые относятся к этим элементам. К примеру, используя контекстное меню элемента Data Model, вы можете генерировать скрипты создания и обновления БД, создавать новые сущности и перечисления:

cuba tree context menu

4.2. Главное меню CUBA

Главное меню CUBA обеспечивает быстрый доступ к CUBA-специфичной функциональности IDE. Некоторые пункты этого меню дублируют функциональность, доступную в дереве проекта и его контекстном меню.

cuba menu

Наиболее часто используемые элементы меню можно добавить на панель инструментов. Для этого необходимо кликнуть на панель и выбрать Customize Menus and Toolbars. В диалоговом окне Menus and Toolbars разверните элемент Main Toolbar и используйте команду Add Action для добавления команд из дерева Main Menu > CUBA.

4.3. Экран приветствия

Экран приветствия открывается в рабочей среде новых проектов после их создания. Его также можно открыть через главное меню: CUBAWelcome.

Этот экран предоставляет быстрый доступ к основным настройкам проекта, типовым действиям, страницам документации и сообщества. Здесь также отображаются версия CUBA, используемая в вашем проекте, версия Studio и сведения о коммерческой подписке.

welcome screen

4.4. Меню настроек CUBA Settings

При выборе элемента CUBA > Settings в главном меню откроется окно настроек IDE, отфильтрованных по слову cuba. Найдите секцию CUBA под секцией Languages & Frameworks.

В секции CUBA содержатся общие настройки, которые распространяются на все проекты, открываемые в данной установленной Studio.

  • Ask before saving DB scripts with DROP statements - предлагать исключить скрипты обновления БД, содержащие команду DROP, из списка скриптов для автоматического выполнения.

  • Show warning if application server port is in use - показывать предупреждение при открытии проекта, если используемый в нём порт Tomcat в данный момент занят.

  • Use embedded browser to open application - если установлен этот флажок, то при двойном клике на секции дерева Runs At запущенное приложение будет открываться во встроенном веб-браузере.

  • Visual designer theme - тема визуальных дизайнеров. Используйте Autodetect, чтобы тема автоматически подстраивалась под тему, выбранную для IDE.

  • Visual designer zoom - масштаб (zoom) визуальных дизайнеров по умолчанию. Масштаб можно настроить и для каждого дизайнера отдельно, используя контекстное меню, открываемое правым щелчком мыши.

  • Old Studio integration enabled - поставьте этот флажок, если вы хотите интегрировать текущий экземпляр IDE со старой Studio SE или Studio Browser Edition. Так вы сможете открывать проекты из старой Studio в этой IDE.

  • Listening port - порт интеграции со старой Studio. Убедитесь, что этот же порт указан в настройках старой Studio в поле IDE Port.

  • Enable transaction block folding - если установлен этот флажок, редактор кода Java свернёт в старом стиле блоки try-finally, использующиеся для контроля транзакций.

Вложенная секция Project settings содержит настройки IDE для текущего открытого проекта. Все настройки, отличные от настроек по умолчанию, сохраняются в файле studio-intellij.xml в корневом каталоге проекта. Этот файл можно добавить в систему контроля версий, чтобы поделиться настройками с другими разработчиками данного проекта.

  • Check compatibility between data model and database scheme - показывать предупреждение при каждом запуске сервера приложения, если текущее состояние модели данных приложения отличается от текущей схемы базы данных.

  • Generate DROP statements in separate update scripts - генерировать более безопасные скрипты обновления БД при удалении сущности и удалении или изменении типа данных её атрибута. Такие скрипты разделены на две части: в первой части скрипта колонка или вся таблица переименовываются в *__UNUSED, а во второй части эти объекты удаляются по-настоящему.

  • Use NVARCHAR when generating scripts for MS SQL Server - если включена эта опция и выбран тип БД Microsoft SQL Server, то для всех строковых атрибутов будет использоваться тип колонки NVARCHAR.

  • Generate script name in format - укажите yyMMddHHmm, чтобы добавлять текущее время к именам генерируемых скриптов обновления базы данных. Это обеспечит правильную последовательность скриптов при совместной работе над проектом.

  • Do not delete columns started with - в этом поле можно указать префикс для колонок таблицы, которые нужно исключить из отслеживания Studio. Если вы добавляете колонку в таблицу, сопоставленную с некой сущностью, и не совмещаете колонку с атрибутом этой сущности, Studio сгенерирует скрипт обновления БД, удаляющий эту колонку. Чтобы избежать удаления, вы можете исключить этот скрипт в диалоговом окне Database Scripts, и он больше не будет сгенерирован. В качестве альтернативы вы можете указать общий префикс для таких колонок в поле Do not delete columns started with и использовать этот префикс в именах колонок. Например, можно ввести NOT_MAPPED_ в указанном поле и назвать колонку NOT_MAPPED_CODE.

  • Column length for enums with ID of String type - в этом поле можно установить длину колонки в БД, которая соответствует атрибуту сущности с типом enum, имеющим строковый идентификатор. К примеру, если вы хотите использовать короткие идентификаторы, состоящие из одного символа, вы можете указать значение 1 в этом поле и тем самым сэкономить место в базе данных.

  • Make plural forms - образовывать формы множественного числа для существительных в соответствии с правилами английской грамматики.

  • Repeat entity parent package for screens - если сущность расположена в дополнительном пакете внутри пакета entity, Studio добавит этот пакет к пути стандартных экранов Generic UI, автоматически генерируемых по шаблонам. Например, если сущность Customer лежит в пакете com.company.sample.entity.crm, пакетом для её экранов по умолчанию будет com.company.sample.web.crm.customer.

  • Use underscores in generated package names - если флажок установлен, слова в именах пакетов будут разделены нижним подчёркиванием в соответствии с camel-регистром в имени соответствующей сущности. К примеру, при генерации экранов для сущности com.company.sample.CustomerGrade, имя пакета будет выглядеть как com.company.sample.customer_grade. Если опция выключена, пакет будет назван com.company.sample.customergrade.

  • Default parent package name for screens - здесь можно указать пакет по умолчанию, который будет использоваться для экранов вместо screens при генерации экранов пользовательского интерфейса, не относящимся к какой-либо сущности. Например, если в этом поле указать значение ui и создать пустой экран по шаблону blank screen, пакетом по умолчанию для этого экрана будет com.company.sample.web.ui.

  • Default access modifier - здесь можно установить модификатор доступа для генерируемых полей сущностей.

  • Generate entity name with underscore symbol - если флажок установлен, имена сущностей будут образованы в формате namespace_ClassName, например, sales_Customer. В противном случае будет использован формат namespace$ClassName.

  • Show module prefix migration dialog - при открытии проекта предлагать миграцию скриптов сборки на новый формат с префиксом модулей, заданным в виде переменной.

  • Instant hot deploy - этот флажок позволяет отключить механизм мгновенного применения изменений (hot deploy). Если hot deploy разрешён, Studio будет динамически обновлять UI уже развёрнутого приложения по мере внесения изменений в представления (views), экраны, пакеты сообщений или главное меню.

  • Hot Deploy Settings - открывает диалоговое окно, в котором можно настроить каталоги hot deployment. Это может быть полезно в случае, если вы захотите добавить, например, каталоги, где размещены файлы HTML и JavaScript модуля web portal вашего проекта. При изменении этих файлов Studio будет копировать их в соответствующие каталоги внутри Tomcat. Таким образом, чтобы увидеть изменения, вам потребуется всего лишь перезагрузить страницу веб-портала.

  • Fold messages in - позволяет контролировать свёртывание сообщений в дескрипторах и контроллерах экрана. Если флажок установлен, ключи сообщений будут заменены на их реальные значения из соответствующих пакетов сообщений.

  • Message folding locale - позволяет указать, сообщения из какого пакета (какой локали) должны быть использованы при свёртывании.

5. Функции и возможности Studio

В этом разделе описаны возможности и особенности Studio, которые позволят вам быстрее и удобнее разрабатывать приложения на платформе. Информация в данном разделе структурирована, по большей части, в соответствии с элементами дерева проекта, которое вы видите в левой части Studio.

Некоторые функции Studio могут пересекаться с отдельными функциями IntelliJ Ultimate Edition или сторонних плагинов. К примеру, чтобы избежать конфликта значков в жёлобе (gutter), необходимо запретить конфликтующие Ultimate-значки. Сделать это можно следующим образом:

  • В меню IDEA выберите Settings > Editor > General > Gutter Icons,

  • Снимите флажки с опций Injection points и Producers for Disposer methods,

  • Сохраните изменения.

5.1. Конфигурация проекта

Здесь описаны средства для настройки конфигурации проекта и управления его инфраструктурой.

5.1.1. Редактор свойств проекта

Окно Project Properties позволяет настроить конфигурацию конкретного проекта. Окно редактора свойств можно открыть из главного меню CUBA или двойным кликом по элементу дерева Project > Properties.

Основные настройки
  • Поле Repositories отображает список репозиториев, используемых в текущем проекте. Studio сканирует эти репозитории и выводит доступные в них версии платформы. Чтобы настроить доступ к репозиторию, используйте кнопки рядом с полем. Более подробно о настройках доступа смотрите в документации. Также вы можете вручную настроить доступ к любому количеству дополнительных репозиториев, содержащих компоненты приложения, зарегистрировав их в файле build.gradle.

  • В поле Platform version можно выбрать желаемую версию платформы. При выборе более новой версии Studio при необходимости осуществит автоматическую миграцию проекта.

  • Флажок Groovy support позволяет использовать код Groovy в приложении: например, в классах контроллеров экранов.

  • Группа App components позволяет выбрать готовые дополнения, поставляемые с платформой, для использования в текущем проекте. Сторонние компоненты приложения настраиваются в отдельном окне CUBA Add-ons.

  • Если необходимо изменить путь к серверу приложений, укажите новый путь в поле Tomcat path. При следующем вызове команды gradlew deploy или gradlew start сервер Tomcat будет установлен в указанный каталог.

  • Группа полей Tomcat ports позволяет указать нестандартные порты для сервера приложений Tomcat, установленного в каталог deploy/tomcat в результате быстрого развёртывания приложения.

  • В частности, поле HTTP port определяет порт, который сервер Tomcat слушает для установки HTTP-соединения, аналогично свойствам приложения cuba.webPort, cuba.webAppUrl, cuba.restApiUrl и cuba.connectionUrlList.

  • В поле AJP port можно указать порт AJP-коннектора.

  • Поле Shutdown port позволяет задать порт, на котором Tomcat будет отслеживать команду SHUTDOWN.

  • Поле Debug port определяет порт, который сервер Tomcat слушает для подключения к отладчику (debugger) Java. После изменения этого порта необходимо также изменить его в настройках отладчика в IDE.

  • В поле Available locales вы можете указать локали, используемые в приложении. Откройте редактор локалей, нажав на кнопку рядом с полем. Флажок Locale select visible в окне редактора управляет свойством приложения cuba.localeSelectVisible. В редакторе также можно определить и переопределить формат строк для распознавания и форматирования дат.

Секция Dependencies

Секция Dependencies отображает и позволяет управлять сторонними зависимостями (библиотеками), подключенными к вашему проекту.

dependencies

Зависимости проекта отображаются в таблице, сгруппированной по модулям в три или более секции, в зависимости от количества модулей в вашем проекте. Если библиотека добавлена к модулю global - она фактически становится доступной во всем проекте, потому что остальные модули CUBA-проекта зависят от модуля global.

Столбец таблицы Type показывает тип зависимости:

  • compile - библиотека используется для компиляции и для запуска приложения

  • provided - для зависимостей, которые необходимы, чтобы скомпилировать ваш код, но не должны присутствовать в runtime classpath (драйверы JDBC, реализация Servlet API и т.д.)

  • runtime - библиотека используется только при запуске приложения

  • testCompile - библиотека используется для компиляции и запуска тестов

  • testRuntime - библиотека используется для тестов, только при их запуске

Столбец Text отображает координаты библиотеки в формате строки зависимости Gradle: "group:name:version".

Действия по управлению зависимостями расположены справа от таблицы Dependencies:

  • Add dependency - добавить новую зависимость к проекту. Укажите XML-объявление зависимости Maven или строку зависимости Gradle. Диалог автоматически проверяет корректность объявления зависимости.

  • Remove dependency - удалить зависимость из проекта.

  • Edit dependency - изменить текст объявления зависимости.

Больше о подключении зависимостей можно прочитать в документации Gradle.

Добавление сторонней библиотеки

Для добавления сторонней зависимости к вашему проекту нужно проделать следующее:

  • Определить XML-объявление зависимости Maven или строку зависимости Gradle для требуемой библиотеки.

newdep gradle
newdep maven
  • Скопировать объявление зависимости в буфер обмена

  • Открыть диалог Project Properties

  • Выбрать модуль, к которому будет добавлена зависимость, или выбрать модуль global, чтобы сделать библиотеку доступной во всём проекте.

  • Нажать кнопку + справа от таблицы Dependencies. Откроется диалог Dependency Editor. Объявление зависимости из буфера обмена будет автоматически скопировано в текстовое поле.

  • Нажать OK в диалоге Dependency Editor. Исправить объявление, если появятся ошибки валидации.

  • Нажать OK в диалоге CUBA Project Properties, чтобы применить изменения. Studio добавит необходимые объявления в скрипт сборки проекта и обновит конфигурацию проекта.

  • Теперь в коде можно использовать классы библиотеки.

Tip

Вид зависимости Gradle implementation 'a.b.c' пока не поддерживается, пожалуйста используйте compile 'a.b.c' вместо него.

5.1.2. Управление аддонами

Аддоны - это публично распространяемые full-stack библиотеки, расширяющие ваш проект дополнительной функциональностью. Дополнительную информацию об аддонах и компонентах приложения можно найти в руководстве по разработке приложений CUBA.

Диалог CUBA Add-ons позволяет управлять аддонами, подключенными к вашему проекту. Его можно открыть:

  • двойным кликом мыши по пункту ProjectAdd-ons в дереве проекта CUBA,

  • из главного меню: CUBAMarketplace…​

Диалог состоит из трёх вкладок: Marketplace, Installed и Updates.

Вкладка Marketplace

Вкладка Marketplace отображает опубликованные и совместимые с вашим проектом аддоны.

addons market small

Аддоны сгруппированы по категориям. Доступен поиск с фильтрацией, например "email" или "category:Translation".

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

addon details

Для установки одного или нескольких аддонов, кликните кнопку Install для интересующих вас аддонов, затем нажмите кнопку Apply или Apply & Close. После подтверждения Studio проделает необходимые изменения в скриптах сборки и конфигурационных файлах вашего проекта, скачает новые библиотеки и обновит конфигурацию проекта Gradle.

Установка аддона по координатам

Координаты аддона - это просто строка зависимости Gradle, например "com.mycompany.cuba-addons:myaddon:0.1.5". Эта строка опубликовывается автором аддона или в каталоге на сайте CUBA platform. Чтобы установить необходимый аддон по координатам (или по строке зависимости Gradle), кликните значок "шестеренка" справа от заголовка вкладки Updates, и выберите пункт Install by coordinates:

addon by coords
Вкладка Installed

Вкладка Installed отображает аддоны, уже подключенные к вашему проекту.

addons installed

Установленные аддоны разделены на две категории. Marketplace Add-Ons - это те, которые установлены из каталога дополнений. Custom Add-Ons - это те, которые разработаны сторонними компаниями и загружены из сторонних репозиториев, в том числе из локального Maven.

Чтобы удалить аддон из вашего проекта, выберите соответствующую строку в списке и нажмите клавишу Delete, или правый клик мыши → Uninstall. Потом кликните Apply в диалоге. Студия удалит аддон из списка зависимостей и обновит конфигурацию проекта.

Вкладка Updates

Studio автоматически проверяет наличие обновлений для аддонов, подключенных к вашему проекту. Вкладка Updates отображает информацию о доступных обновлениях.

addons updates

Чтобы обновить аддон, нажмите кнопку Update, затем кнопку Apply или Apply & Close. Studio обновит версию зависимости, скачает необходимые библиотеки и обновит конфигурацию проекта.

В дополнение к этому, уведомление о доступных обновлениях показывается в правом нижнем углу экрана сразу после открытия проекта:

addon update notification

5.1.3. Управление модулями

Studio позволяет создавать, редактировать и удалять дополнительные модули проекта: core, gui, web, web-toolkit, portal и front. Для управления модулями используйте команды в меню CUBA > Advanced > Manage Modules или в контекстном меню Project > Modules дерева проекта.

В секции Modules дерева проекта отображаются модули, используемые в текущем проекте. При создании нового проекта в нём автоматически создаются модули global, core и web. Для каждого модуля Studio отображает файлы конфигурации, расположенные в этом модуле.

5.1.4. Управление хранилищами данных

Основное хранилище данных

Диалог Main Data Store Properties отображает настройки основного хранилища данных проекта. Его можно открыть:

  • двойным кликом мыши по пункту ProjectData StoresMain Data Store в дереве проекта CUBA

  • через главное меню: CUBAMain Data Store Settings…​

Тип сервера базы данных можно выбрать в поле Database type. В полях ниже вы можете настроить URL подключения к базе данных, указать имя пользователя, пароль и дополнительные параметры подключения.

Формат параметров подключения зависит от типа выбранной СУБД. Строка параметров должна содержать разделитель между именем базы данных и непосредственно параметрами. К примеру, чтобы указать имя экземпляра Microsoft SQL Server 2008+, нужно ввести в поле следующую строку:

;instanceName=myinstance

Нестандартный URL подключения к БД можно указать в случае, если установлен флажок Custom database URL. В этом случае необходимо также указать значения Host и Database, так как в скрипте build.gradle эти значения используются по отдельности.

Если выбрана HSQLDB, Studio сама обеспечит создание и подключение к БД. Созданные файлы БД будут сохранены в каталог build/hsqldb.

Дополнительные хранилища данных

Чтобы создать дополнительное хранилище данных в проекте, кликните правой кнопкой мыши по элементу Data Stores в дереве проекта CUBA и выберите пункт контекстного меню NewAdditional Data Store. Дополнительные хранилища данных, зарегистрированные в проекте, отображаются как подпункты секции Data Stores:

additional stores

Правый клик мыши по пункту дополнительного хранилища открывает контекстное меню:

  • Delete Data Store - удалить хранилище данных из проекта

  • Edit Data Store - открыть диалог редактирования настроек хранилища

  • Generate Model…​ - сгенерировать модель данных по выбранному хранилищу

При создании и редактировании дополнительного хранилища открывается диалоговое окно Data Store. Оно содержит следующие поля:

  • Data store name - имя хранилища данных. Может содержать только буквенно-числовые символы и нижние подчеркивания, а также должно отличаться от имени проекта.

  • Data store type - тип хранилища: RdbmsStore или Custom, более подробно см. в основном Руководстве. В случае, если выбран тип RdbmsStore, необходимо также заполнить следующие поля, описанные ниже.

  • DataSource JNDI name - устанавливается автоматически в Studio на основе имени хранилища.

  • Database type, URL, и т.д. - параметры подключения к БД.

add store settings

5.1.5. Настройки развёртывания

Специальные экраны редакторов Studio помогут вам настроить задачи Gradle для сборки артефактов развёртывания. Эти редакторы можно открыть из главного меню CUBA > Deployment или по двойному клику на элементе дерева Project > Deployment.

Редактор WAR Settings позволяет настроить сборку WAR файлов. После завершения настройки в файле build.gradle будет автоматически создана задача buildWar.

  • Build WAR - установка этого флажка создаст задачу buildWar в файле build.gradle.

  • Include JDBC driver - определяет, нужно ли включать в WAR-файл драйвер JDBC.

  • Include Tomcat’s context.xml - определяет, нужно ли включать в WAR-файл конфигурационный файл context.xml (дескриптор развёртывания Tomcat).

  • Custom context.xml path - путь к дескриптору развёртывания Tomcat context.xml относительно корневого каталога приложения. Поле доступно, если установлен флажок Include Tomcat’s context.xml. Нажмите Generate, чтобы создать этот файл автоматически.

  • Single WAR for Middleware and Web Client - определяет, нужно ли объединять блоки приложения Middleware и Web Client в один единый WAR-файл.

  • Custom web.xml path - файл, который будет использован в качестве собственного web.xml единого WAR-файла. Нажмите Generate, чтобы создать этот файл автоматически.

  • Logback configuration file - путь к конфигурационному файлу logback.xml относительно корневого каталога приложения. Нажмите Generate, чтобы создать этот файл автоматически.

  • App properties - набор свойств приложения, имеющих отношение к этому развёртыванию. Свойства будут добавлены в файл /WEB-INF/local.app.properties внутри WAR.

Редактор UberJAR Settings позволяет настроить сборку Uber JAR. После завершения настройки в файле build.gradle будет автоматически создана задача buildUberJar.

  • Build Uber JAR - установка этого флажка создаст задачу buildUberJar в файле build.gradle.

  • Single Uber JAR - если флажок установлен, задача buildUberJar создаст единый Uber JAR для всех модулей проекта.

  • Logback configuration file - путь к конфигурационному файлу logback.xml относительно корневого каталога приложения. Нажмите Generate, чтобы создать этот файл автоматически.

  • Custom Jetty environment file - путь к конфигурационному файлу jetty-env.xml относительно корневого каталога приложения. Этот файл будет использоваться встроенным сервером Jetty. Поле обязательно к заполнению. Нажмите Generate, чтобы создать этот файл автоматически.

  • App properties - набор свойств приложения, имеющих отношение к этому развёртыванию. Свойства будут добавлены в файл /WEB-INF/local.app.properties внутри Uber JARs.

  • В полях Core port, Web port, Portal port можно настроить порты встроенных серверов для соответствующих блоков приложения. Поле недоступно, если выбрана опция Single Uber JAR. Значения портов по умолчанию описаны в основном руководстве. Кроме того, порты можно указать в качестве аргументов при запуске JAR из командной строки с помощью команды -port.

5.2. Модель данных

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

5.2.1. Операции над сущностями

Создание новой сущности
  1. Выберите элемент Data Model или вложенный в него пакет в дереве проекта и в контекстном меню нажмите New > Entity.

  2. В появившемся окне New CUBA Entity введите имя класса сущности в поле Entity name, выберите тип сущности и её идентификатор.

  3. Studio создаст класс сущности и зарегистрирует его в файле persistence.xml или metadata.xml в зависимости от типа сущности. Созданный класс откроется в редакторе исходного кода, в нижней части которого можно увидеть три вкладки:

    • Text содержит исходный код класса.

    • Designer содержит визуальный дизайнер, который поможет вам настроить сущность и её атрибуты с помощью графического интерфейса, избавив вас от необходимости написания Java-кода вручную.

    • DDL Preview содержит доступный только для чтения DDL-код таблиц сущности и, при необходимости, ограничений по внешнему ключу.

Создание атрибутов сущности

Есть несколько способов добавления атрибутов сущности.

  • С помощью графического интерфейса дизайнера сущности: переключитесь на вкладку Designer, нажмите New под таблицей Attributes и заполните необходимые поля в окне редактора New Attribute.

    Кнопка "глобус" в правой части поля Name поможет сразу же задать удобочитаемое имя атрибута для пользовательского интерфейса. Оно будет храниться в файле messages.properties и использоваться по умолчанию в компонентах UI. Если ваше приложение поддерживает несколько языков, вы также можете задать локализованное имя атрибута для каждого языка.

    attribute l10n
  • В отдельном окне, открываемом из исходного кода класса сущности. Поместите курсор под последним существующим полем класса и нажмите Alt+Insert (Cmd+N). В меню Generate выберите Add Attribute. Studio отобразит окно New Attribute, как если бы оно было открыто из визуального дизайнера. Это же окно откроется, если нажать кнопку Add attribute на панели действий в редакторе исходного кода сущности.

    new attribute 2
  • Вы можете создать поле атрибута и вручную, сгенерировать для него геттер и сеттер, а затем выбирать JPA Annotations в меню Generate, чтобы добавить JPA-аннотации с параметрами по умолчанию.

Studio поможет добавить новые атрибуты к экранам UI, уже созданным для данной сущности. Поместите курсор на строку, в которой описан атрибут, и нажмите Alt+Enter (Option+Enter), или кликните по значку с лампочкой и выберите Add entity attribute to screens:

add attribute to screens

По нажатию клавиши Enter в Studio откроется диалоговое окно со списком экранов, работающих с редактируемой сущностью. Выберите нужные экраны, и Studio сама добавит атрибут к подходящим визуальным компонентам этих экранов, например, к таблице или форме редактирования.

Создание имени экземпляра сущности

Для сущностей, которые будут использоваться в качестве ссылочных атрибутов других сущностей (как, например, Customer может быть атрибутом сущности Order), необходимо задать шаблон для генерации осмысленного имени экземпляра этих сущностей. Этот шаблон задаётся с помощью аннотации @NamePattern класса сущности. Аннотацию можно создать средствами Studio, для этого нужно поместить курсор на название класса, нажать Alt+Enter (Option+Enter) и выбрать Add name pattern (этот пункт доступен только для тех классов, для которых аннотация @NamePattern ещё не задана):

create name pattern

Нажмите Enter, и Studio отобразит список всех имеющихся атрибутов сущности. Выберите один или несколько атрибутов и нажмите Enter, после чего Studio сгенерирует аннотацию @NamePattern над классом сущности.

Создание строк сообщений для новых атрибутов

Когда вы создаёте новые атрибуты вручную, их имена будут подсвечены, чтобы вы не забыли создать удобочитаемые имена атрибутов в соответствующем пакете сообщений:

create message 1

Нажмите Alt+Enter (Option+Enter) на выделенном атрибуте и выберите пункт Create message in the message bundle:

create message
Удаление сущностей

При удалении класса сущности используйте опцию Safe delete для того, чтобы найти и удалить ссылки на данную сущность:

remove entity

Некоторые ссылки, например в файлах persistence.xml и metadata.xml, будут удалены автоматически. При наличии других ссылок, будет показан диалог, в котором они будут перечислены. Нажмите в нем View Usages, просмотрите ссылки в окне инструментов Find и нажмите Cancel или Do Refactor.

5.2.2. Работа с представлениями

Для создания нового представления, или view, выберите сущность в дереве проекта и нажмите New > View в её контекстном меню.

create view

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

  • Entity name - имя сущности, для которой создаётся представление.

  • Name - имя нового представления.

  • Extends - встроенное или собственное представление, чьи атрибуты будет наследовать новое представление. Для любой сущности в платформе определены следующие представления по умолчанию:

    • _local включает в себя все локальные атрибуты сущности, т.е. атрибуты, которые не содержат ссылок на другие сущности,

    • _minimal включает в себя атрибуты, входящие в имя экземпляра сущности и задаваемые аннотацией @NamePattern,

    • _base включает в себя все локальные несистемные атрибуты и атрибуты, заданные в аннотации @NamePattern (т.е. фактически _minimal + _local).

  • Configuration file - файл конфигурации представлений, в котором будет сохранено текущее представление. По умолчанию Studio создаёт единственный файл views.xml в модуле global.

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

Если ваше представление наследует другое представление, все унаследованные атрибуты будут выбраны автоматически, а их чекбоксы будут неактивны.

Когда вы выбираете ссылочный атрибут, в панели справа отобразятся следующие свойства:

  • Entity - имя сущности, на которую указывает ссылка.

  • View - необязательное имя представления, с которым должна быть загружена эта сущность. Мы рекомендуем ссылаться на конкретное представление вместо произвольного набора атрибутов, так вам будет проще поддерживать сложные многоуровневые представления. Кроме того, даже если вы указали имя конкретного представления, вы по-прежнему можете добавить к нему отдельные атрибуты, не включённые в это представление, с помощью чекбоксов в дереве атрибутов.

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

Когда вы нажмёте OK и закроете дизайнер представлений, вы сможете увидеть созданное представление в дереве проекта под сущностью:

create view 2

Двойной клик по представлению в дереве проекта откроет файл конфигурации views.xml и установит курсор на определении этого представления. В нижней части редактора можно увидеть две вкладки: Text и Structure. Последняя отображает список представлений, описанных в этом файле конфигурации.

При редактировании представления в XML-дескрипторе используйте автодополнение имён атрибутов с помощью комбинации Ctrl+Space:

view edit 1

Обратите внимание, если некоторые атрибуты подсвечены: с большой долей вероятности их не существует в данной сущности:

view edit 2

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

  • Выбрав представление в дереве проекта, нажать Edit View в его контекстном меню;

  • Поместив курсов на элемент view в коде файла конфигурации представлений, нажать Alt+Enter (Option+Enter), выбрать Edit view во всплывающем меню и нажать Enter;

  • Переключившись на вкладку Structure в редакторе файла конфигурации представлений, выбрать нужное представление и нажать на кнопку Edit.

5.2.3. Работа с базой данных

Studio умеет создавать DDL-скрипты для создания и поддержания схемы базы данных, соответствующей моделируемым сущностям. Созданные скрипты могут быть выполнены как с помощью Studio, так и прямым вызовом задач Gradle, а также самим приложением при его запуске.

Для того, чтобы создать DDL-скрипты средствами Studio, нажмите CUBA > Generate Database Scripts в главном меню, либо выберите элемент Data Model в дереве проекта и нажмите Generate Database Scripts в его контекстном меню.

Откроется окно Studio Database Scripts, которое содержит следующие вкладки:

Updates

На вкладке Updates отображаются скрипты обновления базы данных для её соответствия текущему состоянию модели данных приложения. Созданные скрипты сохраняются в каталоге modules/core/db/update. Имена скриптов генерируются автоматически и содержат префиксы, которые определяют порядок выполнения скриптов. Скрипты, содержащие команду DROP, подсвечиваются красным.

Вы можете добавить дополнительный скрипт, нажав на кнопку Create, он будет сохранён и позже выполнен вместе с остальными сгенерированными скриптами.

Новые скрипты можно отредактировать или удалить совсем, нажав на кнопку Remove.

Если нажать на кнопку Exclude selected (исключить), вам будут предложены два варианта:

  • Перенести скрипт в папку с исключёнными вручную скриптами: modules/core/db/update-manually. В этом случае скрипт не будет исполнен автоматически при выполнении команды Update database, но вы всегда сможете выполнить его вручную, когда потребуется. Этот вариант удобен для скриптов, удаляющих столбцы и таблицы, ранее переименованные в *__UNUSED.

  • Исключить скрипт: в этом случае он не будет сохранён в папке modules/core/db/update, но будет зафиксирован в файле studio-intellij.xml в каталоге проекта. В следующий раз, когда вы будете генерировать скрипты, Studio проигнорирует изменения, соответствующие исключённым скриптам. Этот вариант позволяет иметь различия между схемой БД и сущностями модели данных приложения.

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

Init Tables

Скрипт Init Tables создаёт все таблицы в базе данных при выполнении команды Create Database. Он выполняется до скриптов Init constraints и Init data. Вы можете редактировать этот скрипт, но обязательно сохраните комментарии, разделяющие таблицы. Скрипт хранится в файле 10.create-db.sql.

Init Constraints

Скрипт Init Constraints служит для создания ограничений целостности. Он выполняется сразу после Init tables. Этот скрипт также можно редактировать, не удаляя комментариев-разделителей. Скрипт хранится в файле 20.create-db.sql.

Init Data

Скрипт Init Data позволяет добавить дополнительную информацию или схему, которой нет в модели данных. Этот скрипт выполняется последним при инициализации БД. Скрипт хранится в файле 30.create-db.sql.

Если проект содержит компоненты приложения (аддоны), для которых нет DDL-скриптов для текущей базы данных, Studio сама создаст скрипты для этих компонентов и отобразит их на вкладках Init {component} tables и Init {component} constraints. Такие скрипты сохраняются в файлах 01.{component}-create-db.sql и 02.{component}-create-db.sql соответственно.

Нажмите Save and close для сохранения сгенерированных скриптов. Теперь вы можете найти их в секции Project > Data Stores > Main Data Store дерева проекта.

Чтобы запустить скрипты обновления, остановите сервер приложения, если он был запущен, и выполните команду Update Database в главном меню CUBA. Если вы хотите заново создать базу данных с нуля с помощью скриптов инициализации, выполните команду Create Database.

5.2.4. Генерация модели данных

Studio позволяет легко создавать модель данных приложения и стандартные экраны UI поверх существующей базы данных. Нажмите CUBA > Advanced > Generate Model в главном меню или выберите Project > Data Stores в дереве проекта и нажмите Generate Model в контекстном меню. Если приложение подключено к нескольким хранилищам данных, выберите один из них в отобразившемся окне Studio.

После этого Studio запустит мастер генерации модели Generate Model from Database.

Шаг 1

Это первый шаг генерации модели данных с помощью мастера.

generate model step1

Дополнительный шаг: вы можете нажать на кнопку Settings, чтобы выбрать пакет Java, в который нужно поместить новые сущности, и настроить сопоставление (mapping) системных атрибутов по умолчанию.

К примеру, если все или большинство таблиц в вашей базе данных содержат столбцы Modified и ModifiedBy, вы можете сопоставить их с атрибутами Updatable.updateTs и Updatable.updatedBy для всех генерируемых сущностей. В этом случае вам не придётся настраивать сопоставление этих атрибутов индивидуально для каждой сущности. Используйте список Exclude columns from mapping, если вы хотите исключить некоторые столбцы из автоматического сопоставления для всех таблиц.

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

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

Чекбокс справа поможет выбрать или снять выбор сразу со всех доступных таблиц.

Нажмите Next.

Шаг 2

На этом шаге вы можете просмотреть и отредактировать сопоставление атрибутов, которое было создано автоматически для выбранных таблиц.

generate model step2

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

  • OK - автоматическое сопоставление прошло успешно, все столбцы полностью отражены в новых сущностях.

  • Join table - связь между сущностями распознана и отражена в виде связанной таблицы many-to-many.

  • There are unmapped columns - некоторые столбцы не могут быть отражены в новых сущностях.

  • New PK will be created - таблица не имеет первичного ключа. Будет создан новый первичный ключ с типом UUID.

  • Composite PK will be replaced - таблица имеет составной первичный ключ, но на него нет ссылок из других таблиц. Составной первичный ключ будет заменён первичным ключом с типом UUID.

  • Composite PK referenced by other tables - таблица имеет составной первичный ключ, на который ссылаются другие таблицы. Studio не может сопоставить такую таблицу.

  • Unsupported PK type - таблица имеет первичный ключ неподдерживаемого типа. Studio не может сопоставить такую таблицу.

  • Choose primary key for DB view - данная таблица является представлением (view), и вы должны выбрать один или несколько столбцов, которые будут использованы в качестве идентификатора сущности. Для этого нажмите кнопку Choose PK и выберите столбцы для первичного ключа.

Кнопка Refresh mapping позволяет заново выполнить автоматическое сопоставление для выбранных таблиц. Таким образом, вы можете, к примеру, внести изменения в схему БД в некоем стороннем клиенте баз данных, а затем вернуться в мастер Studio и перезапустить процедуру сопоставления.

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

generate model step2 2

Кнопка Choose PK появляется вместо кнопки Edit mapping, если выбрано представление (view) базы данных, и требуется отметить столбцы, которые будут использованы в качестве идентификатора сущности.

Нажав Back, вы можете вернуться к предыдущему шагу и изменить список выбранных таблиц.

Нажмите Next, чтобы перейти к следующему шагу.

Шаг 3

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

generate model step3

Если вы снимете флажок Create standard screen, Studio не будет генерировать экраны UI для новых сущностей.

Используйте поля In module, Package и Menu, чтобы указать, где должен быть размещён исходный код создаваемых экранов и в какой части меню приложения они должны отображаться.

Используйте выпадающий список в столбце Standard screens, чтобы выбрать тип создаваемых экранов.

Вы можете спокойно пропустить этот шаг и создать экраны позднее, после завершения генерации модели данных.

Нажмите Next, чтобы перейти к следующему шагу.

Шаг 4

Этот шаг завершает процесс генерации модели данных.

Таблица Import scripts содержит список скриптов, которые необходимо выполнить в базе данных, чтобы сделать её совместимой с создаваемыми сущностями.

До этого этапа никаких изменений не было ни внесено в проект, ни даже сохранено на диск. По факту, Studio выполняет генерацию сущностей и экранов и сохраняет скрипты только после того, как вы нажмёте Run all scripts или Run script.

Вы можете просмотреть и отредактировать скрипты на этой странице, затем выполнить их или просто сохранить, чтобы выполнить позднее в любой отдельной утилите для управления базами данных. Скрипты импорта сохраняются в папку проекта modules/core/db/import.

5.2.5. Поддержка произвольной СУБД

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

Выберите CUBA > Advanced > Define Custom Database в главном меню.

В открывшемся окне можно указать свойства базы данных, с которой вы хотели бы работать. На основе указанных свойств Studio сгенерирует код для поддержки выбранной СУБД как на этапе разработки, так и в готовом приложении.

  • DB type id - идентификатор типа СУБД, который будет использован в качестве значения свойства cuba.dbmsType.

  • DB type name - удобочитаемое имя БД, которое будет отображаться в Studio.

После нажатия OK Studio создаст классы Java в пакете com.haulmont.cuba.core.sys.persistence и классы Groovy в пакете com.haulmont.studio.db.{db_id} вашего проекта. Базовая реализация, сгенерированная в Studio, подходит для использования СУБД Microsoft SQLServer. Вы можете изменить её при необходимости.

Для начала приведите класс com.haulmont.studio.db.{db_id}.{db_id}DbProperties в соответствие с выбранной вами базой данных. После этого вы сможете выбирать эту СУБД в настройках проекта в Studio. Закройте проект и переоткройте его заново, чтобы в списке доступных СУБД появилась нужная.

Чтобы подключиться к новой базе данных из работающего приложения, скорректируйте классы {db_id}DbmsFeatures и {db_id}DbTypeConverter в пакете com.haulmont.cuba.core.sys.persistence. Класс {db_id}SequenceSupport используется только для генерации целочисленных идентификаторов и уникальных чисел.

Наконец, если это необходимо, модифицируйте класс com.haulmont.studio.db.{db_id}.{db_id}DdlGenerator для правильной генерации скриптов init и update в Studio. Пропустите этот шаг, если вы не планируете создавать DDL-скрипты для новой базы данных.

Если вы планируете использовать нестандартную СУБД в качестве основного хранилища данных проекта, сгенерируйте скрипты инициализации и обновления БД, чтобы Studio могла создать init-скрипты для всех компонентов приложения, включая сам фреймворк. Эти скрипты не включают в себя некоторые данные, необходимые для инициализации БД, поэтом добавьте вручную следующие команды в скрипт Init data вашего проекта (30.create-db.sql):

insert into SEC_GROUP (ID, CREATE_TS, VERSION, NAME, PARENT_ID)
values ('0fa2b1a5-1d68-4d69-9fbd-dff348347f93', current_timestamp, 0, 'Company', null)^

insert into SEC_USER (ID, CREATE_TS, VERSION, LOGIN, LOGIN_LC, PASSWORD, NAME, GROUP_ID, ACTIVE)
values ('60885987-1b61-4247-94c7-dff348347f93', current_timestamp, 0, 'admin', 'admin',
'cc2229d1b8a052423d9e1c9ef0113b850086586a',
'Administrator', '0fa2b1a5-1d68-4d69-9fbd-dff348347f93', 1)^

insert into SEC_USER (ID, CREATE_TS, VERSION, LOGIN, LOGIN_LC, PASSWORD, NAME, GROUP_ID, ACTIVE)
values ('a405db59-e674-4f63-8afe-269dda788fe8', current_timestamp, 0, 'anonymous', 'anonymous', null,
'Anonymous', '0fa2b1a5-1d68-4d69-9fbd-dff348347f93', 1)^

5.3. Компоненты среднего слоя

В дереве проекта внутри элемента Middleware отображаются все сервисы среднего слоя и управляемые бины, созданные в проекте. В данном разделе мы рассмотрим, как создавать сервисы и бины.

5.3.1. Создание сервисов

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

Чтобы создать новый сервис, в контекстном меню элемента Middleware в дереве проекта выберите New > Service:

create service

Введите имя интерфейса сервиса. После этого будут автоматически сгенерированы константы имён соответствующего бина и самого сервиса:

create service 2

Интерфейс сервиса будет создан в модуле global, а его реализация - в модуле core. Также новый сервис будет автоматически зарегистрирован в файле конфигурации web-spring.xml.

Маркер в жёлобе Studio позволяет легко переключаться между интерфейсом и бином сервиса:

service interface

Когда вы создаёте новый метод в интерфейсе сервиса, Studio сама проверит наличие его реализации, и если реализация не найдена, предложит создать её в классе бина сервиса:

service interface 2

5.3.2. Создание бинов

Studio отображает все управляемые бины среднего слоя, включая entity listeners и transaction listeners, в элементе Middleware > Beans дерева проекта.

studio beans

Для создания управляемого бина нужно создать новый Java-класс: выберите нужный пакет в дереве проекта и выберите New > Java Class в его контекстном меню. Затем добавьте классу аннотацию @Component, как в примере выше. Чтобы избежать конфликта имён, особенно при разработке компонента приложения, рекомендуется явно указать уникальное имя бина в этой аннотации.

5.4. Универсальный пользовательский интерфейс

Studio предлагает широкий набор возможностей для оптимизации работы с пользовательским интерфейсом приложения.

В секции Generic UI дерева проекта вы можете найти следующие элементы:

  • Web Menu открывает графический редактор главного меню приложения.

  • Main Message Pack содержит строки сообщений для элементов главного меню и общих элементов UI приложения.

  • Screens отображает созданные экраны.

  • Themes используется для управления темами визуального представления приложения.

5.4.1. Создание и удаление экранов

Чтобы создать экран пользовательского интерфейса, выберите New > Screen в контекстном меню элемента Generic UI в дереве проекта. Если вы хотите создать CRUD-экраны для сущности, выберите эту сущность или одно из её представлений в дереве проекта и также нажмите New > Screen в контекстном меню:

create screen

Studio отобразит список доступных шаблонов экранов. Список разделён на две секции: Screen Templates и Legacy Screen Templates. Первая содержит шаблоны экранов, для которых доступен новый API начиная с версии 7 фреймворка, тогда как в секции Legacy содержатся экраны, которые совместимы также с версией 6.

create screen 2

При создании экрана для сущности или её представления, выбранных в дереве проекта, поля Entity и View будут заполнены автоматически:

create screen 3

В секции Advanced мастера создания экрана вы можете изменить стандартные имена дескриптора и контроллера экрана, а также его идентификатор. Это может потребоваться, если вы планируете создать более одного экрана для выбранной сущности.

Когда вы нажмёте Finish, будут созданы и открыты файлы XML-дескриптора и Java-контроллера экрана. Старые экраны, не имеющие аннотации UiDescriptor и/или @UiController, дополнительно будут зарегистрированы в конфигурационном файле web-screens.xml.

При удалении файлов экрана используйте опцию Safe delete для того, чтобы найти и удалить ссылки на данный экран:

safe delete screen 1

Некоторые ссылки, например в файлах web-menu.xml и web-screens.xml, будут удалены автоматически. При наличии других ссылок, будет показан диалог, в котором они будут перечислены. Нажмите в нем View Usages, просмотрите ссылки в окне инструментов Find и нажмите Cancel или Do Refactor:

safe delete screen 2

5.4.2. Работа с дескриптором экрана

Редактор XML-дескриптора экрана содержит две вкладки: Text и Designer. На вкладке Text вы можете редактировать код XML напрямую, а вкладка Designer позволяет работать с экраном в визуальном редакторе разметки.

xml descriptor

Переключаться между дескриптором и контроллером экрана можно с помощью специального маркера в жёлобе Studio. Также вы можете выбрать дескриптор в дереве проекта и в его контекстном меню нажать Go to controller.

Studio непрерывно инспектирует код разметки экрана на предмет ошибок и несоответствий, проверяет внутренние и внешние ссылки. В случае обнаружения следующих проблем Studio покажет специальное предупреждение или подчеркнёт проблемный элемент в XML-коде:

  • Экран не может быть собран из-за ошибки в разметке XML.

  • Ссылка на сущность или её свойство, используемая компонентом, не соответствует реальной модели данных приложения.

  • Есть конфликт размеров компонентов: учитываются значения атрибутов width, height и expand.

  • Значения атрибутов dataContainer и dataLoader не ссылаются ни на один из имеющихся контейнеров или загрузчиков.

  • Для полей внутри элемента form явно не определён XML-атрибут property: в этом случае для ссылки на поле сущности будет неявно использовано значение атрибута id.

  • Семантическая ошибка в элементе form: поля дублируются или располагаются не внутри вложенного элемента column.

  • Количество столбцов gridLayout не соответствует заявленному количеству.

  • Дублирование атрибута в расширенном экране, когда один и тот же атрибут объявлен и в родительском, и в дочернем экране.

  • Имена элементов в дочернем экране не соответствуют аналогичным элементам в родительском экране, либо их расположение некорректно.

  • Значение атрибута messagesPack не ссылается на реально существующий пакет сообщений, содержащий как минимум один файл messages_xx.properties.

  • Ссылка на схему XSD устарела.

  • Значения идентификаторов элементов не уникальны внутри данного экрана.

Эти инспекции можно настроить в окне Settings (CUBA > Settings > Editor > Inspections).

На вкладке Designer отображается визуальный дизайнер, который позволяет создавать компоновку экрана и задавать свойства компонентов UI в стиле WYSIWYG.

xml descriptor 2

Рабочая область дизайнера включает в себя четыре панели:

  • Canvas - рабочая область, в которой вы можете располагать компоненты, а также изменять их размер и задавать выравнивание с помощью кнопок:

    • расширить горизонтально,

    • расширить вертикально,

    • выровнять по вертикали/горизонтали.

  • Palette - палитра, содержащая набор доступных экранных компонентов:

    • Контейнеры;

    • Компоненты;

    • Компоненты данных: контейнеры и загрузчики;

    • Не-визуальные компоненты: действия, настройки диалогового окна, таймеры.

Чтобы добавить компонент на экран, перетащите его из палитры на полотно или в панель иерархии компонентов.

  • Hierarchy - панель иерархии компонентов, отображающая использованные в экране компоненты в виде дерева. Элементы дерева можно перетаскивать с места на место, иногда это даже удобнее, чем перемещать их по полотну. Вы можете удалять, копировать, вырезать или вставлять элементы в дерево иерархии с помощью его контекстного меню, открываемого по клику правой кнопки мыши.

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

5.4.3. Работа с контроллером экрана

Данный раздел посвящён возможностям Studio для работы с кодом контроллеров экранов.

Специальные значки в жёлобе Studio позволяют быстро переключаться между дескриптором и контроллером экрана, позиционировать курсор на нужном XML-элементе инжектированного компонента и т.д.

controller
Инжекция зависимостей

Механизм Dependency injection - это основной способ получения ссылок на визуальные компоненты и элементы API в коде контроллера экрана. Конечно, вы можете описать поле нужного типа и аннотировать его вручную, но Studio предоставляет возможность выбрать нужный объект из списка в специальном окне, чтобы создать требуемое поле автоматически. Это окно открывается по нажатию Alt+Insert (Cmd+N), далее нужно выбрать пункт Inject…​ в выпадающем меню Generate:

controller injection

Инжектировать в контроллеры можно следующие объекты:

  • Визуальные компоненты и компоненты данных, определенные в XML-дескрипторе,

  • Интерфейсы API экранов,

  • Интерфейсы инфраструктуры,

  • Сервисы среднего слоя,

  • Интерфейсы конфигурации.

Обработка событий

Создав обработчик некоего события, вы можете выполнять его код на разных этапах жизненного цикла экрана, например, реагировать на действия пользователя. Обработчик представляет собой отдельный метод в контроллере экрана с аннотацией @Subscribe, принимающий событие в качестве параметра. Такой метод можно создать в Studio: нажмите Alt+Insert (Cmd+N) и выберите Subscribe to Event в меню Generate:

subscribe dialog

Каждое событие в отобразившемся окне снабжено описанием Javadoc в правой части окна.

По умолчанию в окне доступны следующие события:

  • События контроллера для управления жизненным циклом экрана.

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

  • События фрейма для управления жизненным циклом внешнего фрейма, в который включён данный экран.

  • События контекста данных, позволяющие реагировать на изменения data context и выполнять код до и после сохранения данных в экране.

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

Делегаты

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

Делегат представляет собой метод контроллера экрана со специальной подписью и аннотацией @Install. Такой метод также можно создать в Studio, нажав Alt+Insert (Cmd+N) и выбрав Install Delegate в меню Generate:

install dialog

Каждый делегат в отобразившемся окне снабжён описанием Javadoc в правой части окна.

5.4.4. Работа с меню приложения

Дизайнер меню позволяет задать элементы главного меню приложения и сохранить их в конфигурационном файле web-menu.xml. На вкладке Structure вы найдёте графический дизайнер меню, а его XML-код можно редактировать на вкладке Text.

web menu

Существует два режима создания меню:

  • Режим Single mode содержит только элементы, описанные в файле web-menu.xml. В этом режиме вам придётся вручную создавать все элементы меню, включая те, что были созданы в компонентах приложения. С другой стороны, этот режим предоставляет вам полный контроль над структурой меню.

  • Режим Composite mode включает в себя все элементы, описанные в файле menu.xml проекта, плюс элементы из конфигурационных файлов меню компонентов приложения. Этот режим позволяет легко использовать все унаследованные элементы и добавить к ним элементы, специфичные для данного проекта, в любое место в структуре меню. Унаследованные элементы отредактировать нельзя.

    Дополнительно на вкладке Text можно определить для элементов меню атрибуты ìnsertBefore и insertAfter, которые указывают, где должен быть размещён конкретный элемент меню. Эти атрибуты позволяют комбинировать элементы меню текущего проекта с элементами, унаследованными из компонентов, если выбран режим Composite.

    Например, если вы хотите поместить собственную структуру меню слева от стандартного элемента Administration, установите атрибут insertBefore="administration" для корневого элемента в вашей иерархии.

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

Чтобы добавить в меню новый элемент, выберите существующий элемент (или файл конфигурации, если нужно создать элемент верхнего уровня) и нажмите на кнопку +. Появится окно Menu item editor, в котором вы можете создать элемент меню с одним из следующих типов:

Screen
web menu create

Элемент меню, открывающий экран приложения.

Для элемента Screen необходимо определить следующие свойства:

  • Screen - неуникальный идентификатор экрана, который должен открывать этот элемент.

  • Id - дополнительный уникальный идентификатор элемента.

  • Open type - свойство, определяющее, как должен открываться экран: в новой вкладке или в виде модального окна (NEW_TAB или DIALOG). По умолчанию используется NEW_TAB.

  • Shortcut - горячие клавиши для открытия данного экрана. Допустимые модификаторы (ALT, CTRL, SHIFT) разделяются символом "-", например, ALT-C.

  • Style name - определяет имя стиля элемента, подробнее см. в разделе Темы приложения основного руководства.

Menu
web menu create 2

Элемент меню, содержащий другие элементы меню (подменю).

Для элемента Menu необходимо определить следующие свойства:

  • Id - дополнительный уникальный идентификатор элемента.

  • Style name - имя стиля элемента.

Bean
web menu create 3

Элемент меню, который вызывает определённый метод управляемого бина.

Для элемента Bean необходимо определить следующие свойства:

  • Id - дополнительный уникальный идентификатор элемента.

  • Bean - имя бина, которое можно получить с помощью AppBeans (к примеру, cuba_Messages).

  • Bean method - имя метода бина.

  • Shortcut - горячие клавиши для вызова метода. Допустимые модификаторы (ALT, CTRL, SHIFT) разделяются символом "-", например, ALT-C.

  • Style name - имя стиля элемента.

Class
web menu create 4

Элемент меню, который выполняет метод run() определённого класса.

Для элемента Class необходимо определить следующие свойства:

  • Id - дополнительный уникальный идентификатор элемента.

  • Class - полное имя класса, унаследованного от Runnable.

  • Shortcut - горячие клавиши для вызова метода. Допустимые модификаторы (ALT, CTRL, SHIFT) разделяются символом "-", например, ALT-C.

  • Style name - имя стиля элемента.

Separator

Горизонтальная линия, разделяющая элементы меню.

5.4.5. Изменение стиля приложения

В Studio можно легко и быстро создавать как расширения тем приложения, так и собственные темы.

theme extension

При создании расширения или новой темы в проекте будет создана специальная структура папок, а также будет изменён скрипт сборки build.gradle.

Все созданные темы отображаются в секции Themes дерева проекта.

halo ext

После расширения или создания темы вы можете изменять переменные стилей как вручную в файле SCSS, так и в визуальном редакторе: для этого в контекстном меню новой темы выберите пункт Open Variables File. Этот файл также можно открыть из главного меню CUBA: выберите Advanced > Manage themes > Edit theme variables.

theme variables