Хост плагинов

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

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

Приложения, разработанные для работы на хосте плагинов, полностью отвечают за рендеринг интерфейса страницы и могут получить доступ ко всем компонентам пользовательского интерфейса CMS Studio и API через глобальную переменную window.dccms в браузере или через npm-пакет @dccms/studio-ui при использовании стека разработки.

Вы можете перейти к хосту плагинов, войдя в CMS Studio и перейдя по адресу /studio/plugin. Например, в вашем локальном окружении URL будет http://localhost:8080/studio/plugin. Для рендеринга плагина хосту плагинов требуется от трех до пяти аргументов строки запроса.

Аргументы хоста плагинов:

Название

Значение по умолчанию

Описание

site

требуется

Id проекта, где установлен плагин

type

требуется

Имя директории категории внутри директории {sandbox}/config/studio/plugins

name

требуется

Имя директории плагинов внутри директории {sandbox}/config/studio/plugins/{type}

file

index.js

Имя файла, который плагин-хост должен загрузить. Это может быть HTML или JavaScript файл. 

id

ID плагина, когда приложение вложено в директорию с ID плагина

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

Хост плагинов загружает один файл, который может быть либо JavaScript (JS), либо HTML файлом, и этот файл отвечает за инициализацию приложения.

  • JS файл: 
    • При загрузке файла JavaScript хост плагинов сначала загружает runtime-скрипты CMS Studio UI, а затем загружает ваш файл. Ваш JavaScript файл может получить доступ ко всем функциям runtime CMS Studio через window.dccms
    • Вы можете писать на обычном JavaScript или использовать стек разработки, который транспилирует ваш код в конечный JavaScript файл, который будет загружен в браузере. Это полезно, если вы хотите использовать JSX или TypeScript.
  • HTML файл:
    • Когда вы загружаете HTML-файл, контент отображается точно так, как определено в HTML-файле. Поэтому DC CMS runtime (window.dccms) не доступно до тех пор, пока вы сами это не включите. Для использования UI API или компонентов рекомендуется использовать пакет npm @dccms/studio-ui. Не рекомендуется вручную копировать и вставлять теги <script src=""> из CMS Studio, так как они могут изменяться в новых версиях DC CMS.
    • При работе с HTML-файлом вы можете загружать дополнительные ресурсы, такие как скрипты, таблицы стилей, изображения и т. д., используя API загрузчика файлов плагина вместе со стандартными HTML-тегами. Например, для динамической загрузки JavaScript-файла можно использовать такой тег script: <script src="/studio/1/plugin/file?siteId={SITE_ID}&type={CATEGORY}&name={NAME}&filename={FILE_NAME}"></script> 

Если у вас есть приложение, которое нужно построить, например, через транспиляцию, у вас есть выбор либо хранить исходные файлы внутри вашего проекта DC CMS, либо в отдельном репозитории. Главное — убедиться, что завершенная сборка вашего плагина правильно помещена в директорию файлов плагинов, как описано здесь.

Использование набора инструментов Front-end разработки Copy-icon

При создании вашего приложения с использованием инструментов, таких как webpack (включая CRA) или подобных, важно помнить, что базовый URL вашего приложения не будет просто “/”. Например, рассмотрим следующую структуру для веб-сайта под названием «Cofee Shop» с плагином под названием «bulk-edit»…

coffee-shop/authoring/static-assets/{pluginIdPath} <== Plugins root directory

  apps/                                                <== Category directory

    bulk-edit/                                         <== Plugin root directory

      static/

        index.js

        css/

          index.css

        index.html
Copy-icon

Чтобы правильно загрузить файл index.js, инструмент сборки может попытаться получить доступ к static/index.js, что приведет к ошибке 404. Чтобы исправить это, настройте базовый URL вашего инструмента на /studio/1/plugin/file?siteId=coffee-shop&type=apps&name=bulk-edit&filename=. Таким образом, конечный URL будет /studio/1/plugin/file?siteId=coffee-shop&type=apps&name=bulk-edit&filename=static/index.js, что обеспечит успешную загрузку файла.

При использовании CRA вы можете выполнить описанное выше, добавив файл .env.production и установив конфигурацию PUBLIC_URL, чтобы указать базовый URL. 

PUBLIC_URL=/studio/1/plugin/file?siteId=coffee-shop&type=apps&name=bulk-edit&filename=
Copy-icon

Мы рекомендуем вам использовать React и Material UI при разработке ваших приложений и виджетов. UI DC CMS создан на основе этих технологий, поэтому такая интеграция позволит вам добиться согласованности и обеспечить удобство использования для конечного пользователя.

Кроме того, вы сможете воспользоваться всеми возможностями UI CMS Studio, а также её утилитами и API. Ознакомьтесь ниже с образцами приложений, разработанных с использованием этих технологий, чтобы лучше понять, как они работают.

Обратите внимание, что при создании приложения с использованием пакета @dccms/studio-ui вы можете столкнуться с проблемой большого размера сборки. Это связано с тем, что вы, по сути, создаёте ещё одну CMS Studio. 

Отображение приложения хоста плагинов в CMS Studio Copy-icon

Иногда вашим требованиям может соответствовать автономное приложение, но для пользователей может быть полезно отображать приложение в модальном диалоге, не покидая интерфейс CMS Studio.

DC CMS предлагает уникальный компонент под названием PluginHostIFrame, который позволяет отображать плагин хост в iFrame с указанным приложением. При использовании с WidgetDialog этот плагин позволяет вызвать ваше приложение плагин хоста в интерфейсе CMS Studio в нужное вам время.

С использованием npm пакета

import { showWidgetDialog } from '@cms

cms/studio-ui/state/actions/dialogs';

import { useDispatch } from 'react-redux';


const dispatch = useDispatch();

dispatch(

  showWidgetDialog({

    title: 'Bulk Edit',

    widget: {

      id: 'cms.components.PluginHostIFrame',

      configuration: {

        plugin: { type: 'apps', name: 'bulk-edit', file: 'index.html' }

      }

    }

  })

);
Copy-icon
С использованием браузерного времени выполнения (browser runtime)

const dispatch = dccms.getStore().dispatch;

dispatch({

  type: 'SHOW_WIDGET_DIALOG',

  payload: {

    title: 'Bulk Edit',

    widget: {

      id: 'сms.components.PluginHostIFrame',

      configuration: {

        plugin: { type: 'apps', name: 'bulk-edit', file: 'index.html' }

      }

    }

  }

});
Copy-icon

По умолчанию PluginHostIFrame будет использовать текущий активный проект, но он также может принимать аргумент site, если вы хотите отображать iFrame, содержащий приложение хоста плагинов из определенного проекта.

Пример Copy-icon

Для примера рассмотрим сайт с названием "Coffee Shop" и id coffee-shop. Изначально мы создали категорию плагинов под названием apps, расположенную в {yourPluginDirectory}/authoring/static-assets/{pluginId}/apps. В этой категории мы развернули простое приложение для массового редактирования контента в директории bulk-edit, расположенной в {sandbox}/config/studio/plugins/apps/bulk-edit. Это приложение изначально было структурировано вокруг одного JavaScript файла с именем index.js.

Настроив наши файлы и директории плагина с использованием упомянутого JavaScript файла и установив его с помощью cms-cli команды copy-plugin, мы смогли получить доступ к интерфейсу плагина Bulk Edit по адресу /studio/plugin?site=cofee-shop&type=apps&name=bulk-edit.

Поскольку требования к приложению возросли, и его пользовательский интерфейс стал более сложным, мы решили обновить его до полнофункционального приложения с использованием хэш-маршрутизации. Для этого мы выбрали инструменты типа Create React App или Angular CLI. В результате точка входа была перенесена с index.js на файл index.html, который обычно генерируется этими инструментами. Для эффективной работы обновленного приложения мы теперь загружаем index.html вместо оригинального index.js.

В результате интерфейс плагина Bulk Edit теперь доступен по адресу /studio/plugin?site=coffee-shop&type=apps&name=bulk-edit&file=index.html.

Связанные статьи Copy-icon

Плагины

Документация для разработчиков