Менеджер темы

Менеджер темы — глобальный объект, который отслеживает состояния и события темы. Он позволяет выполнять дополнительные действия после возникновения событий или изменений состояния. Например, собирать информацию о действиях клиента в теме для дальнейшей аналитики.

Настройки из статьи применимы, если у вас у установлена официальная тема BILLmanager. Подробнее о том, как создать свою тему, см. статью Создание темы.

Инициализация менеджера

Объект менеджера доступен в глобальном объекте window под названием ISPDragonManager. Этот объект не становится доступным мгновенно. Чтобы дождаться его создания, рекомендуется отслеживать событие ISPDragonManagerLoaded, которое срабатывает при готовности объекта менеджера. В данных события ISPDragonManagerLoaded содержится объект менеджера.

Чтобы получить объект менеджера, используйте шаблон: 

function handlerManager(manager) {
    // работа с менеджером
}

// если код выполнился после того, как менеджер был создан, объект ISPDragonManager доступен в объекте `window`
if (window.ISPDragonManager) {
    handlerManager(window.ISPDragonManager);
} else {
    // если менеджер ещё не создан на момент исполнения кода, дождитесь выполнения события `ISPDragonManagerLoaded`
    window.addEventListener('ISPDragonManagerLoaded', event => {
        // в данных события лежит объект менеджера
        const manager = event.detail;
        handlerManager(manager);
    });
}

События

Менеджер позволяет отслеживать общие события, которые происходят в теме:

• http-response — получение ответа на запрос;
• action — выполнение действия. Например, нажатие на кнопку;
• form-submit — успешная отправка формы;
• form-view-init — инициализация формы;
• form-destroy — закрытие формы;
• form-wizard — переход на wizard (мастер) или уход с него.

Тип события http-response

Происходит, когда HTTP-ответ приходит от сервера.

Объект события включает следующие свойства:

Тип события action

Происходит при внутренних событиях темы: 

• нажатие на кнопку;
• нажатие на внутреннюю ссылку, т.е. ссылку с атрибутом @internal="yes".

В зависимости от типа события, его объекты содержат свойства:

Объект события "Нажатие на кнопку"

Объект события "Нажатие на внутреннюю ссылку"

Тип события form-submit

Происходит при успешной отправке формы. Если форма не прошла валидацию, событие не произойдет.

Тип события form-view-init

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

Если внутри одной формы изменяется объект doc, событие form-view-init произойдёт повторно. Объект события будет содержать новый объект formGroup и новое свойство contextFunc.

Тип события form-destroy

Происходит при закрытии формы.

Тип события form-wizard

Происходит, когда пользователь входит на Форму-мастер (wizard) или покидает её после успешной отправки формы на последнем шаге.

Объект события "Открытие первого шага wizard"

Объект события "Успешная отправка формы на последнем шаге wizard"

Методы работы с событиями

Ниже перечислены методы объекта менеджера, которые позволяют работать с событиями темы.

addListener(eventName, callback) 

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

Функция возвращает undefined.

removeListener(eventName, callback) 

Удаляет переданную функцию из обработчиков события с именем, указанным в eventName. После этого функция больше не будет вызываться при возникновении события с таким именем.

Функция возвращает undefined.

listenToEvent$(eventName) 

Позволяет получить объект класса Observable , который срабатывает при возникновении события с именем, указанным в eventName.

Функция возвращает объект класса Observable, который отправляет объект события.

Примеры использования

Приведённые примеры будут выполнены в том случае, если существует глобальный объект менеджера (подробнее см. раздел "Инициализация менеджера").

Ниже приведён пример добавления и удаления обработчика события http-response:

// функция-обработчик
const callback = (event) => {
    // обработчик получает объект события
    console.log('Объект события http-response', event);
    // удаляем обработчик
    window.ISPDragonManager.removeListener('http-response', callback);
};
// добавляем обработчик на событие `http-event`
window.ISPDragonManager.addListener('http-response', callback);

В примере ниже приведена подписка на объект Observable события action:

// подписка на событие `action`
window.ISPDragonManager.listenToEvent$('action').subscribe(event => {
    // поток отправляет объект события
    console.log('Объект события action', event);
});

Состояния

Менеджер позволяет получать состояния темы и их изменения:

• active-doc — тег doc активной вкладки платформы;
• user-real-level — уровень пользователя в панели;
• active-context-id — id текущего активного контекста.

Состояние active-doc 

Объект, соответствующий корневому тегу doc активной вкладки платформы.

Состояние user-real-level

Текущий уровень пользователя представлен целым числом. Соответствует атрибуту @level из первого элемента doc.path. Таким образом определяется уровень корневого пользователя.

Состояние active-context-id 

Строка, соответствующая  id  текущего активного контекста. Например, id  активной вкладки. Позволяет однозначно различать элементы на странице, если, например, открыто несколько одинаковых вкладок.

Методы работы с состоянием

Ниже перечислены методы объекта менеджера, которые позволяют работать с состояниями темы.

getState(stateName) 

Позволяет синхронно получить текущее значение состояния, указанного в stateName.

Функция возвращает значение состояния.

addWatcher(stateName, watcher) 

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

Функция возвращает undefined.

removeWatcher(stateName, watcher)

Удаляет функцию слежения за изменением значения состояния с именем, указанным в stateName.

Функция возвращает undefined.

watchForState$(stateName, options?)

Позволяет получить объект класса Observable, который будет срабатывать при изменении значения состояния с именем, указанным в stateName. При подписке этот Observable сразу отправит текущее значение состояния. Затем он будет возвращать значение состояния при каждом его изменении.

Функция возвращает объект класса Observable, который отправляет значение состояния.

Примеры использования

Приведённые примеры будут выполнены в том случае, если существует глобальный объект менеджера (подробнее см. раздел "Инициализация менеджера").

В примере ниже приведено синхронное получение уровня пользователя:

// получаем значение состояния `user-real-level`
const currentUserLevel = window.ISPDragonManager.getState('user-real-level');
console.log(currentUserLevel);

В примере ниже показано, как добавить и удалить слушателя состояния:

// функция-обработчик
const callback = (currentDoc) => {
    // обработчик первым аргументом получает значение состояния
    console.log('Значение состояния active-doc', currentDoc)
    // удаление обработчика
    window.ISPDragonManager.removeWatcher('active-doc', callback);
};
// добавление обработчика. При добавлении обработчика он будет вызван немедленно. Далее будет вызываться на каждое изменение состояния
window.ISPDragonManager.addWatcher('active-doc', callback);

В примере ниже показано, как подписаться на объект Observable состояния user-real-level:

window.ISPDragonManager.watchForState$('user-real-level').subscribe(userLevel => {
    // уровень пользователя будет выведен в консоль сразу после подписки, и при каждом изменении состояния
    console.log(userLevel)
});

При установке значения опции skipFirst: true, поток будет отправлять значения состояния только при его изменении и не будет отправлять значение сразу после подписки на него:

window.ISPDragonManager.watchForState$('user-real-level', { skipFirst: true }).subscribe(userLevel => {
    // уровень пользователя будет выведен в консоль только при изменении состояния
    console.log(userLevel)
});

Может быть полезно

Связанные статьи:

• Создание темы