Миграция с Classic UI

Вследствие несовместимости между Classic и Flow UI автоматическое обновление с Jmix 1.5 Classic UI до Jmix 2.0 невозможно. В этом разделе приведена инструкция по апгрейду приложения на основе Jmix 1.5 Classic UI вручную.

Преобразование в проект на Flow UI

Сначала необходимо удалить Classic UI из проекта и адаптировать структуру проекта и скрипты сборки к Flow UI.

  1. Откройте проект на Classic UI в IDE.

    Далее мы будем называть этот проект "мигрирующим".

  2. Создайте новый проект на последней версии Jmix 1.5 в другом каталоге, используя шаблон Full-Stack Application with Incubating FlowUI. Выберите то же имя и базовый пакет, что и в мигрирующем проекте.

    Далее мы будем называть этот проект "созданным".

  3. Скопируйте следующие файлы из корневого каталога созданного проекта в мигрирующий:

    .gitignore
.npmrc
.pnpmfile.cjs
build.gradle
package.json
tsconfig.json
types.d.ts
vite.config.ts

    Здесь и далее производите копирование, выполнив команду Copy в окне инструментов Project исходного проекта, а затем команду Paste на соответствующем узле целевого проекта.

  4. Добавьте стартеры используемых дополнений в секцию dependencies файла build.gradle, руководствуясь инструкциями по ручной установке этих дополнений.

    Если какое-либо дополнение не реализовано в Jmix 1.5, но доступно в 2.0 (например, Reports), вы сможете добавить его после апгрейда проекта до Jmix 2.0. В этом случае будьте осторожны при первом старте приложения без зависимости на дополнение - убедитесь, что сгенерированные файлы Liquibase changelogs не содержат команд удаления таблиц дополнения. Подробнее эта ситуация описана ниже.

  5. В мигрирующем проекте удалите следующие каталоги (выключите Safe delete чтобы избежать бесполезных предупреждений от IDE):

    1. src/main/java/<base_package>/screen

    2. src/main/resources/<base_package>/screen

    3. src/main/themes

    4. src/main/resources/<base_package>/theme

  6. Скопируйте следующие каталоги из созданного проекта в мигрирующий:

    1. frontend

    2. src/main/java/<base_package>/view

    3. src/main/resources/<base_package>/view

    4. src/main/resources/META-INF

  7. В файле application.properties мигрирующего проекта:

    1. Удалите свойства jmix.ui.*.

    2. Скопируйте свойства jmix.flowui.*, ui.*, vaadin.* из созданного проекта в мигрирующий.

  8. Скопируйте файл src/main/resources/<base_package>/menu.xml из созданного проекта в мигрирующий и перезапишите существующий файл.

  9. Откройте файл src/main/resources/<base_package>/messages_en.properties мигрирующего проектв и удалите сообщения <base_package>.screen.* и <base_package>/menu.application. Скопируйте сообщения <base_package>.view.* и <base_package>/menu.application.title из такого же файла созданного проекта.

  10. Скопируйте классы FullAccessRole и UiMinimalRole пакета <base_package>.security из созданного проекта в мигрирующий.

  11. В других имеющихся ролях мигрирующего проекта удалите аннотации io.jmix.securityui.role.annotation.MenuPolicy и io.jmix.securityui.role.annotation.ScreenPolicy.

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

    @Push
@Theme(value = "<project_name>")
@PWA(name = "<project_name>", shortName = "<project_name>")
class ... implements AppShellConfigurator

    Например:

    // ...
import com.vaadin.flow.component.page.AppShellConfigurator;
import com.vaadin.flow.component.page.Push;
import com.vaadin.flow.server.PWA;
import com.vaadin.flow.theme.Theme;
// ...

@Push
@Theme(value = "onboarding")
@PWA(name = "Onboarding", shortName = "Onboarding")
@SpringBootApplication
public class OnboardingApplication implements AppShellConfigurator {

  13. Выполните команду Build → Build Project и устраните ошибки компиляции, если они возникнут.

  14. Запустите приложение.

    1. Studio отбразит окно Liquibase Root Changelog Check и предложит удалить команды include, ссылающиеся на модули, которых нет в проекте Jmix 1.5 Flow UI (например, /io/jmix/uidata/liquibase/changelog.xml). Примите предложенные изменения и продолжите.

    2. Studio создаст Liquibase changelog с командами для удаления таблиц UI_FILTER_CONFIGURATION, UI_SETTING и UI_TABLE_PRESENTATION. Эти команды следует сохранить и применить, так как данные таблицы не содержат никаких полезных данных для Flow UI.

    3. Если в базе данных есть таблицы дополнений, отсутствующих в Jmix 1.5, убедитесь что эти таблицы не будут удалены. Либо нажмите Remove from Changelog → Remove and Ignore для соответствующего узла с командой dropTable в окне генерации файлов Liquibase changelog, либо отмените процесс и добавьте свойство main.datasource.studio.liquibase.exclude-prefixes перед тем как запускать приложение снова. Например:

      main.datasource.studio.liquibase.exclude-prefixes = REPORT_

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

Разработка новых экранов

На данный момент вы получили работающее приложение, основанное на Jmix 1.5 с Flow UI. Его пользовательский интерфейс включает в себя только экраны, предоставляемые шаблоном нового приложения: LoginView, MainView, UserListView и UserDetailView.

Следующие шаги:

  1. Обновите проект до версии Jmix 2.0, используя стандартную процедуру апгрейда проекта в Studio.

  2. Создайте CRUD-экраны для объектов вашей модели данных, используя Мастер создания экранов.

В результате у вас получится приложение со старой моделью данных и бэкенд-логикой, а также с новым пользовательским интерфейсом, который позволяет управлять данными с помощью стандартных экранов списка/деталей. Теперь вам нужно кастомизировать пользовательский интерфейс, используя Flow UI API и его набор компонентов.