5.5.11. Собственные визуальные компоненты

В данном разделе содержится обзор различных способов создания собственных визуальных компонентов в CUBA-приложениях. Практическое руководство по использованию этих подходов содержится в разделе Создание собственных визуальных компонентов.

Новый визуальный компонент может быть создан с помощью следующих технологий:

  • На основе Vaadin add-on.

    Это простейший способ, требующий следующих шагов:

    • Добавить в build.gradle зависимость от артефакта аддона.

    • Создать в проекте модуль web-toolkit. Данный модуль содержит файл виджетсета GWT и позволяет создавать клиентские части визуальных компонентов.

    • Подключить виджетсет аддона в виджетсет проекта.

    • Если требуется адаптировать внешний вид компонента к теме приложения, создать расширение темы и задать для компонента нужный CSS.

    См. пример в разделе Подключение аддона Vaadin.

  • Как обертка библиотеки на JavaScript.

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

    • Создать в модуле web серверный компонент Vaadin. Серверный компонент определяет API для серверного кода, методы доступа, слушатели событий и т.д. Серверный компонент должен быть унаследован от класса AbstractJavaScriptComponent. Модуль web-toolkit для интеграции JavaScript-компонента не требуется.

    • Создать JavaScript-коннектор. Коннектор - это функция, которая инициализирует JavaScript-компонент и ответственна за взаимодействие между JavaScript и server-side кодом.

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

    См. пример в разделе Подключение JavaScript библиотеки.

  • В виде нового компонента GWT.

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

    • Создать в проекте модуль web-toolkit.

    • Создать класс клиентского виджета GWT.

    • Создать серверный компонент Vaadin.

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

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

    • Создать интерфейс RPC, который определяет серверный API, вызываемый клиентом.

    См. пример в разделе Создание GWT компонента.

  • Как ресурс WebJar.

    Данный метод позволяет использовать различные JavaScript-библиотеки, упакованные в JAR-файлы и развёрнутые в Maven Central. Для подключения библиотеки к приложению требуется следующее:

    • Добавить зависимость в метод compile модуля web:

      compile 'org.webjars.bower:jrcarousel:1.0.0'

    • Создать в проекте модуль web-toolkit.

    • Создать класс клиентского виджета GWT и реализовать в нём native JSNI метод для создания компонента.

    • Создать класс серверного компонента с аннотацией @WebJarResource.

      Аннотация может использоваться только с наследниками ClientConnector (которые обычно являются классами компонентов UI в модуле web-toolkit). Значением аннотации @WebJarResource должен быть путь к ресурсу следующего вида:

      <resource_name>/<resource_version>/<resource>

      Оно может содержать одно или более строковых определений ресурсов WebJar:

      @WebJarResource({
        "jquery-ui/1.12.1/jquery-ui.min.js",
        "jquery-fileupload/9.12.1/jquery-fileupload.min.js",
        "jquery-fileupload/9.12.1/jquery-fileupload.min.js"
})
public class CubaFileUpload extends CubaAbstractUploadComponent {
    ...
}

    • Добавить новый компонент к экрану.

Степень интегрированности визуального компонента в платформу можно разделить на три уровня:

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

  • На втором уровне новый компонент интегрируется в универсальный пользовательский интерфейс платформы. В этом случае, с точки зрения прикладного разработчика, компонент выглядит так же как и стандартный компонент из библиотеки визуальных компонентов. Разработчик может определить компонент в XML-дескрипторе экрана или создать его с помощью ComponentsFactory в контроллере. См. пример в разделе Подключение аддона Vaadin с интеграцией в Generic UI.

  • На третьем уровне новый компонент доступен в палитре компонентов WYSIWYG-дизайнера экранов Studio. См. пример в разделе Поддержка собственных компонентов в CUBA Studio.