Опыт внедрения Directum Portal

Опубликовано:
19 января в 08:56

2 0

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

Пример нашего портала

Рис. Главная страница

Рис. Страница Новости

Рис. Страница Сотрудники

Рис. Страница Календарь

Рис. Страница Развитие

Что же такое Directum Portal? В самом простом понимании это no-code конструктор для сложных корпоративных сайтов и порталов. Мы формируем страницу, перетаскивая мышкой готовые виджеты и элементы. В основе Directum Portal лежит Liferay, главной особенностью которого является возможность объединять данные из разных систем в едином удобном интерфейсе.

Установка Liferay на Windows

Рассмотрим развертывание Liferay именно на Windows, так как установка docker-образов подробно описана в документации к порталу. Также наиболее удобно вести всю разработку на одной виртуальной машине, а среда разработки Directum RX работает только под Windows.

Подготовка к установке:

Установить Java Development Kit 17 или 21 версии;
Настроить системные переменные: JAVA_HOME и JRE_HOME;

Пример:

JAVA_HOME: C:\Program Files\Microsoft\jdk-11.0.26.4-hotspot
JRE_HOME: %JAVA_HOME%

Скачать архив Tomcat по ссылке и распаковать в папке, которая станет корнем портала.

Для запуска портала открываем командную строку, переходим в папку с разархивированным порталом и выполняем команду startup. В итоге портал запустится на 8080 порту. Далее задаем основные настройки, если нужно указываем подключение к базе данных Postgres или MySQL.

Рис. Пример настроек

В результате получаем чистый Liferay.

Рис. Стартовая страница

Для приведения чистого Liferay к виду Directum Portal нам понадобится развернутый портал из docker-образов. Последовательность действий:

На linux-сервере с установленным Directum Portal переходим в папку mnt;
Копируем все модули с расширением jar, а также тему с расширением war и переносим их в папку deploy нашего Liferay;
На сайте развернутого из docker-образов, переходим в раздел Language Override и экспортируем перевод;
На нашем стенде также переходим в Language Override и импортируем ранее полученный файл;
В Instance Settings переходим в Localization и выбираем русский язык в качестве доступного, а также устанавливаем его в качестве основного;
Также в Instance Settings переходим в раздел Instance Configuration и устанавливаем тему Directum по умолчанию;
В карточке пользователя меняем язык на русский;
Применяем тему Directum к страницам, для этого переходим в раздел Страницы сайта и в Конфигурации выбираем нужную нам тему.

Видео с примером настройки:

Виджеты

Что такое виджет в Liferay? В общем смысле виджет — это независимый модуль или компонент, который выполняет определенную функцию и который пользователь может разместить на странице портала. За время внедрения было реализовано множество виджетов: Дни рождения, События из календарей, RSS лента, Отображение оргструктуры, Карточка сотрудника, Недавние комментарии к статьям, Бронирование переговорок и т.д.

Примеры реализованных виджетов:

Рис. Дни рождения

Рис. Карточка сотрудника

Рис. Библиотека

Создание виджета на JavaScript

Подготовка:

Установите Node.js (информация по совместимости версий);
Установите генератор Yeoman;

Команда для установки:

npm install –global yo@4.3.1

Установите генератор Liferay JS, для создания проектов под Liferay.

Команда для установки:

npm install -global generator-liferay-js

Создание проекта:

В командной строке: yo liferay-js;
Выбираем фреймворк на котором будем реализовывать виджет: JavaScript, Angular, React, Vue.js, Metal.js;
Задаем наименование проекта;
Указываем нужна ли локализация и поддержка конфигурации;
Задаем категорию, в которой будет находиться виджет.

Рис. Пример создания проекта

В результате будет создан проект с следующей структурой:

my-react-portlet-bundle
- assets/ → CSS и ресурсы
  - css/ → CSS файлы
    - styles.css → Базовый CSS файл
  - Images/ → Картинки
- features/ → Дополнительный возможности Liferay
  - localization → Файлы локализации
    - Language.properties → Базовый файл локализации
  - configuration.json → Конфигурация виджета
- src/ → JavaScript файлы
  - AppComponent.js → Базовый файл
  - index.js → Основной файл для инициализации виджета
- .babelrc → Конфигурация Babel
- .npmbuildrc → Конфигурация для локального запуска
- .npmbundlerrc → Конфигурация сборки
- package.json → Конфигурация библиотек

Описание файлов

configuration.json

В файле конфигурации можно создать системные настройки (system), которые будут влиять сразу на все экземпляры виджета, а также можно добавить экземплярные настройки (portletInstance), которые устанавливаются конкретно для каждого виджета. Например, есть 2 страницы и на каждой используется один и тот же виджет, в таком случае Системные настройки будут работать сразу на оба виджета, а экземплярные настройки у каждого виджета уникальны.

Рис. Пример файла configuration.json

Далее будут продемонстрирована настройка виджета на портале.

Видео: Системная настройка

Видео: Конфигурация виджета

Language.properties

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

Рис. Файл локализации

Чтобы использовать локализованные строки у себя в коде, их нужно получать через следующую функцию Liferay.Language.get("key"). Также можно использовать общие ключи локализации, которые созданы через no-code.

Рис. Путь до Language Override

Рис. Ключ локализации

.babelrc

Используются для конфигурации сборщика зависимостей npm, который оптимизирует JavaScript, применяя пресеты (presets) и плагины, чтобы управлять зависимостями модулей и избегать конфликтов имен. Важный момент заключается в том, что при использовании async и await в коде необходимо добавить плагин transform-runtime.

Рис. Файл babelrc

.npmbundlerrc

Данный файл содержит основные настройки сборки проекта, такие как путь до собираемого jar файла, доступность виджета, пути до локализации и конфигурации, а также признаки необходимости генерации отчетов. Например, если dump-report включен, то при сборке будет создаваться файл с подробным описанием состава проекта.

Описание параметров:

create-jar - Настройки упаковки проекта в JAR
- output-dir - Папка, куда будет собран JAR-файл
- features – Дополнительные параметры
  - js-extender – Признак доступности виджета для выбора
  - web-context - Базовый URL, по которому будет доступно приложение
  - Localization - Путь к файлам локализации (переводы интерфейса)
  - Configuration - Путь к конфигурационному файлу
dump-report - Генерация отчёта о сборке
verbose – Признак генерации подробного лога

Рис. Файл npmbundlerrc

Сборка и публикация виджета

Если при создании виджета был указан путь до локального Liferay, то опубликовать можно при помощи команды npm run deploy. Если же нужно опубликовать виджет на другой сервер, то в терминале вводим команду npm run build, в итоге собирается jar файл, который необходимо перенести в папку deploy на сервере.

Важный момент, по оптимизации заключается в том, что нужно использовать максимально легкие библиотеки, так как чем больше будет весить ваш виджет, тем дольше он будет загружаться на странице портала. Исходя из этого, размер виджета не должен превышать 1 МБ. Также, если вы будете использовать react в вашем виджете, то он уже по стандарту доступен в самом Liferay, для этого нужно подключить библиотеку liferay/portal7.4, которая включает большинство часто используемых библиотек, но там 16 версия react. Если нужна более новая версия или какая-то специфичная библиотека, которая будет использоваться сразу в нескольких виджетах, то потребуется создать проект с общими зависимостями (Shared Bundle).

Shared Bundle

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

Создание проекта:

В командной строке: yo liferay-js;
Выбираем Shared Bundle;
Задаем наименование проекта;
Указываем нужна ли локализация;
Задаем путь до локального liferay;
Указываем нужна ли инициализация. Обычно инициализация нужна только если планируется сконфигурировать библиотеки;
После этого добавляем все необходимые зависимости через npm и собираем проект.

Рис. Пример создания общего пакета

После создания общего пакета, нужно начать использовать библиотеки именно из него. Для этого в файле npmbundlerrc добавляем раздел config в котором указываем какие библиотеки будем импортировать. А в файле package.json данные библиотеки нужно перенести из раздела dependencies в раздел devDependencies, чтобы они не попали в jar и не увеличили размер виджета.

Рис. Пример настроенного файла npmbundlerrc

Общие сведения

Несколько css файлов

Если в виджете используется много визуала, то может возникнуть ситуация, когда будет не удобно использовать 1 css файл. В таком случае нужно указать пути до всех css файлов в package.json в виде массива строк.

Рис. Пример указания нескольких css файлов

Картинки

Если в виджете будут использоваться картинки, то в папке assets нужно создать новую папку images и хранить картинки именно там. Для того чтобы обратиться к этим картинкам нужно использовать свойство contextPath.

Рис. Дерево файлов

Рис. Пример использования

Передача данных между виджетами

Допустим у нас есть несколько виджетов которые должны обмениваться данными между собой. Для таких случаев в Liferay есть система событий. Liferay.fire позволяет отправлять данные в виде объекта. А Liferay.on работает как подписка на события, с заданным наименованием. Важно при переключении страниц удалять подписки на события, для этого используется метод Liferay.detach.

Рис. Пример отправки события

Рис. Пример подписки на событие

Текущий контекст

Для получения информации о текущем контексте используется объект Liferay.ThemeDisplay. При помощи него можно, например получить информацию о пользователе, о сайте, об url, о локализации и т.д.

Основные методы:

Информация о пользователе

getUserId() - ID текущего пользователя
getUserEmailAddress() - email текущего пользователя
isSignedIn() - проверка, авторизован ли пользователь

Информация о группах

getSiteGroupId() - ID сайта
getCompanyId() - ID компании

URL и пути

getURLHome() - URL домашней страницы
getPortalURL() - базовый URL портала

Язык и локализация

getLanguageId() - ID языка (например, "en_US")

Рис. Пример использования Liferay.ThemeDisplay

Liferay API

В Liferay есть два основных типа API для работы с данными и сервисами: Rest Api и JSONWC.

REST API

Доступен по адресу /o/api, по которому откроется swagger с описанием всех доступных методов.

Рис. Swagger

Из плюсов можно выделить REST-подход, а также то, что запросы можно выполнять прямо в swagger, но не все сервисы доступны через данный API, так, например, работа с календарем недоступна по REST API.

Рис. Пример использования REST API

JSONWC

Доступен по адресу /api/jsonws, по которому откроется веб интерфейс с описанием методов.

Рис. Веб интерфейс

Данный тип использовался в Liferay с самого начала, из-за этого он поддерживает практически все базовые сервисы, такие как календари, новости, форумы и т.д. Из особенностей можно выделить то, что этот тип работает только через POST запросы.

Рис. Пример использования JSONWC

Возможности визуального конструктора

Визуальный конструктор позволяет создавать и настраивать страницы портала, перетаскивая готовые элементы (блоки, поля) в графическом интерфейсе. Помимо этого, можно указать CSS как для отдельных объектов на странице, так и для всего сайта сразу, также можно добавить свой JavaScript код на страницы.

Настройка CSS

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

Последовательность действий:

Открываем код страницы (F12);
Находим нужный элемент, в данном случае это navbar;
Переходим в редактирование страницы;
Выбираем наш виджет и переходим во вкладку advanced;
Добавляем нужный css код, в данном случае это display: none для класса navbar;
Применяем настройки.

Видео: Демонстрация настройки css

Добавление JS кода

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