Введение

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

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

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

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

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

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

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

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

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

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

IntelliJ Platform предоставляет мощный фундамент для среды разработки CUBA Studio. Она содержит множество функций, ускоряющих производительность CUBA-разработчика, таких как удобный пользовательский интерфейс, контекстнозависимое автодополнение, безопасные рефакторинги кода, фоновые проверки корректности, встроенные средства контроля версий и интеграция с Gradle. Если вы не использовали IntelliJ IDEA раньше, то мы рекомендуем вам посетить секцию Learn & Support section веб-сайта IntelliJ IDEA, чтобы ознакомиться с её основными возможностями и особенностями.

Примечания к выпускам

Версия 13

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

  • Эффективное использование пространства окна IDE.

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

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

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

  1. Панели дизайнера стали независимыми панелями IDE (tool window). Component Hierarchy - осталась в верхнем правом углу IDE, как и раньше. Component Palette отображается в нижнем правом углу. Component Inspector отображается в нижнем левом углу и содержит вкладки Properties и Handlers.

    Эти панели автоматически появляются, когда вы открываете дескриптор экрана в редакторе. Когда вы переключаетесь в редакторе на другой экран, содержимое панелей обновляется. Иногда, когда вы открываете другие панели IDE (такие как Gradle, Persistence и т.д.), панели дизайнера экранов скрываются, и потом их нужно будет переоткрыть, используя соответствующие кнопки на левой и правой кромках окна IDE.

    Сохранилась возможность отображения панели Component Inspector в правом нижнем углу для тех пользователей, кто предпочитает старую компоновку. Чтобы переместить эту панель на правую сторону окна, используйте кнопку Move to Right Bottom, расположенную в заголовке панели.

    v 13 sd tool windows
  2. Панель предпросмотра верстки теперь разделяет пространство редактора с исходным кодом дескриптора экрана. Вкладки Text и Designer ушли в прошлое. Справа, на верхней панели редактора дескриптора экрана теперь расположены четыре кнопки, переключающие режим отображения предпросмотра:

    1. Editor only - редактор содержит только исходный код.

    2. Editor and Preview - пространство редактора разделено пополам между исходным кодом и панелью предпросмотра.

    3. Preview only - весь редактор занят панелью предпросмотра (как было раньше в дизайнере экранов).

    4. Preview in Window - редактор содержит исходный код, а панель предпросмотра выделена в независимое окно, которое можно переместить на другой монитор.

  3. Панели дизайнера активны и взаимодействуют с редактором XML кода. Опытные разработчики, которые просматривают и редактируют верстку экранов путем прямого редактирования XML кода, теперь могут воспользоваться всеми возможностями быстрой генерации кода в дизайнере экранов:

    1. Панели дизайнера Component Hierarchy и Component Inspector следят за курсором в XML коде и выбирают соответствующий компонент, когда курсор переходит от одного тега к другому.

    2. При выборе элемента в панели иерархии - курсор перемещается к соответствующему XML тегу в исходном коде.

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

  4. Дизайнер экранов теперь отображает столбцы и действия компонентов типа TableDataGrid) в дереве Component Hierarchy. Кроме того были удалены несколько модальных диалогов, которые ранее использовались для редактирования столбцов и действий. Теперь вы можете просматривать и редактировать свойства столбцов и действий, а также их обработчики событий, прямо в панели Component Inspector. Добавлять новые столбцы и действия в таблицу тоже стало удобнее. Когда в дизайнере выбрана таблица, одна из её колонок или действий, то в панели Component Inspector отображается кнопка + Add. Нажав её, можно добавить один или несколько столбцов или действий в таблицу.

  5. В дизайнер экранов добавлены диалоги-помощники создания компонентов. Добавлять контейнеры данных, таблицы и гриды, столбцы и действия таблиц, поля форм в экраны стало проще.

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

    v 13 datagrid wizard
  6. В панель дизайнера Component Hierarchy добавлена возможность поиска компонента по строке:

    v 13 search hierarchy
  7. В контекстное меню панели Component Hierarchy добавлены дополнительные конвертации. Теперь можно быстро сконвертировать компонент TextField в TextArea и другие компоненты:

    v 13 text field conversions
  8. Действие контекстного меню Inject to Controller, доступное в панели Component Hierarchy, теперь позволяет инжектировать несколько выбранных компонентов за раз.

Другие добавленные возможности и улучшения:

  1. Добавлена поддержка языка программирования Kotlin. Вы можете выбрать Kotlin как основной язык программирования проекта в мастере создания проекта, если выбрана версия платформы 7.2.0 или выше. Все элементы CUBA проекта: сущности, экраны, сервисы - генерируются с использованием Kotlin. Визуальные дизайнеры Studio, автодополнения, инспекции и мгновенное применение изменений также поддерживают Kotlin.

  2. Был переработан механизм мгновенного применения изменений к отладочному серверу (Hot Deploy) для проектов, использующих версию платформы 7.2.0 или выше (для всех языков программирования), чтобы поддержать язык Kotlin. Если вы столкнетесь с какими-либо проблемами в Java / Groovy проектах, вы можете переключиться на старый режим применения изменений, выключив следующую настройку: главное меню → CUBASettingsProject SettingsHot deploy compiled classes.

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

  4. К конфигурации запуска CUBA Application были добавлены две настройки: аргументы командной строки (command line arguments) и переменные среды (environment variables). Эти настройки применяются к процессу Tomcat, который выполняет CUBA приложение в режиме отладки. Например, указав аргументы командной строки, можно задать часовой пояс: -Duser.timezone=Europe/London или увеличить доступную память: -Xmx1500m для сервера приложения.

    v 13 run configuration
  5. Добавлен новый шаблон экрана входа в систему (login) с обновленными компоновкой и дизайном. Этот шаблон доступен для проектов, основанных на версии платформы 7.2.0 или выше. Примеры, как новый экран входа выглядит, можно посмотреть здесь: Тикет GitHub. Чтобы добавить новый экран входа в ваш проект, выберите шаблон Login screen with branding image в мастере создания экранов NewScreen.

  6. В диалог Project Properties добавлена возможность менять версию проектных артефактов сборки:

    v 13 artifact version
  7. Действие Inject добавлено в верхнюю панель действий для редактора исходного кода сервисов среднего слоя и Spring бинов. Ранее оно было доступно только через меню Generate (Alt+Insert).

  8. Добавлен удобный диалог для задания параметров подключения в окне Data Store Properties. К полю Connection params добавлена кнопка "карандаш", нажатие этой кнопки открывает диалог, позволяющий ввести параметры подключения. Studio конвертирует параметры в строку подключения, используя разделительные символы конкретной СУБД:

    v 13 connection params
  9. Диалог Locales теперь подсказывает доступные языки и страны и автоматически заполняет код локали соответственно выбранному языку и стране:

    v 13 locales dialog
  10. Инспекция кода Attribute is not included into the view была расширена. Теперь она также проверяет использования неперсистентных атрибутов, которые имеют связанные персистентные атрибуты, указанные в параметре аннотации @MetaProperty#related.

  11. Улучшено поведение Studio для проблемных ситуаций, когда синхронизация проекта Gradle по какой-то причине завершается ошибкой. Главное меню CUBA теперь остается видимым и содержит следующие дополнительные пункты:

    1. Пункт Re-Import Gradle Project может помочь в случае однократной проблемы недоступности сети.

    2. Пункт Restore Project to the Latest State откатывает содержимое скриптов сборки Gradle до состояния, соответствующего последнему успешному импорту, и это позволяет исправить ситуацию в случае нечаянных или ошибочных изменений в скриптах сборки.

      v 13 menu import failed
  12. Версия Studio, устанавливаемая как отдельная IDE, обновлена до платформы IntelliJ Community 2019.2. Если у вас уже была установлена отдельная Studio IDE, то она не будет обновлена; вам следует скачать новую версию с сайта CUBA Platform.

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

Версия 12
  1. Дизайнер экранов был переработан с использованием UI компонентов платформы IntelliJ. Новый дизайнер открывается быстрее и имеет более отзывчивый интерфейс. Для дизайнера было проделано много улучшений, некоторые из них упомянуты ниже.

    v 12 screen designer
  2. В дизайнер экранов добавлена новая вкладка Handlers, рядом с Palette и Properties. Она отображает как уже существующие методы-обработчики, так и все возможные варианты слушателей событий и делегатов действий, связанных с выбранным компонентом. Чтобы создать необходимый метод-обработчик - просто выполните двойной клик мыши по соответствующей строке таблицы.

    v 12 sd handlers
  3. Действие Preview добавлено в верхнюю панель действий дескриптора экранов. Оно открывает окно с предварительным просмотром верстки редактируемого экрана. Рабочая область экрана предпросмотра взаимодействует с редактором XML и автоматически обновляет содержимое в соответствии с изменениями верстки.

    v 12 sd preview
  4. Добавлены действия Inject to controller и Go to XML в контекстное меню дерева иерархии компонентов в дизайнере экранов.

  5. Добавлены действия CUBA Documentation в контекстное меню дерева иерархии компонентов и контекстное меню палитры компонентов. Эти действия открывают соответствующую секцию компонента в руководстве разработчика CUBA.

  6. Кнопка Add Column добавлена во вкладку Properties для компонента Form.

  7. Добавлено автодополнение имени класса для поля class в диалогах Validator и Formatter дизайнера экрана.

  8. Добавлена генерация кода слушателей для различных системных событий CUBA-приложения. Вызвать генерацию можно двумя способами:

    1. Открыть существующий Spring-бин и нажать Subscribe to event на верхней панели действий редактора исходного кода.

    2. В секции Middleware дерева проекта CUBA выполнить правый клик мыши и выбрать пункт NewEvent Listener.

      v 12 event listeners
  9. Добавлены опции уровня проекта, влияющие на генерацию экранов. Эти настройки используются мастером NewScreen…​. Чтобы изменить настройки, откройте главное меню → CUBASettingsScreen Generation Settings. Доступны следующие настройки:

    1. Form field width (450px по умолчанию) - используется редакторами сущностей

    2. Keep editor actions at the bottom - используется редакторами сущностей, открываемыми в "полноэкранном" режиме (не как диалог)

    3. Force modal open type for editors - используется редакторами сущностей, открываемыми как диалог

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

  11. Добавлена возможность генерировать код методов-обработчиков для компонентов, у которых еще не задан id. Studio попросит пользователя ввести id компонента, когда это потребуется.

  12. Действие Main Menu добавлено в верхнюю панель действий для редактора контроллера экрана. Оно позволяет добавить текущий экран в главное меню или перейти к настройкам уже существующего пункта меню.

    v 12 main menu action
  13. Улучшен интерфейс элементов Build WAR и UberJAR в секции Deployment дерева проекта CUBA. Теперь вы можете собрать WAR или UberJar просто выполнив двойной клик по соответствующему элементу Build WAR или Build UberJAR, если сборка данного артефакта включена. Конфигурационные файлы, относящиеся к данным артефактам (single-war-web.xml, logback.xml, jetty-env.xml и т.д.), теперь показываются рядом с элементами дерева проекта WAR/UberJAR Settings для удобного доступа.

    v 12 uber jar
  14. Добавлены новые действия для создания новых скриптов создания и обновления БД. Эти действия доступны в дереве проекта CUBA, внутри секции Data StoresMain Data Store:

    1. init → контекстное меню → NewDatabase init script

    2. update → контекстное меню → NewDatabase update script

  15. Диалог Install Delegate, который вызывается из контроллера экрана, теперь позволяет сгенерировать делегаты: formatter, column generator и value provider для колонок таблиц.

  16. Добавлены подсказки для атрибута icon в XML дескрипторах экранов, также добавлен предпросмотр иконки в виде gutter icon.

    v 12 icon gutter
  17. Добавлены подсказки для XML атрибута optionsEnum у компонента LookupField.

  18. Всплывающее окно Quick Documentation, когда оно вызвано для UI компонентов, теперь отображает ссылку для перехода к документации CUBA:

    v 12 quick doc
  19. Диалог Localized Message в редакторе сущности теперь автоматически составляет ключи сообщений для ошибок валидации Bean Validation, например "playground_Rank.queueSize.validation.Digits" или "playground_Tariff.taxType.validation.NotNull".

  20. Добавлена поддержка опции Integrated Security для типа СУБД Microsoft SQL Server (2012+). Заметьте, что она доступна только для проектов, основанных на CUBA 7.1.0 или более поздних.

  21. Улучшена производительность работы Studio с большими проектами (редактор сущностей, статический анализ файлов views.xml, дерево проекта CUBA).

  22. Минимальная поддерживаемая версия IntelliJ IDEA увеличена до 2019.1. Это значит, что если вы используете более старую версию IDEA (или CUBA Studio), вы не сможете обновить у себя плагин CUBA до новых версий; вам следует обновить вашу инсталляцию IDEA (или CUBA Studio).

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

Версия 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.2. Плагин CUBA имеет свою собственную версию, начинающуюся с 13.

Установочные файлы 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 2019.1 или более новую версию.

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

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

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

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

1.1. Работа за прокси-сервером

Чтобы сконфигурировать CUBA Studio для доступа к интернету через прокси-сервер, вам нужно проделать следующие шаги:

  1. Настроить IntelliJ IDEA (или CUBA Studio)

  2. Настроить Gradle

  3. Настроить Git (необязательно)

Настройка прокси в IntelliJ IDEA (CUBA Studio)
  • Открыть диалог Settings: главное меню → FileSettings.

  • Выбрать секцию настроек Appearance & BehaviorSystem SettingsHTTP Proxy.

  • Проставить необходимые значения настроек и нажать Check connection для проверки:

proxy idea

При необходимости обратитесь к этой странице за дополнительной информацией.

Настройка прокси в Gradle
  • Найдите файл ~/.gradle/gradle.properties в домашнем каталоге пользователя.

  • Отредактируйте этот файл и добавьте необходимые параметры, как описано в документации Gradle:

systemProp.http.proxyHost=192.168.57.1
systemProp.http.proxyPort=3128
systemProp.http.proxyUser=developer
systemProp.http.proxyPassword=Df887..33
systemProp.http.nonProxyHosts=*.nonproxyrepos.com|localhost
Настройка прокси в Git (необязательно)

Возможно вы захотите задать настройки прокси в том числе и для инструмента контроля версий Git, например чтобы скачивать проекты-примеры из GitHub репозиториев CUBA:

Выполните эту команду:

git config --global http.proxy http://proxyUsername:proxyPassword@proxy.server.com:port

Или обратитесь к документации Git для детального описания.

1.2. Работа без интернет подключения

Разработка проектов в Studio возможно и без интернет подключения (в оффлайне). При этом все проектные зависимости должны быть уже загружены, т.е. проект уже был открыт и собирался в данной установке Studio. Часть функционала Studio будет недоступна в оффлайн-режиме, например будет невозможно сменить версию CUBA или просматривать список аддонов в CUBA Add-ons Marketplace.

Чтобы включить оффлайн режим, откройте панель инструментов Gradle, расположенную в правой части окна IDE и нажмите кнопку Toggle Offline Mode:

gradle offline mode

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

1.3. Нестандартные сборки Studio

Иногда вам может потребоваться использовать одну из нестандартных сборок Studio в вашей IDE. Это может быть необходимо для того, чтобы получить ранний доступ к самым новым возможностям Studio или чтобы поучаствовать в бета-тестировании. Чтобы использовать нестандартную сборку Studio, вам нужно установить плагин определенной версии в среду разработки IntelliJ IDEA.

Tip

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

Бета-версии

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

  • Предоставить заинтересованным пользователям ранний доступ к новым возможностям Studio.

  • Помочь команде CUBA опробовать новые версии Studio на широком диапазоне рабочих сред, установив бета-версию и предоставив команде обратный отзыв.

Чтобы попробовать возможности бета-версии, проделайте следующее:

  1. Откройте: главное меню → FileSettingsPlugins.

  2. Нажмите иконку gear и выберите Manage Plugin Repositories.

  3. Нажмите + (Add), чтобы добавить строку и введите следующий Repository URL: https://plugins.jetbrains.com/plugins/beta/list

  4. Переключитесь на вкладку Marketplace. Вы должны сразу увидеть, что плагин CUBA предлагается к обновлению на версию BETA.

  5. Нажмите Update.

  6. Перезагрузите IDE, если вам будет предложено это сделать.

Если/когда вам потребуется вернуться на стабильную версию плагина, проделайте следующее:

  1. Откройте: главное меню → FileSettingsPlugins.

  2. Выполните Uninstall для плагина CUBA.

  3. Нажмите иконку gear и выберите Manage Plugin Repositories.

  4. Удалите "beta" репозиторий из списка.

  5. Установите плагин CUBA снова, он скачается из стабильного канала обновлений.

Ночные (nightly) сборки

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

Warning

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

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

  1. Откройте: главное меню → FileSettingsPlugins.

  2. Нажмите иконку gear и выберите Manage Plugin Repositories.

  3. Нажмите + (Add), чтобы добавить строку и введите следующий Repository URL: https://plugins.jetbrains.com/plugins/haulmont_nightly/list

  4. Переключитесь на вкладку Marketplace. Вы должны сразу увидеть, что плагин CUBA предлагается к обновлению на версию NIGHTLY.

  5. Нажмите Update.

  6. Перезагрузите IDE, если вам будет предложено это сделать.

Так как новые ночные сборки публикуются ежедневно, вы начнете получать ежедневные уведомления "plugin can be updated" от IDE.

Если/когда вам потребуется вернуться на стабильную версию плагина, проделайте следующее:

  1. Откройте: главное меню → FileSettingsPlugins.

  2. Выполните Uninstall для плагина CUBA.

  3. Нажмите иконку gear и выберите Manage Plugin Repositories.

  4. Удалите "nightly" репозиторий из списка.

  5. Установите плагин CUBA снова, он скачается из стабильного канала обновлений.

Установка плагина с диска

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

  1. Откройте страницу CUBA Plugin в репозитории плагинов JetBrains.

  2. Выберите канал, из которого вам нужно скачать релиз (Stable, Beta или Nightly).

  3. Найдите требуемую версию в списке Version History.

  4. Нажмите Download, чтобы скачать сборку.

  5. Откройте главное меню → FileSettingsPlugins.

  6. Нажмите иконку gear и выберите Install Plugin from Disk…​.

  7. Выберите загрузившийся zip файл в дереве файлов и нажмите OK.

  8. Перезагрузите 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, или используйте главное меню → FileNewProject.

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

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

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

  5. Измените Module prefix, если необходимо. Это значение служит префиксом названий модулей CUBA проекта. Префикс модулей возможно изменить позже.

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

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

  8. Выберите Platform version – используемую в проекте версию платформы CUBA. Если у вас нет особых требований, выбирайте последнюю релизную версию.

  9. Для целей бета-тестирования или раннего опробования новых возможностей платформы CUBA вам может потребоваться использовать одну из нестабильных версий платформы, тех что заканчиваются суффиксами BETA или SNAPSHOT. Чтобы увидеть их в списке выбора Platform version, включите флажок Show unstable versions. Учтите также, что SNAPSHOT-версии публикуются только в репозиторий артефактов repo.cuba-platform.com.

  10. Выберите значение в выпадающем списке Languages support, чтобы сменить набор языков программирования, используемых в проекте, или оставьте рекомендуемое значение Java.

  11. Используйте поле Available locales, чтобы открыть диалог редактирования Locales и поменять набор локалей, используемых в проекте. Вы сможете изменить их позже, если потребуется.

  12. Нажмите Next.

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

  14. Нажмите Next.

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

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

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

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

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

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

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.

  • Для целей бета-тестирования или раннего опробования новых возможностей платформы CUBA вам может потребоваться использовать одну из нестабильных версий платформы, тех что заканчиваются суффиксами BETA или SNAPSHOT. Чтобы увидеть их в списке выбора Platform version, включите флажок Show unstable versions.

    Tip

    SNAPSHOT-версии доступны только, если вы используете репозиторий артефактов repo.cuba-platform.com.

    Warning

    Нестабильные (BETA и 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 аддоны, вам может потребоваться обновить их до соответствующих версий, совместимых с новой версией платформы CUBA:

    • Откройте дерево проекта CUBA → ProjectAdd-ons.

    • Перейдите на вкладку Updates.

    • Выберите все аддоны, для которых предлагается обновление.

    • Нажмите Apply & Close.

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

  • Попробуйте собрать проект, выполнив команду 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 по умолчанию).

Настройки конфигурации запуска (Run/Debug Configuration)

При необходимости вы можете задавать настройки отладочного сервера Tomcat, который используется конфигурацией запуска (Run/Debug configuration) CUBA Application. Диалог с настройками можно открыть следующим образом:

  • Кликнуть элемент CUBA Application на панели инструментов и выбрать Edit Configurations…​ в выпадающем меню.

  • Или использовать главное меню → RunEdit Configurations…​

run configuration toolbar

Появится диалог Run/Debug Configuration. Вас могут заинтересовать следующие настройки:

  • JRE - среда запуска (Java Runtime Environment), используемая для запуска отладочного сервера Tomcat. Вы можете выбрать JRE, отличающуюся от проектной JDK, не забывая при этом про требования совместимости (приложение, скомпилированное под Java 11, не запустится под Java 8).

  • Command line arguments - опции JVM, используемые при запуске отладочного сервера. Например укажите -Xmx1500m, чтобы увеличить максимально допустимый объем используемой сервером памяти.

  • Environment Variables - переменные среды, которые должны быть доступны процессу отладочного сервера.

run configuration settings

3.5. Использование неосновной JDK

Как IntelliJ IDEA, так и Gradle по умолчанию используют Java Development Kit (JDK), определяемую переменной JAVA_HOME, для сборки и запуска Java проектов. Чтобы использовать другую JDK в вашем проекте, не меняя глобальные настройки, вам необходимо проделать некоторые действия.

Рассмотрим следующую конфигурацию рабочей среды:

  • Переменная среды JAVA_HOME на рабочей машине указывает на JDK 8, и по каким-то причинам вы не можете поменять её.

  • Вы решили использовать JDK 11 в проекте.

  • Вы будете использовать новые API, появившиеся в Java 11, поэтому ваш проект должен и компилироваться и запускаться под JDK 11.

Вам нужно проделать следующие шаги:

  • Добавить JDK 11 в глобальный список SDK в IDEA, если она еще не добавлена. Откройте диалог через главное меню → FileProject Structure. Выберите SDKs в левом меню. Нажмите кнопку + → выберите JDK → укажите каталог, куда установлена JDK 11. Нажмите OK, чтобы сохранить изменения.

  • При создании нового проекта - выберите "11" в поле Project SDK.

  • Для уже существующих проектов - откройте диалог через главное меню → FileProject Structure и измените значение поля ProjectProject SDK.

  • Перейдите в корневой каталог проекта и создайте там файл gradle.properties со следующим содержимым:

# Путь к JDK 11
org.gradle.java.home = C:/Java/jdk-11.0.5.10-hotspot
  • Подредактируйте файл build.gradle, расположенный в корневом каталоге проекта. Добавьте следующие выражения в конец блока configure([globalModule, coreModule, webModule]):

configure([globalModule, coreModule, webModule]) {
    ...
    sourceCompatibility = '11'
    targetCompatibility = '11'
}
  • Обновите конфигурацию Gradle проекта: панель инструментов GradleReimport All Gradle Projects;

  • Измените JRE, используемую конфигурацией запуска CUBA Application. Главное меню → RunEdit configurations…​CUBA Application → Измените значение поля JVM.

После выполнения этих действий проект будет компилироваться и запускаться под JDK 11, без необходимости менять глобальные системные настройки.

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 содержатся общие настройки, которые распространяются на все проекты, открываемые в данной установленной 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 and embedded browser zoom percentage - масштаб (zoom) по умолчанию для рабочей области дизайнера экрана. Масштаб можно настроить позже, используя одно из действий на верхней панели области предпросмотра.

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

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

Секция Project settings

Вложенная секция 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 entity attribute 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 compiled classes - включает новый механизм мгновенного применения изменений (hot deploy) для проектов, основанных на CUBA 7.2 и выше. Старый механизм копировал исходные файлы Java в каталоги конфигурации Tomcat и компилировал их особым загрузчиком классов. Новый механизм компилирует исходный код на стороне IDE и таким образом позволяет мгновенное применение изменений для кода на языке Kotlin. Если вы столкнетесь с проблемами при использовании нового механизма мгновенного применения изменений, вы можете попробовать отключить эту настройку.

  • Scaffolding language - выбирает, какой язык программирования будет использоваться для генерации кода в проектах с подключенным языком Kotlin. Доступные опции: Kotlin, Java и Always Ask. Если ваш проект имеет смешанное Java / Kotlin содержимое и вы хотите контролировать, на каком языке будут сгенерированы каждая новая сущность, сервис или экран - выберите значение Always Ask в списке выбора. Эта настройка отображается только для проектов с включенной поддержкой Kotlin.

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

  • Screen Generation Settings - настройки, влияющие на генерацию экранов. Они используются мастером NewScreen…​. Доступны следующие настройки:

    • Default form field width - используется редакторами сущностей

    • Keep editor actions at the bottom - используется редакторами сущностей, открываемыми в "полноэкранном" режиме (не как диалог)

    • Force modal open type for editors - используется редакторами сущностей, открываемыми как диалог

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

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

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

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

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

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

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

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

Основные настройки
  • Поле Module prefix отображает префикс имен модулей проекта. Имя модуля в свою очередь определяет название артефактов сборки, например модуль sales-global собирает артефакт sales-global-0.1.jar. Вы можете изменить значение в данном поле, чтобы переименовать модули проекта. Например CUBA проект с префиксом модулей wages будет состоять из модулей с названиями wages-global, wages-core и wages-web.

  • Поле Artifact version позволяет изменить версию проектных артефактов сборки. Если флажок Snapshot отключен, то версия считается финальной сборкой, не snapshot (snapshot - это сборка, которая затем может быть заменена другой сборкой с теми же именем и версией).

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

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

  • Флажок Show unstable versions добавляет в список версий платформы отображение нестабильных версий, оканчивающихся суффиксами BETA или SNAPSHOT.

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

  • Если необходимо изменить путь к серверу приложений, укажите новый путь в поле 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. В редакторе также можно определить и переопределить формат строк для распознавания и форматирования дат.

5.1.2. Зависимости проекта

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

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' вместо него.

Добавление зависимости от JAR файла

Случаются ситуации, когда у вас имеется библиотека в виде JAR-файла, не загруженного в публичные или внутренние Maven репозитории, и вам нужно добавить этот файл как зависимость к вашему проекту. В этом случае вам нужно проделать ручные изменения в скрипте build.gradle.

  • Создайте папку lib в корневом каталоге проекта;

  • Скопируйте JAR файл в этот каталог, например как <my-project>/lib/custom-lib.jar

  • Откройте скрипт сборки Gradle: дерево проектов CUBA → Build Scriptbuild.gradle;

  • Модифицируйте файл build.gradle, добавив элемент flatDir в секцию repositories:

    repositories {
        maven {
            ...
        }
        flatDir {
            dirs "${project.rootDir}/lib"
        }
     }
  • Измените секцию configure(globalModule) файла build.gradle, добавив зависимость и указав имя JAR файла:

configure(globalModule) {
    ...
    dependencies {
        compile(name: 'custom-lib')
    }
}
  • Обновите конфигурацию проекта Gradle: панель инструментов GradleReimport All Gradle Projects;

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

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

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

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

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

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

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

5.1.3.1. Marketplace

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

addons market small

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

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

addon details

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

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

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

addon by coords
5.1.3.3. Установленные аддоны

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

addons installed

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

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

5.1.3.4. Обновления аддонов

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

addons updates

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

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

addon update notification

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

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

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

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

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

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

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

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

Свойства хранилищ данных

Следующие свойства доступны для задания в главном и дополнительных хранилищах данных:

  • Define JDBC DataSource in - определяет компонент системы, ответственный за создание пула соединений к базе данных (доступно для проектов, основанных на CUBA 7.2 или выше). Доступные значения - Application и JNDI.

    • Application - пул соединений создается и управляется платформой CUBA, с использованием библиотеки HikariCP. Это рекомендуемый режим.

    • JNDI - пул соединений создается сервером приложения и кладется в JNDI. CUBA приложение получает пул соединений из регистра JNDI по его JNDI-имени.

  • Database type - тип сервера базы данных. Studio поддерживает PostgreSQL, Microsoft SQL Server, Oracle, MySQL, MariaDB, Amazon RedShift и HSQLDB из коробки. Если необходимо, то возможно сынтегрироваться и с другими СУБД, обращайтесь к этой секции за подробностями.

  • Database URL - укажите хост, порт и имя базы данных.

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

    ;instanceName=myinstance

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

  • Custom database URL - укажите нестандартный URL подключения к БД. Значения Host и Database все равно нужно указать, так как они дополнительно используются для создания БД.

  • Database user и Password - логин и пароль для подключения.

  • Integrated Security - использовать соответствующую опцию аутентификации при подключении к базе данных Microsoft SQL Server 2012+.

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

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

Чтобы создать дополнительное хранилище данных в проекте, кликните правой кнопкой мыши по элементу 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, более подробно см. в основном Руководстве.

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

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

Скрипты создания и обновления БД

Скрипты создания и обновления БД доступны для основного хранилища и отображаются внутри его элемента Main Data Store в дереве проекта:

db scripts
  • Скрипты создания (init) БД содержат DDL и DML операторы, создающие БД с нуля и до состояния схемы, сооветствующего текущему состоянию модели данных.

  • Скрипты обновления (update) БД содержат операторы, которые обновляют уже существующую структуру БД с какого-то из предыдущих состояний до состояния, соответствующего текущему состоянию модели данных.

Studio автоматически поддерживает скрипты создания и обновления БД на основании изменения модели данных, подробнее это описано в секции Работа с базой данных.

Вы также можете создавать дополнительные скрипты БД, если это необходимо. Используйте следующие действия в дереве проекта CUBA, в секции Data StoresMain Data Store:

  • init → контекстное меню → NewDatabase init script

  • update → контекстное меню → NewDatabase update script

new update script

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

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

deployment settings
Сборка WAR файлов

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

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

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

  • 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, чтобы создать этот файл автоматически.

  • Для проектов, основанных на версиях CUBA 7.2 и выше:

    • Custom data store configuration - позволяет переопределить настройки хранилища данных, которые будут установлены для WAR-файла.

  • Для проектов, основанных на версиях CUBA вплоть до 7.1:

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

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

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

Подпункт Build WAR отображается в том случае, если соответствующая опция включена в настройках. Двойной клик по нему запускает задачу gradlew buildWar.

Сборка Uber JAR

Редактор 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, чтобы создать этот файл автоматически.

  • Для проектов, основанных на версиях CUBA 7.2 и выше:

    • Custom data store configuration - позволяет переопределить настройки хранилища данных, которые будут установлены для сборки UberJar.

  • Для проектов, основанных на версиях CUBA вплоть до 7.1:

    • 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.

Подпункт Build UberJAR отображается, если соответствующая опция включена в настройках. Двойной клик по нему запускает задачу gradlew buildUberJar.

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. Работа с перечислениями

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

Перечисления отображаются рядом с сущностями в секции Data Model дерева проекта CUBA.

Создание нового перечисления
  1. Выберите секцию Data Model или пакет внутри неё в дереве проекта и выберите в контекстном меню: New > Enumeration.

  2. Откроется диалог New CUBA Enumeration. Введите название класса перечисления в поле Class, выберите пакет, куда поместить класс и выберите тип Id (рекомендуется String).

create enum
  1. Studio создаст класс перечисления. Созданный класс будет открыт в редакторе исходного кода. В нижней части редактора будут отображены две вкладки:

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

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

enum designer

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

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

  • Столбец Value позволяет ввести id константы представления. Это и есть то значение, которое будет храниться в БД.

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

Дизайнер также предоставляет возможность сменить Id type, используемый представлением с String на Integer и наоборот. Чтобы провести такую миграцию, откройте дизайнер представления и переключите значение Id type. Studio промигрирует использования представления в коде. После этого вам следует изменить значения (Id) существующих констант представления. Заметьте, что такая миграция не обновит данные, уже хранящиеся в таблицах БД, и вам нужно будет реализовать подобную миграцию самостоятельно, например с помощью скрипта обновления БД.

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

Для создания нового представления, или 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.4. Работа с базой данных

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.5. Генерация модели данных

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.6. Поддержка произвольной СУБД

Как описано в документации, вы можете реализовать работу с любой СУБД, поддерживаемой фреймворком 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

Для создания управляемого бина в модуле core, выберите секцию MiddlewareBeans в дереве проекта и выберите в контекстном меню пункт New > Bean:

create bean

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

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

5.3.3. Создание слушателей событий приложения

Слушатель событий - это бин Spring, имеющий один или несколько методов-слушателей, которые принимеют объект Event и содержат реакцию на это событие. Вы можете узнать больше о событиях и слушателях в Руководстве Разработчика.

Studio позволяет генерировать код слушателей для различных событий приложения:

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

Новый класс слушателя

Чтобы сгенерировать новый класс слушателя, выберите секцию Middleware дерева проекта CUBA, а затем выберите пункт контекстного меню NewEvent Listener.

create event listener

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

Добавить метод слушателя к существующему классу

Чтобы добавить метод слушателя к существующему классу, откройте существующий Spring бин и нажмите действие Subscribe to event в верхней панели действий редактора исходного кода:

add listener method

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-дескриптора экрана интегрирован с дизайнером экранов. Дизайнер экранов представляет из себя несколько панелей и боковых панелей IDE (tool window), позволяющих создавать верстку экрана и устанавливать свойства компонентов визуальным образом. Вы можете редактировать XML напрямую или использовать панели дизайнера для генерации кода.

Дизайнер экранов состоит из следующих панелей:

  • Редактор исходного кода - позволяет редактировать исходный XML код.

  • Верхняя панель действий - предоставляет несколько действий для быстрого доступа.

  • Панель предпросмотра верстки (Preview) - отображает схематичное интерактивное представление верстки экрана.

  • Панель иерархии компонентов (Component Hierarchy) - отображает иерархию элементов экрана в виде дерева.

  • Панель палитры компонентов (Component Palette) - отображает набор доступных компонентов, которые можно добавить в текущий экран.

  • Панель свойств компонента (Component Inspector) - отображает и позволяет редактировать свойства компонента и генерировать обработчики событий, связанные с ним.

Tip

Панели дизайнера экранов доступны только для пользователей с активной подпиской CUBA Studio.

screen designer
Верхняя панель действий

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

  • Controller - перейти к контроллеру экрана.

  • <название класса сущности> - отображается, если данный экран является экраном просмотра/выбора или редактором сущности. Позволяет перейти к классу сущности, связанной с данным экраном.

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

Боковые панели дизайнера

Панели Component Hierarchy, Component Palette и Component Inspector реализованы как независимые боковые панели IDE (tool window). Эти панели автоматически появляются, когда вы открываете дескриптор экрана в редакторе. Когда вы переключаете активный файл дескриптора экрана, содержимое боковых панелей обновляется. Иногда, когда вы открываете другие боковые панели IDE (такие как Gradle, Persistence и т.д.), панели дизайнера экранов скрываются, и вы можете переоткрыть их, кликнув по соответствующим кнопкам на левой и правой кромках окна IDE.

Также есть возможность отображать панель Component Inspector в нижнем правом углу окна IDE, для тех пользователей, кто предпочитает старую компоновку, использовавшуюся в предыдущих версиях CUBA Studio. Чтобы переместить эту панель направо, нажмите кнопку Move to Right Bottom, расположенную в заголовке панели.

Панели дизайнера остаются активными и при редактировании XML кода. Опытные разработчики, которые просматривают и меняют дескрипторы экранов прямым редактированием XML кода, также могут воспользоваться возможностями панелей дизайнера экранов. Вы можете добавлять компоненты из палитры в панель иерархии, переупорядочивать компоненты и редактировать свойства компонентов в панели Component Inspector, когда в редакторе открыт исходный код. Все изменения немедленно применяются к исходному коду.

Панель предпросмотра верстки

Панель предпросмотра верстки (Preview) отображает схематичное интерактивное представление верстки экрана. Она разделяет пространство редактора с исходным кодом дескриптора экрана. В правой части верхней панели дескриптора экрана находятся четыре кнопки, которые переключают режим отображения предпросмотра:

  • Editor only - редактор содержит только исходный код.

  • Editor and Preview - пространство редактора разделено пополам между исходным кодом и панелью предпросмотра.

  • Preview only - весь редактор занят панелью предпросмотра.

  • Preview in Window - редактор содержит исходный код, а панель предпросмотра выделена в независимое окно, которое можно переместить на другой монитор.

layout preview modes

В верхней правой части панели также находятся несколько элементов управления:

layout preview controls
  • Выпадающий список 100% x 100% позволяет вам выбрать фиксированный размер канвы. Размер канвы может быть больше, чем размер панели предпросмотра, в этом случае добавляются дополнительные полосы прокрутки. Например если вы разрабатываете сложный экран с большим количеством компонентов и хотите оценить предварительный вид экрана, вы можете выбрать размер канвы 1920 x 1080 и увидеть, как верстка выглядит на большом экране.

  • Кнопка Refresh перезагружает содержимое страницы предпросмотра.

  • Кнопки Zoom In, Zoom Out и Zoom Reset изменяют масштаб на странице предпросмотра.

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

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

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

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

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

layout component controls
Палитра компонентов

Панель палитры компонентов (Component Palette) расположена в нижнем правом углу IDE. Она отображает набор доступных элементов экрана:

  • Контейнеры (Containers);

  • Компоненты (Components);

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

  • Невизуальные элементы (Non-visual): действия, настройки диалогового окна, таймеры и другие вспомогательные элементы экрана;

  • Главный экран (Main window): составные компоненты главного экрана приложения.

Компоненты в палитре можно искать по имени с помощью текстового поля поиска.

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

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

  • Add to Design - добавляет выбранный компонент на экран, помещая его в место, соответствующее выбранному элементу иерархии.

  • CUBA Documentation - открывает страницу документации по выбранному компоненту в руководстве разработчика.

component palette
Панель иерархии компонентов

Панель иерархии компонентов (Component Hierarchy) расположена в верхнем правом углу окна IDE. Она отображает дерево элементов экрана.

Элементы дерева можно перетаскивать с места на место.

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

  • Convert - конвертировать компонент в один из похожих альтернативных компонентов.

  • Wrap - обернуть компонент в один из предлагаемых контейнеров.

  • Go to XML - перейти к XML тегу в исходном коде.

  • Inject - инжектировать элемент в контроллер экрана или перейти к уже существующему определению в классе контроллера.

  • Delete, Copy, Cut, Paste - удалить, скопировать, вырезать, вставить элемент.

  • CUBA Documentation - открыть страницу документации для выбранного компонента.

component hierarchy
Панель свойств компонента

Панель свойств компонента (Component Inspector) расположена в нижнем левом углу окна IDE. Она отображает и позволяет редактировать свойства выбранного элемента экрана:

  • Вкладка Properties отображает свойства компонента.

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

Вы можете искать атрибуты по имени с помощью поля поиска:

component inspector

Для некоторых видов выбранных элементов панель отображает кнопку + Add, которая позволяет быстро добавить связанные по смыслу под-элементы, такие как действие таблицы, столбец таблицы или поле формы. Если выбранный элемент - это:

  • Table, Grid или их действия или колонки - то доступны действия AddColumn, AddGroup, AddAction.

  • Form или колонка или поле формы - доступны действия AddColumn, AddField.

  • DataLoadCoordinator - доступно действие AddonScreenEvent trigger и другие триггеры.

component inspector add button
Статический анализ кода (Inspections)

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

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

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

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

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

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

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

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

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

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

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

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

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

  • и другие проблемы.

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

Намерения (Intentions) и меню Generate

Intention-действие ("намерение") - это контекстно зависимое действие (зависит от позиции курсора), которое может быть запущено разработчиком из редактора исходного кода по нажатию Alt+Enter (Option+Enter). Intention-действия помогают с рефакторингами, генерацией кода, навигацией по коду и другими задачами. Вы можете прочитать больше об intention-действиях здесь: https://www.jetbrains.com/help/idea/intention-actions.html.

Меню Generate содержит контекстно зависимые действия, помогающие генерировать различные конструкции кода. Это меню может быть вызвано из редактора исходного кода нажатием Alt+Insert (Cmd+N). Дополнительная информация об этом меню находится здесь: https://www.jetbrains.com/help/idea/generating-code.html.

Многие intention-действия и элементы меню Generate, встроенные в Studio, помогают работать с компонентами экранов. Используйте Alt+Insert (Cmd+N) и Alt+Enter (Option+Enter), чтобы исследовать возможности работы с конкретными компонентами UI и источниками данных.

  1. Например, чтобы добавить новое поле в компонент Form, вы можете поместить курсор во внутрь элемента form и выполнить одно из следующих действий:

    • Нажать Alt+Insert (Cmd+N), выбрать Add field, а затем выбрать значение атрибута property,

      gui Form add
    • Ввести field и нажать TAB, затем выбрать значение атрибута property.

      gui Form add tab
  2. Другой пример - добавление локализованной подписи к одному из компонентов. Вы можете набрать в исходном коде ключ локализованного сообщения, которое ещё не существует. Указывающий на сообщение элемент окажется подсвечен красным цветом. Затем нажмите Alt+Enter (Option+Enter) и выберите Create message in the message bundle:

    intention add localized message

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

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

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

controller
Верхняя панель действий

Панель действий расположена в верхней части редактора исходного кода класса. Она отображает следующие действия:

  • <название класса сущности> - перейти к сущности, связанной с текущим экраном, если это экран просмотра/выбора или редактор сущности.

  • Descriptor - перейти к соответствующему дескриптору экрана

  • Main Menu - добавить текущий экран в главное меню или перейти к настройкам уже добавленного пункта меню.

  • Inject - инжектировать зависимости в класс контроллера экрана, см. ниже.

  • Subscribe to Event - подписать контроллер на различные события, см. ниже.

  • Install Delegate - генерировать методы-делегаты компонентов, см. ниже.

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

Механизм Dependency injection - это основной способ получения ссылок на визуальные компоненты и элементы API в коде контроллера экрана. Конечно, вы можете описать поле нужного типа и аннотировать его вручную, но Studio предоставляет возможность выбрать нужный объект из списка в специальном окне, чтобы создать требуемое поле автоматически. Это окно можно открыть:

  • выбрав действие Inject из верхней панели действий,

  • или нажав Alt+Insert (Cmd+N), далее нужно выбрать пункт Inject…​ в выпадающем меню Generate:

controller injection

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

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

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

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

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

  • Прочие Spring-бины, определенные в проекте,

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

  • Экземпляр SLF4J Logger.

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

Создав обработчик некоего события, вы можете выполнять его код на разных этапах жизненного цикла экрана, например, реагировать на действия пользователя. Обработчик представляет собой отдельный метод в контроллере экрана с аннотацией @Subscribe, принимающий событие в качестве параметра. Такой метод можно создать в Studio:

  • кликнув действие Subscribe to Event из верхней панели действий,

  • или нажав Alt+Insert (Cmd+N) и выбрав Subscribe to Event в меню Generate:

subscribe dialog

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

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

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

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

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

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

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

Делегаты

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

Делегат представляет собой метод контроллера экрана со специальной подписью и аннотацией @Install. Такой метод также можно создать в Studio:

  • кликнув действие Install Delegate из верхней панели действий,

  • или нажав 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

6. Интеграция с IntelliJ IDEA Ultimate Edition

IntelliJ IDEA Ultimate Edition - это платная среда разработки, включающая в себя множество дополнительных функций, полезных для разработки CUBA приложений: поддержка CSS и JavaScript, JPA, Spring, Docker, подключение к БД и другие.

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

6.1. Отключение конфликтующих функций

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

  • Откройте главное меню > Settings > Editor > General > Gutter Icons,

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

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

6.2. Включение функций поддержки JPA

Поддержка стандарта JPA (Java Persistence Annotation) предоставляется плагином Java EE: EJB, JPA, Servlets.

Warning

Функциональность, описанная ниже, недоступна в CUBA Studio IDE или в IntelliJ IDEA Community Edition.

Поддержка JPA стандарта предоставляет следующие функции, полезные для разработки CUBA приложений:

  • JPQL запросы: подсветка синтаксиса, автодополнение и инспекции,

  • Консоль JPQL запросов (JPA Console, для проектов основанных на CUBA 7.1 или выше),

  • Инспекции исходного кода сущностей,

  • ER диаграмма,

  • Другие возможности, описанные на сайте JetBrains.

Чтобы воспользоваться этими возможностями, вам нужно настроить две вещи в вашем проекте:

  • Настроить Data Source для базы данных, соответствующей главному хранилищу данных,

  • Добавить JPA фасеты (facet) для всех модулей проекта.

Studio помогает быстрее выполнить обе эти задачи. Инструкции в следующих секциях актуальны для версии IDEA 2019.2.

6.2.1. Настройка Data Source

Вы можете настроить Data Source (источник данных) вручную с помощью окна инструментов (tool window) Database, расположенного на правой кромке окна IDE. Но Studio предоставляет и автоматическое обнаружение источника данных при открытии проекта:

datasource notification

Если вы пропустили уведомление, оно также записывается в окно инструментов Event Log, которое можно открыть, нажав на соответствующую кнопку в правом нижнем углу экрана.

Нажмите Configure, и откроется предзаполненный диалог Data Sources and Drivers.

add ds dialog

Механизм обнаружения источника данных автоматически определяет параметры на основании настроек главного хранилища данных и заполняет параметр Driver и другие свойства подключения. Вам нужно только настроить драйвер базы данных в диалоге "Data Sources and Drivers":

  • Нажмите ссылку Download missing driver files в нижней части диалога. Файлы драйвера будут скачаны автоматически.

  • Нажмите Test Connection, чтобы убедиться, что настройки подключения определены корректно. Измените их если необходимо.

  • Поменяйте значение поля Save на Forever. Иначе пароль будет забыт после перезапуска IDE.

  • Закройте диалог, выбрав кнопку OK.

Если JPA фасеты уже созданы, назначьте для них созданный Data Source, открыв окно инструментов Persistence. Правый клик мыши по каждому фасету → Assign Data Sources…​ → сменить Data Source → OK.

6.2.2. Настроить JPA фасеты

Каждый модуль в проекте должен иметь настроенный JPA фасет, иначе возможности, связанные с JPQL запросами, не будут доступны в этом модуле.

Автообнаружение JPA фасетов

Studio помогает вам, автоматически обнаруживая фасеты. При первом открытии проекта вы увидите уведомление Frameworks Detected в правом нижнем углу окна IDE:

facet detection

Если JPA фасеты уже были настроены в вашем проекте, уведомление не появится. Чтобы получить уведомление, вы можете открыть диалог из главного меню → FileProject Structure и удалить существующие фасеты. Затем переоткройте проект и выполните обновление проекта Gradle (окно инструментов Gradle → кнопка Reimport All Gradle Projects).

Если вы пропустили уведомление, оно также записывается в окно инструментов Event Log:

event log

Нажмите ссылку Configure, и откроется диалог Setup Framework.

Снимите флажки с элементов группы Web и нажмите OK:

setup frameworks

Чтобы проверить, что фасет настроен корректно, откройте окно инструментов Persistence, расположенное на левой кромке окна IDE . Затем раскройте один из узлов, например тот, что относится к модулю app-global, и раскройте под-узел Entities. Вы должны увидеть список сущностей, определенных в вашем проекте или унаследованных из аддонов:

persistence tool window
Ручная настройка JPA фасета

Можно также настроить JPA фасеты вручную через диалог FileProject Structure.

  • Откройте диалог Project Structure,

  • Выберите пункт Facets в левом меню,

  • Удалите все существующие фасеты JPA,

  • Для всех модулей вашего проекта: global, core, gui, web, portal - проделайте следующие действия:

  • Нажмите иконку "+" (Add),

  • Выберите тип фасета JPA,

  • Выберите под-модуль с названием, оканчивающимся на "main", например "sample-sales.app-global.main". Нажмите OK.

  • В нижней правой части диалога поменяйте Default JPA Provider на CUBA EclipseLink.

  • Повторите эти шаги для других модулей.

Tip

Не забудьте поменять поле Default JPA Provider на CUBA EclipseLink, иначе консоль JPA запросов не будет работать.

add facet manually

6.2.3. Примеры возможностей

JPQL запросы: подсветка синтаксиса, автодополнение и инспекции - работают в Java и XML файлах для модулей, где JPA фасет сконфигурирован:

jpql highlighting
jpql java

Entity-relation (ER) диаграмму можно открыть из окна инструментов Persistence: правый клик по любому модулю → EntitiesER Diagram. Возможно вы захотите включить опцию Superclasses вверху диаграммы, чтобы отключить показ общих базовых классов:

er diagram
JPA консоль
Tip

JPA консоль доступна только для проектов, использующих 7.1 или более позднюю версию CUBA.

JPA консоль открывается через окно инструментов Persistence: развернуть любой модуль → выделить пункт Entities и затем нажать кнопку Console:

jpa console button

Окно консоли откроется. Теперь вы можете выполнять JPQL запросы на БД, подключенной к проекту:

jpa console