Глава 18. Дополнительные возможности веб-клиента

В процессе реализации прикладных систем могут возникать задачи интеграции веб-сайта с прикладным решением, доступ к которому осуществляется с использованием веб-клиента. Такая интеграция может подразумевать, например, возможность открытия веб-клиента внутри элемента <iframe> html-страницы веб-сайта.

Подобное встраивание предполагает выполнение следующих действий:

● Выделение на странице сайта области, в которой будет исполняться веб-клиент.

● Реализация некоторого интерфейса (на встроенном языке) на стороне прикладного решения, который будет отвечать за обмен данными с веб-сайтом, в который интегрируется прикладное решение. Сюда же можно отнести установку необходимого режима основного окна приложения и предоставление пользователю возможность использовать нужный режим основного окна клиентского приложения с помощью прав доступа.

● Реализация некоторого интерфейса (на языке JavaScript) на стороне сайта, в который интегрируется прикладное решение, с целью предоставления веб-клиенту необходимой информации о режиме работы и обмена данными с прикладным решением.

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

Общие требования к интеграции следующие:

1. Прикладное решение должно предоставлять доступ с помощью веб-клиента (опубликовано на веб-сервере). Подробнее см. стр. см. здесь.

2. Веб-сервер должен быть корректно настроен для обеспечения встраивания прикладного решения в веб-сайт. Подробнее см. стр. см. здесь.

3. Для работы с веб-сайтом, в который интегрирован веб-клиент, должны использовать только те веб-браузеры, которые поддерживаются системой «1С:Предприятие» для работы веб-клиента (см. здесь).

У прикладного решение существует свойство глобального контекста ОкноВнешнегоСайта. С помощью этого свойства прикладное решение получает интерфейс с веб-сайтом в том случае, если прикладное решение интегрировано в этот веб-сайт. Этот интерфейс позволяет выполнить несколько действий:

● Проверить, что веб-клиент работает внутри какого-либо веб-сайта. Это можно выполнить с помощью свойства ОкноВнешнегоСайта.Доступно. В дальнейшем рекомендуется все действия с менеджером окна внешнего веб-сайта (свойство ОкноВнешнегоСайта) выполнять после проверки того, что данное свойство установлено в значение Истина.

● Получать сообщения от внешнего (относительно веб-клиента) веб-сайта, предварительно зарегистрировав метод обработчика сообщений от веб-сайта с помощью метода ОкноВнешнегоСайта.ПодключитьОбработчикСообщений(). Также можно отключить обработку сообщений внешнего веб-сайта, если такая обработка более не требуется. Отключение обработки сообщений выполняется с помощью метода ОкноВнешнегоСайта.ОтключитьОбработчикСообщений().

● Отправлять сообщения внешнему веб-сайту с помощью метода ОкноВнешнегоСайта.ОтправитьСообщение().

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

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

● С помощью свойства Режим основного окна клиентского приложения.

● С помощью командной строки запуска клиентского приложения MainWindowMode.

● С помощью метода УстановитьРежимОсновногоОкна().

Также необходимо предоставить возможность использования нужного режима основного окна клиентского приложения с помощью установки соответствующих прав доступа.

Смотри также:

● Свойство конфигурации Режим основного окна клиентского приложения (см. здесь).

● Командная строка запуска веб-клиента (см. стр. см. здесь).

● Права доступа (см. здесь).

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

● Указать место, где будет отображаться интерфейс веб-клиента. Это можно сделать с помощью элемента <div>. При загрузке веб-клиент автоматически добавит для выбранного элемента подчиненный элемент <iframe>, который будет содержать всю необходимую информацию.

● Указать, откуда загружать код JavaScript-интерфейса веб-клиента (Embedded WebClient API). После загрузки этого интерфейса в веб-браузере становится доступным объект WebClient1CE. Для загрузки JavaScript-интерфейса в текст сайта необходимо включить следующий код: <script src="%АдресВебСайта%/%ИмяИБ%/scripts/webclient1ce.js"></script>.

● Реализовать интерфейс взаимодействия с системой «1С:Предприятие».

Рассмотрим более подробно объект WebClient1CE:

● Конструктор WebClient1CE(webClientContainerID, config), где:

● webClientContainerID ‑ тип String ‑ идентификатор элемента <div>, в который будет встраиваться элемент <iframe>, в котором будет работать веб-клиент. Обязательный параметр.

● config ‑ тип Object ‑ объект, содержащий настройки веб-клиента. Обязательный параметр.

● Метод gotoURL(navigationURL) ‑ позволяет выполнить переход по навигационной ссылке. Работает аналогично методу встроенного языка ПерейтиПоНавигационнойСсылке(). Параметры метода:

● navigationURL ‑ тип String ‑ навигационная ссылка, по которой необходимо выполнить переход. Обязательный параметр.

● Метод postMessage(message) ‑ отправляет в веб-клиент текст, указанный в качестве параметра. При вызове этого метода в прикладном решении будут вызваны обработчики, которые подключены с помощью вызова метода ОкноВнешнегоСайта.ПодключитьОбработчикСообщений(). Параметры метода:

● message ‑ тип String ‑ текст, который будет передан в веб-клиент. Обязательный параметр.

Объект настроек, который передается в качестве параметра в конструктор объекта WebClient1CE, имеет следующие свойства:

● webClientURL ‑ тип String ‑ строка запуска веб-клиента (включая команды и параметры командной строку запуска веб-клиента). Указание обязательно.

● width ‑ тип String ‑ ширина области встраивания (элемента <iframe>) с указанием единицы измерения. Указание необязательно.

● height ‑ тип String ‑ высота области встраивания (элемента <iframe>) с указанием единицы измерения. Указание необязательно.

● events ‑ тип Object ‑ объект, описывающий обработчики событий, поступающие от встраиваемого веб-клиента. Указание необязательно.

Объект, который описывает обработчики событий от веб-клиента, имеет следующие свойства:

● onStart ‑ тип Function ‑ функция (без параметров), которая будет вызвана после запуска прикладного решения. Функция будет вызвана после завершения работы обработчика события ПриНачалеРаботыСистемы встраиваемого прикладного решения. Указание необязательно.

● onEnd ‑ тип Function ‑ функция (без параметров), которая будет вызвана перед завершением работы прикладного решения. Функция будет вызвана после завершения работы обработчика события ПриЗавершенииРаботыСистемы встраиваемого прикладного решения. Указание необязательно.

● onMessage ‑ тип Function ‑ функция, которая будет вызвана для получения сообщения от прикладного решения. Сообщение отправляется с помощью вызова метода ОкноВнешнегоСайта.ОтправитьСообщение(). Функция onMessage имеет следующие параметры:

● message ‑ тип String ‑ текст сообщения, посланного из прикладного решения.

● origin ‑ тип String ‑ указывает основной адрес веб-клиента. Строка включает в себя протокол, домен и порт.

Указание необязательно.

● onFormOpen ‑ тип Function ‑ функция, которая будет вызвана при открытии формы прикладного решения (после завершения работы обработчика события ПриОткрытии). Функция onFormOpen имеет следующие параметры:

● url ‑ тип String ‑ навигационная ссылка открываемой формы. Параметр будет равен пустой строке в том случае, если открываемая форма не имеет навигационной ссылки.

● formName ‑ тип String ‑ имя открываемой формы, сформированная для английского варианта встроенного языка.

Указание необязательно.

● onFormClose ‑ тип Function ‑ функция, которая будет вызвана при закрытии формы прикладного решения (после завершения работы обработчика события ПриЗакрытии). Функция onFormClose имеет следующие параметры:

● url ‑ тип String ‑ навигационная ссылка открываемой формы. Параметр будет равен пустой строке в том случае, если открываемая форма не имеет навигационной ссылки.

● formName ‑ тип String ‑ имя открываемой формы, сформированная для английского варианта встроенного языка.

Указание необязательно.

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

Пример демонстрирует:

● Как указать на странице элемент, в котором будет работать веб-клиент.

● Какой минимальный набор действий необходимо выполнить на стороне веб-сайта, чтобы веб-клиент смог запуститься и взаимодействовать с внешним сайтом.

● Какой минимальный набор действия необходимо выполнить в прикладном решении, чтобы оно смогло работать «внутри» внешнего веб-сайта и взаимодействовать с этим веб-сайтом.

Для работы примера необходимо иметь веб-сервер, на котором размещена демонстрационная веб-страница и опубликован веб-клиент. Прикладное решение, используемое для демонстрации, состоит из единственной обработки, указанной в виде формы рабочей области начальной страницы. В форме этой обработки должна быть создана команда СообщениеВнешнемуСайту, эта команда размещена на форме обработки (в виде кнопки с именем СообщениеВнешнемуСайту). Модуль формы содержит следующий код на встроенном языке:

&НаКлиенте
Процедура СообщениеВнешнемуСайту(Команда)
    Если ОкноВнешнегоСайта.Доступно Тогда
   СообщениеСайту = Новый СообщениеВнешнемуСайту("Сообщение от веб-клиента");
   ОкноВнешнегоСайта.ОтправитьСообщение(СообщениеСайту);
    КонецЕсли;
КонецПроцедуры
&НаКлиенте
Процедура ПриОткрытии(Отказ)
    Если ОкноВнешнегоСайта.Доступно Тогда
   ОбработчикСобытия = Новый ОписаниеОповещения("ПриПолученииСообщенияОтВнешнегоСайта", ЭтотОбъект);
   ОкноВнешнегоСайта.ПодключитьОбработчикСообщений(ОбработчикСобытия);
    КонецЕсли;
КонецПроцедуры
&НаКлиенте
Процедура ПриЗакрытии(ЗавершениеРаботы)
    Если ОкноВнешнегоСайта.Доступно Тогда
   ОбработчикСобытия = Новый ОписаниеОповещения("ПриПолученииСообщенияОтВнешнегоСайта", ЭтотОбъект);
   ОкноВнешнегоСайта.ОтключитьОбработчикСообщений(ОбработчикСобытия);
    КонецЕсли;
КонецПроцедуры
&НаКлиенте
Процедура ПриПолученииСообщенияОтВнешнегоСайта(Сообщение, ДополнительныеПараметры) Экспорт
    Сообщить(Сообщение.Данные);
КонецПроцедуры

Прикладное решение должно быть опубликовано на веб-сервере. Адрес публикации необходимо запомнить для вставки в демонстрационную веб-страницу.

Прикладное решение будет интегрироваться в веб-страницу, которая выглядит следующим образом:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <script src="%АдресВебСайта%/%ИмяИБ%/scripts/webclient1ce.js"></script>
</head>
<body onload="init();">
    <div id="webClientContainer"></div>
    <button onclick="messageToWebClient();">Сообщение веб-клиенту</button>
    <div id="webClientMessageArea"></div>
    <script>
   var webClient = null;
   var onWebClientMessage = function (message, origin) {
    if (origin === '%АдресВебСайта%') {
       document.querySelector('#webClientMessageArea').innerText = message;
     }
    };
   var messageToWebClient = function () {
    webClient.postMessage("Это сообщение из внешнего сайта");
   };
   var init = function () {
    webClient = new WebClient1CE('webClientContainer',
    {
     webClientURL: '%АдресВебСайта%/%ИмяИБ%?MainWindowMode=EmbeddedWorkplace',
     width: '600px',
     height: '400px',
     events:
     {
       onMessage: onWebClientMessage
     }
    });
   };
    </script>
</body>
</html>

Для того чтобы веб-страница заработала, необходимо выполнить следующие замены:

● Текст %АдресВебСайта% на реальный адрес веб-сайта (протокол, домен и порт), на котором публикуется веб-клиент.

● Текст %ИмяИБ% на реальное имя публикуемой информационной базы (как оно указано в поле Имя диалога публикации на веб-сервере).

Так, если веб-клиент опубликован по адресу http://mysite.org/dbName, то псевдопеременные заменяются следующим образом:

● %АдресВебСайта% заменяется на http://mysite.org.

● %ИмяИБ% заменяется на dbName.

Рассмотрим подробнее, что выполняется на этой веб-странице:

● Элемент <script> выполняет загрузку скрипта, реализующего Embedded WebClient API.

● При загрузке тела веб-страницы срабатывает обработчик init(), который указан в качестве обработчика события onload элемента body.

● Строка <div id="webClientContainer"></div> определяет элемент <div>, в который будет встроен веб-клиент.

● В обработчике init() выполняется создание объекта WebClient1CE. Конструктору передается идентификатор элемента <div> (в примере это webClientContainer). Также в обработчике init():

● Веб-клиенту передается командная строка запуска, которая указывает, что веб-клиент должен быть запущен в режиме основного окна Встроенное рабочее место.

● Для элемента <iframe>, в котором будет работать веб-клиент, устанавливается ширина равная 600 пикселам и высота, равная 400 пикселам. Указание данных параметров не является обязательным, вместо этого можно использовать или размер по умолчанию или использовать другие способы задания размера области отображения <iframe>, например CSS.

● Регистрируется обработчик события onMessage, который будет принимать сообщение от веб-клиента. Обработка этого события будет выполняться в методе onWebClientMessage(), описанном ранее на странице.

● Строка <button onclick="messageToWebClient();">Сообщение веб-клиенту</button> формирует на веб-странице кнопку, нажатие не которую приводит к тому, что в веб-клиент отправляется сообщение с текстом Это сообщение из внешнего сайта. Отправка выполняется из обработчика messageToWebClient(), подключенного к событию onclick кнопки.

● Строка <div id="webClientMessageArea"></div> содержит описание области, в которую будет выводиться сообщение от веб-клиента (из обработчика события onMessage).

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

Рис. 520. Веб-клиент в iframe

На рисунке цифрами отмечены:

1. Нажатие кнопки Сообщение внешнему сайту приведет к появлению текста Сообщение от веб-клиента ниже кнопки Сообщение веб-клиенту.

2. Нажатие кнопки Сообщение веб-клиенту приведет к появлению сообщения Это сообщение из внешнего сайта в панели сообщений веб-клиента.

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

Условие if (origin === '%АдресВебСайта%') на странице (в общем случае) необходимо в том случае, если один обработчик используется для нескольких прикладных решений, внедренных в одну страницу. В этом случае условие будет нужно для того, чтобы понять, от какого веб-клиента поступило сообщение.

Командная строка запуска веб-клиента, указанная при инициализации свойства webClientURL: webClientURL: '%АдресВебСайта%/%ИмяИБ%?MainWindowMode=EmbeddedWorkplace', может содержать параметры аутентификации. Например, когда пользователь выполняет аутентификацию на веб-странице (или веб-сайте, в более широком смысле), а веб-страница может однозначно преобразовать имя пользователя веб-сайта в имя пользователя (и пароль) в прикладном решении. Тогда строку запуска веб-клиента следует разместить в переменной и сформировать эту переменную до того момента, как начнется запуск веб-клиента, встроенного в веб-страницу.

В заключении стоит отметить еще один момент. Во время загрузки веб-клиента отображается заставка и индикатор процесса загрузки. Если веб-клиент встроен в веб-страницу, то заставка и индикатор будут отображаться в том контейнере, куда встроен веб-клиент. Если это не требуется, то управлять видимостью области веб-страницы следует с помощью свойства CSS visibility. Так, строка для определения контейнера веб-клиента на веб-странице, будет выглядеть следующим образом:

<div id="webClientContainer" style="visibility: hidden"></div>

Для включения видимости контейнера необходимо зарегистрировать функцию, которая будет обрабатывать событие onStart от веб-клиента:

events:
{
    onStart: onStartWebClient,
    onMessage: onWebClientMessage
}

А затем написать собственно эту функцию (рядом с функцией onWebClientMessage()):

var onStartWebClient = function ()
{
    document.querySelector('#webClientContainer').style.visibility = "visible";
};

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

Прогрессивное веб-приложение (Progressive Web App, PWA) ‑ технология в веб-разработке, которая позволяет визуально (и, частично, функционально) преобразовать сайт в обычное приложение, которое работает на персональном компьютере или мобильном устройстве. Прогрессивное веб-приложение можно установить на устройство пользователя, и затем это приложение может пользоваться как обычное приложение для той операционной системы, которая работает на устройстве. Таким образом, использование прогрессивного веб-приложения может оказаться слабо отличимым (или совсем не отличимым) от использования приложения, специально разработанного для операционной системы на устройстве. Веб-клиент системы «1С:Предприятие» может быть использован в качестве прогрессивного веб-приложения в том случае, если для подключения к веб-серверу используется протокол HTTPS и на веб-сервере установлен действительный сертификат. Возможность использования веб-клиента в качестве прогрессивного веб-приложения зависит не только от самого веб-клиента, но и от используемого веб-браузера. Веб-браузеры, которые поддерживают использование прогрессивных веб-приложений, указаны в системных требованиях (см. здесь).

Для прогрессивного веб-приложения имеется возможность задать название приложения. Это название используется:

● Для отображения в окне установки/удаления прогрессивного веб-приложения.

● В главном меню прогрессивного веб-приложения.

● В названии картинки прогрессивного веб-приложения (в меню Пуск или на рабочем столе).

Название прогрессивного веб-приложения используется в момент установки прогрессивного веб-приложения и при деальнейшем использовании. После изменения названия необходимо переустановить прогрессивное веб-приложение для того, чтобы новое название актуальным. Ограничение на длину названия составляет 45 символов. Если название превышает 45 символов, при отображении оно обрезается и дополняется многоточием.

Название прогрессивного веб-приложения можно задать следующими способами (в порядке уменьшения приоритета):

● Командой ProgressiveWebApplicationName командной строки запуска веб-клиента (см. здесь).

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

● В настройках публикации веб-клиента или с помощью файла default.vrd соответствующей публикации. Описание диалога публикации см. здесь, описание элемента файла defaut.vrd см. здесь.

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

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

Само по себе, прогрессивное веб-приложение, не предоставляет прикладному решению каких-то специальных возможностей. Тем не менее, система «1С:Предприятие» предоставляет возможность выполнить следующие действия:

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

● Установить прогрессивное веб-приложение на устройство пользователя.

● Получить информацию о том, в каком режиме работает приложение.

Для доступа к методам работы с PWA предназначен менеджер прогрессивного веб-приложения, который доступен через свойство глобального контекста ПрогрессивноеВебПриложение.

Перед тем, как пытаться установить приложение, необходимо проверить, что на данном устройстве можно выполнить установку прогрессивного веб-приложения. Для выполнения проверки предназначен метод Поддерживается(). Если на данном устройстве поддерживается использование PWA, то можно выполнить установку.

В процессе установки PWA используется несколько методов:

● Установлено() ‑ данный метод позволяет узнать, в данный момент PWA на данном устройстве установлено или нет.

● НачатьУстановку() ‑ метод инициирует установку PWA. Перед непосредственно установкой, веб-браузер покажет пользователю диалог, в котором нужно подтвердить установку или отказаться от нее. Чтобы получить результат этого действия, предназначен следующий метод. Этот же диалог можно получить если:

● Нажать пиктограмму (+) в правой части адресной строки веб-браузера при работе в веб-клиенте.

● Выбрать команду Отображать как отдельное приложение меню Сервис и настройки самого веб-клиента.

● ПодключитьОбработчикОкончанияУстановки() ‑ этот метод позволяет зарегистрировать обработчик обратного вызова, управление в который попадет после того, как пользователь что-то ответит в диалоге веб-браузера, который отображается перед установкой PWA.

● ОтключитьОбработчикОкончанияУстановки() ‑ позволяет отключить обработчик, установленный предыдущим методом. Использовать данный метод разумно в том случае, когда ранее подключенный обработчик окончания установки более не требуется.

Разработчик может проверить, в каком режиме работает прикладное решение, с помощью метода ТекущийРежим():

● Если прогрессивное веб-приложение установлено и открыто в отдельном окне, метод вернет значение РежимПрогрессивногоВебПриложения.ВОтдельномОкне.

● Если прогрессивное веб-приложение установлено и открыто во вкладке браузера, метод вернет значение РежимПрогрессивногоВебПриложения.ВОкнеБраузера.

● В остальных случаях (включая вызов метода в тонком или толстом клиентских приложениях), метод вернет значение Неопределено.