Плагины пользовательского интерфейса ПО «zVirt Max»

1. Общие сведения о плагинах пользовательского интерфейса ПО «zVirt Max»

ПО «zVirt Max» поддерживает плагины, предоставляющие нестандартные функции. Это упрощает использование Портала администрирования для интеграции с другими системами. Каждый плагин интерфейса представляет собой набор расширений пользовательского интерфейса, которые могут упаковываться и распространяться для использования с ПО «zVirt Max».

Плагины пользовательского интерфейса ПО «zVirt Max» интегрируются с Порталом администрирования прямо на клиенте с помощью языка программирования JavaScript. Плагины вызываются Порталом администрирования и выполняются в среде выполнения JavaScript в веб-браузере. Плагины пользовательского интерфейса могут использовать язык JavaScript и его библиотеки.

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

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

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

2. Жизненный цикл плагина пользовательского интерфейса ПО «zVirt Max»

Основной жизненный цикл плагина пользовательского интерфейса делится на три стадии:

Обнаружение плагина.
Загрузка плагина.
Начальный запуск плагина.

2.1. Обнаружение плагина пользовательского интерфейса ПО «zVirt Max»

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

В рамках обработки запросов к HTML-страницам Портала администрирования (HTTP GET) инфраструктура плагинов пользовательского интерфейса пытается обнаружить и загрузить дескрипторы плагинов из локальной файловой системы. Для каждого дескриптора плагина инфраструктура также пытается загрузить соответствующие пользовательские конфигурации плагина, используемые для переопределения конфигураций конкретных плагинов по умолчанию (если они есть) и подстройки поведения плагина во время выполнения. Пользовательская конфигурация плагина является необязательной. После загрузки дескрипторов и соответствующих пользовательских файлов конфигурации oVirt Engine собирает данные плагинов пользовательского интерфейса и встраивает их в HTML-страницу Портала администрирования для оценки во время выполнения.

По умолчанию дескрипторы плагинов находятся в $ENGINE_USR/ui-plug-ins с сопоставлением по умолчанию ENGINE_USR=/usr/share/ovirt-engine, как определено локальной конфигурацией oVirt Engine. Ожидается, что дескрипторы плагинов будут соответствовать спецификациям формата JSON, но дескрипторы плагинов делают возможными комментарии в стиле Java/C++ (разновидностей /* и //) в дополнение к спецификациям формата JSON.

По умолчанию пользовательские файлы конфигурации плагина находятся в $ENGINE_ETC/ui-plug-ins с сопоставлением по умолчанию ENGINE_ETC=/etc/ovirt-engine, как определено локальной конфигурацией oVirt Engine. Ожидается, что пользовательские файлы конфигурации плагина будут соответствовать тем же правилам в отношении формата содержимого, что и дескрипторы плагина.

Пользовательские файлы конфигурации плагина обычно соответствуют соглашению о присвоении имен <descriptorFileName>-config.json.

2.2. Загрузка плагина пользовательского интерфейса ПО «zVirt Max»

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

Для каждого обнаруженного плагина Портал администрирования создает элемент HTML iframe, используемый для загрузки его хост-страницы. Хост-страница плагина необходима для инициации процесса начального запуска плагина, и этот процесс начального запуска используется для оценки кода плагина в контексте плагина элемента iframe. Инфраструктура плагинов пользовательского интерфейса поддерживает обслуживание ресурсных файлов плагина (таких как хост-страница плагина) из локальной файловой системы. Хост-страница плагина загружается в элемент iframe, и код плагина подвергается оценке. После оценки кода плагина он связывается с Порталом администрирования посредством API плагина.

2.3. Начальный запуск плагина пользовательского интерфейса ПО «zVirt Max»

Типовой процесс начального запуска состоит из следующих шагов:

Процесс начального запуска плагина

Получить экземпляр pluginApi для данного плагина
Получить объект конфигурации плагина для среды выполнения (необязательно)
Зарегистрировать соответствующие функции обработчика событий
Сообщить инфраструктуре плагинов пользовательского интерфейса о необходимости продолжить инициализацию плагина

Следующий фрагмент кода иллюстрирует вышеупомянутые шаги на практике:

// Access plug-in API using 'parent' due to this code being evaluated within the context of an iframe element.
// As 'parent.pluginApi' is subject to Same-Origin Policy, this will only work when WebAdmin HTML page and plug-in
// host page are served from same origin. WebAdmin HTML page and plug-in host page will always be on same origin
// when using UI plug-in infrastructure support to serve plug-in resource files.
var api = parent.pluginApi('MyPlugin');

// Runtime configuration object associated with the plug-in (or an empty object).
var config = api.configObject();

// Register event handler function(s) for later invocation by UI plug-in infrastructure.
api.register({
     // UiInit event handler function.
  UiInit: function() {
    // Handle UiInit event.
     window.alert('Favorite music band is ' + config.band);
         }
});

// Notify UI plug-in infrastructure to proceed with plug-in initialization.
api.ready();

3. Файлы, относящиеся к плагинам пользовательского интерфейса, и пути к этим файлам

Таблица 1. Файлы, относящиеся к плагинам пользовательского интерфейса, и пути к этим файлам
Файл	Путь	Примечания
Файлы дескрипторов плагинов (метаданные)	/usr/share/ovirt-engine/ui-plugins/my-plugin.json
Пользовательские файлы конфигурации плагинов	/etc/ovirt-engine/ui-plugins/my-plugin-config.json
Ресурсные файлы плагинов	/usr/share/ovirt-engine/ui-plugins/<resourcePath>/PluginHostPage.html	<resourcePath> определяется соответствующим атрибутом в дескрипторе плагина.

4. Пример развертывания плагина пользовательского интерфейса

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

Развертывание плагина Hello World!

Создайте дескриптор плагина, создав следующий файл в Менеджере управления по пути /usr/share/ovirt-engine/ui-plugins/helloWorld.json:
```
{
    "name": "HelloWorld",
    "url": "/ovirt-engine/webadmin/plugin/HelloWorld/start.html",
    "resourcePath": "hello-files"
}
```
Создайте хост-страницу плагина, создав следующий файл в Менеджере управления по пути /usr/share/ovirt-engine/ui-plugins/hello-files/start.html:
```
<!DOCTYPE html><html><head>
<script>
var api = parent.pluginApi('HelloWorld');
api.register({
    UiInit: function() { window.alert('Hello world'); }
});
api.ready();
</script>
</head><body></body></html>
```

Если плагин Hello World! успешно реализован, то при авторизации на Портале администрирования вы увидите этот экран:

Рисунок 1. Успешная реализация плагина Hello World!