В ELMA365 с помощью модулей расширения вы можете реализовать просмотр и редактирование типов файлов, которые не поддерживаются в системе по умолчанию.
Например, на странице оформления заказа вы хотите разместить не только текстовое описание, но и схемы монтажа оборудования в формате .djvu. По умолчанию в системе нельзя просматривать файлы такого типа, но вы можете создать пользовательский модуль, который позволит это делать.
начало внимание
Создавать и настраивать модули могут только пользователи, включённые в группу Администраторы.
конец внимание
Архитектура
Модуль состоит из следующих основных частей: параметры конфигурации, виджет Страница предпросмотра и методы API.
Параметры конфигурации определяют поведение модуля в целом. Это могут быть, например, поддерживаемые форматы файлов, адрес сервера просмотра, язык интерфейса и т. д.
Логика просмотра и редактирования реализована в виджете Страница предпросмотра с помощью клиент-серверных сценариев.
Методы API в составе модуля обеспечивают обмен данными с внешним приложением.
Создание и настройка модуля
Чтобы создать новый модуль, перейдите в Администрирование > Модули, нажмите кнопку +Модуль. В открывшемся окне выберите опцию Создать. Заполните информацию о модуле и нажмите кнопку Создать. Подробнее об этом читайте в статье «Создание модуля».
Добавление параметров для подключения модуля
На вкладке Настройки можно создавать, редактировать и удалять общие параметры модуля, которые отображаются на странице подключения модуля в разделе Администрирование.
Например, вы можете вынести на страницу настроек модуля поля с выбором поддерживаемых форматов файлов, переключением режима открытия файлов и адресом стороннего сервера просмотра файлов.
Для создания полей перейдите на вкладку Настройки и нажмите кнопку + Добавить.
В открывшемся окне заполните поля. Например, создайте свойство типа Категория и в качестве значений добавьте наименования форматов. Затем нажмите кнопку Создать.
После этого добавленное свойство будет отображаться на странице подключения модуля.
Параметры являются глобальными — они применяются ко всем файлам в системе, которые просматриваются или редактируются с помощью модуля.
В настройки расширения рекомендуется включать выбор поддерживаемых типов файлов и ввод параметров соединения с внешним приложением для просмотра и редактирования.
При необходимости вы можете изменить стандартную форму представления настроек, например, скрыть часть полей. Для этого на вкладке Настройки нажмите кнопку Изменить форму. В открывшемся дизайнере интерфейсов вы можете изменить форму настройки. Подробнее об этом читайте в статье «Настройки модуля».
Методы API
На вкладке Методы API добавляются методы обмена данными с внешним сервером. Если в создаваемом модуле не предусматривается возможность обмена данными, добавлять методы не нужно.
Например, вы можете создать POST-запрос callback
, который при редактировании документа будет получать с внешнего сервера текущий статус этого документа и добавлять его новую версию в ELMA365. Исходный код метода, который можно добавить, приведён в подразделе «Пример интеграции с внешним средством просмотра и редактирования файлов».
Виджет предпросмотра
Виджет предпросмотра является главным компонентом модуля. В нём осуществляется обмен данных между ELMA365 и внешним приложением. Чтобы создать виджет:
- Перейдите в настройках модуля на вкладку Виджеты.
- Нажмите кнопку +Виджет.
- В открывшемся окне задайте следующие параметры:
- Название* — укажите название виджета;
- Код виджета* — задайте идентификатор для виджета;
- Расширение — выберите группу Предпросмотр файлов. Укажите тип Страница предпросмотра.
- Нажмите кнопку Сохранить.
После этого откроется дизайнер интерфейсов, в котором можно настроить виджет.
В контексте виджета по умолчанию созданы следующие свойства:
- File — свойство типа Файл. Документ, который открывается модулем просмотра и редактирования;
- Action — свойство типа Строка. Режим открытия документа: только просмотр, просмотр и редактирование. Может принимать значения
view
иedit
; - Extension — свойство типа Строка. Расширение файла из свойства File.
Эти переменные отображаются на правой панели дизайнера интерфейса на вкладке Свойства.
Рассмотрим пример использования контекста виджета. Создадим метод, который будет проверять в клиентском сценарии, поддерживается ли модулем просмотр файла определённого типа. Сначала получим расширение файла из контекстной переменной Extension виджета:
function getFileExtension() {
if (Context.data.extension){
return (Context.data.extension[0]);
}
else {
return "";
}
}
Если формат файла поддерживается, то будем возвращать true
, и false
в противном случае. В примере ниже разрешена обработка только файлов с расширением .xlsx.
async function canRender() {
let fileType:string = getFileExtension();
if (fileType == "xlsx")
{
return true;
}
else
{
return false;
}
}
Если файл имеет другое расширение, то в системе вместо пользовательского модуля будет использоваться средство просмотра по умолчанию: пакет MS Office365. При неудачной попытке открытия файла в окне просмотра появится сообщение об ошибке.
Важно: чтобы получить данные документа, необходимо использовать серверные сценарии виджета предпросмотра, поскольку у клиентских сценариев может быть недостаточно прав доступа.
Пример создания модуля предпросмотра без интеграции со сторонним сервисом
Рассмотрим пример создания модуля, который позволит воспроизводить файлы формата .mp3 в интерфейсе ELMA365. Для создания такого модуля будут использоваться стандартные HTML-элементы без настройки интеграции со сторонним сервисом.
- Перейдите на страницу Администрирование > Модули. В правом верхнем углу нажмите кнопку +Модуль, а затем Создать. Укажите название модуля и краткое описание.
- Задайте формат файла, который будет распознаваться модулем. Для этого перейдите на вкладку Настройки и нажмите +Добавить. В открывшемся окне задайте следующие параметры:
- Отображаемое имя* — Поддерживаемые форматы;
- Имя свойства* — SupportedFileTypes. Обратите внимание, данное имя свойства обязательно, так как оно проверяется при поиске модулей для открытия файла с определённым расширением;
- Тип* — Категория. Так как модуль поддерживает одно файловое расширение, выберите Одиночный тип;
- Значение — mp3.
- Нажмите кнопку Создать.
- Создайте виджет, который будет воспроизводить файл формата .mp3. Для этого на вкладке Виджеты нажмите + Виджет. Задайте произвольные значения для полей Название и Код виджета, например, mp3 preview. В поле Расширение выберите Предпросмотр > Страница предпросмотра. Нажмите кнопку Сохранить.
- В открывшемся дизайнере интерфейсов перейдите на вкладку Контекст.
- Создайте переменную, которая будет хранить ссылку на обрабатываемый файл. Для этого нажмите + Добавить и задайте следующие значения:
- Отображаемое имя* — Ссылка на файл;
- Имя свойства* — link;
- Тип* — Строка.
- Перейдите на вкладку Шаблон. Добавьте на поле для моделирования виджет Код. В открывшемся окне введите следующий сценарий:
<% if (Context.data.link) { %>
<audio controls>
<source src="<%= Context.data.link%>" type="audio/mp3">
Ваш браузер не поддерживает встроенное аудио. Попробуйте скачать его
<a href="<%= Context.data.link%>" download>по ссылке</a>.
</audio>
<% } %>
В указанном сценарии с помощью стандартных HTML-элементов создаётся окно, содержащее плеер с файлом. В качестве источника для файла служит ссылка, созданная на шаге 6.
После сохранения сценария на поле для моделирования отобразится созданный плеер:
- Перейдите на вкладку Сценарии. В правом верхнем углу нажмите Клиент. Добавьте код, который будет производить инициализацию виджета:
/** Событие, выполняющееся при инициализации виджета */
async function onInit() {
// Получить ссылку на загрузку файла из контекстной переменной file
const file_link = await Context.data.file?.getDownloadUrl();
// Если ссылки нет — завершить работу
if (!file_link) {
return;
}
// Присвоить контекстной переменной link значение ссылки на загрузку файла
Context.data.link = file_link;
}
- В левом верхнем углу нажмите кнопку Сохранить, а затем Проверить, чтобы убедиться, что виджет составлен верно. Затем нажмите Опубликовать.
После этого при включённом модуле вы сможете воспроизводить файлы формата .mp3 в интерфейсе ELMA365, добавив их в поле типа Файлы в карточку любого элемента приложения.
Пример интеграции с внешним средством просмотра и редактирования файлов
Рассмотрим интеграцию модуля предпросмотра с внешними приложениями на примере сервиса просмотра Р7-Офис. В этой интеграции c помощью сценария на языке Javascript реализованы отправка документа и параметров его просмотра на внешний сервер, получение и отображение ответа в ELMA365.
Для создания модуля выполните следующие действия:
- Перейдите на страницу Администрирование > Модули. В правом верхнем углу нажмите кнопку +Модуль, а затем Создать. Укажите название модуля и краткое описание.
- Задайте формат файла, который будет распознаваться модулем. Для этого перейдите на вкладку Настройки и нажмите +Добавить. В открывшемся окне задайте следующие параметры:
- Отображаемое имя* — Поддерживаемые форматы;
- Имя свойства* — SupportedFileTypes. Обратите внимание, данное имя свойства обязательно, так как оно проверяется при поиске модулей для просмотра файла с определённым расширением;
- Тип* — Категория. Чтобы модуль поддерживал несколько файловых расширений, выберите Множественный тип.
- Значение — по очереди добавьте поддерживаемые модулем типы: doc, docx, odt, txt, xls, xlsx, ods, csv, ppt, pptx, odp.
- Нажмите кнопку Создать.
- Аналогично создайте два свойства, с помощью которых будет происходить подключение к серверу внешнего средства просмотра файлов, со следующими параметрами:
- Отображаемое имя* — задайте названия для свойств: Адрес сервера ELMA365 и Адрес сервера Р7-Офис;
- Имя свойства* — укажите уникальные имена для свойств: elmaServerAdress и r7OfficeServerAdress;
- Тип* — у обоих свойств установите тип Строка.
- Создайте виджет, который будет открывать файлы указанных форматов. Для этого на вкладке Виджеты нажмите +Виджет. Задайте произвольные значения для полей Название и Код виджета, например, doc preview. В поле Расширение выберите Предпросмотр > Страница предпросмотра.
- В открывшемся дизайнере интерфейсов перейдите на вкладку Контекст.
- Создайте контекстную переменную, которая будет использоваться для передачи параметров с сервера на клиент. Для этого нажмите +Добавить и задайте следующие значения:
- Отображаемое имя* — Дополнительные параметры;
- Имя свойства* — ExtensionParameters;
- Тип* — Строка.
- Перейдите на вкладку Шаблон. Добавьте на поле для моделирования виджет Код. В открывшемся окне введите сценарий, приведённый ниже.
<div style="height: 100%;width: 100%;display: flex;"> |
- Приведённый выше сценарий содержит функции, работу которых необходимо описать на вкладке Сценарии. Перейдите на эту вкладку и в правом верхнем углу нажмите Клиент. Добавьте сценарий, приведённый ниже.
/* window webAPI */ |
- На вкладке Сценарии в правом верхнем углу нажмите кнопку Сервер. Добавьте сценарий, приведённый ниже.
/* Server scripts module */ |
- В левом верхнем углу нажмите кнопку Сохранить, а затем Проверить, чтобы убедиться, что виджет составлен верно. Затем нажмите Опубликовать.
- Закройте дизайнер интерфейсов. В настройках модуля перейдите на вкладку Методы API. Создайте новый метод. Добавьте сценарий, размещённый ниже.
async function callback(req: FetchRequest): Promise<HttpResponse | void> { |
После этого при включённом модуле вы сможете просматривать файлы с форматами, указанными в настройках этого модуля, в интерфейсе ELMA365.