Демо-приложение на PHP для каталога решений МоегоСклада

Данное демо показывает основные способы взаимодействия решений с МоимСкладом по протоколу Vendor API.

В демо-приложении реализованы следующие функции:

• Активация (с получением токена доступа к JSON API 1.2) и деактивация по Vendor API
• Использование iframe для настройки решения администратором аккаунта с обновлением статуса в МоемСкладе
• Получение контекста пользователя для iframe (отображение информации по пользователю, проверка прав администратора)
• Получение информации из МоегоСклада по JSON API 1.2 с доступом по токену
• Встраивание виджетов в карточку Контрагента, Заказ покупателя и Отгрузку
• Встраивание кастомных кнопок в документ и список Заказов покупателя
• Открытие кастомного модального окна из виджета и кнопки в Заказе покупателя

ВНИМАНИЕ! Демо-приложение предназначено для ознакомления с функционалом каталога решений МоегоСклада и вопросы безопасности и стабильности его работы не рассматривались в рамках его разработки.

Для запросов в МойСклад данное решение использует библиотеку curl. Обратитесь к документации, для того чтобы настроить её для локальной разработки.

Виджеты

Решение встраивает виджеты на следующие экраны:

• Контрагент (entity.counterparty.edit)
• Заказ покупателя (document.customerorder.edit)
• Отгрузка (document.demand.edit)

Цель данных виджетов - продемонстрировать, как работает система виджетов в UI МоегоСклада.

Все виджеты работают одинаково и реализуют следующие функции:

• Отображение текущего пользователя (демонстрация получения контекста пользователя по contextKey)
• Получение данных об открытой сущности/документе через JSON API
• Возможность управления задержкой отправки сообщения OpenFeedback (демонстрация работы протокола open-feedback)
• Возможность посмотреть границы и размеры содержимого виджета
• Лог JavaScript-сообщений (Window.postMessage): входящих от хост-окна и исходящих от виджета

Обратите внимание, что геометрические свойства DOM-элементов типа scrollHeight равны 0 или null до момента снятия заглушки в хост-окне (так работают браузеры) - например, в обработчике входящего сообщения Open и даже после отправки сообщения OpenFeedback. Если виджет не поддерживает опциональный протокол open-feedback, то заглушка при открытии виджета не ставится и геометрические свойства должны работать уже при получении сообщения Open.

Подробнее про виджеты https://dev.moysklad.ru/doc/api/vendor/1.0/#vidzhety

Кастомные кнопки

Решение встраивает кастомные кнопки на следующие экраны:

• Документ Заказ покупателя (document.customerorder.edit)
• Список Заказов покупателя (document.customerorder.list)

В демо-приложении создаются следующие кнопки:

• Отобразить уведомление - отправляет в ответе МоемуСкладу действие showNotification для отображения всплывающего уведомления
• Открыть ссылку - отправляет действие navigateTo для открытия ссылки в новой вкладке
• Открыть popup - отправляет действие showPopup для открытия кастомного модального окна.

Подробнее про кастомные кнопки https://dev.moysklad.ru/doc/api/vendor/1.0/#kastomnye-knopki

Кастомные модальные окна

Для открытия модального окна из виджетов, нажмите кнопку Открыть popup в нем. При этом виджет отправит хост-окну сообщение ShowPopupRequest и МойСклад отобразит диалоговое окно с двумя кнопками Сохранить и Отмена.

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

Подробнее про работу с модальными окнами https://dev.moysklad.ru/doc/api/vendor/1.0/#kastomnye-modal-nye-okna

Настройка (конфигурирование) решения

Перед использованием решения нужно настроить следующие конфигурационные параметры через переменные окружения (рекомендуется) либо напрямую в config.php:

• APP_ID - идентификатор решения в МоемСкладе
• APP_UID - appUid решения в МоемСкладе
• APP_SECRET_KEY - секретный ключ для подписи JWT
• APP_BASE_URL - базовый URL решения, должен указывать на содержимое ./src/php (сейчас используется при генерации дескриптора)

Структура файлов решения

Основные файлы

• button.php - обработка нажатий кастомных кнопок
• Dockerfile - конфигурация для запуска решения в docker-контейнере
• config.php - текущая конфигурация
• iframe.html.php - HTML-шаблон содержимого iframe
• iframe.php - контроллер отображения содержимого iframe
• jwt.lib.php - JWT PHP библиотека (копипаст из https://github.com/firebase/php-jwt)
• lib.php - общие классы приложения (конфигурация, модели данных, врапперы доступа к API МоегоСклада)
• update-settings.php - контроллер обновления настроек
• user-context-loader.inc.php - общий код получения контекста пользователя через Vendor API (используется главным iframe решения и виджетами)
• vendor-endpoint.php - контроллер REST-endpoint'a для обработки запросов по Vendor API

Файлы виджетов

• widgets/counterparty-widget.php - контроллер виджета в карточке Контрагента (entity.counterparty.edit)
• widgets/customerorder-widget.php - контроллер виджета в Заказе покупателя (document.customerorder.edit)
• widgets/demand-widget.php - контроллер виджета в Отгрузке (document.demand.edit)
• widgets/popup.html.php - HTML-шаблон содержимого кастомного модального окна с javascript-кодом
• widgets/popup.php - общий код контроллера модальных окон
• widgets/widget.html.php - HTML-шаблон содержимого виджета с javascript-кодом взаимодействия виджета с хост-окном
• widgets/widget.inc.php - общий код контроллеров виджетов

Утилиты

Для удобства отладки в папке utils находятся два скрипта:

• generate-descriptor.php - генерация дескриптора решения в соответствии с текущей конфигурацией
• generate-jwt.php - генерация JWT-токена (например, для выполнения запросов через Postman)

Логирование

Логи решения выводятся в /var/logs/apache2/error.log (в консоль при запуске в docker).

Данные

Состояние решений хранится в файловой системе (сериализацией) по одному файлу на каждую установку в data/*.app