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

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

Настройки из статьи применимы, если у вас у установлена официальная тема 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-элементами формы.

Тип события 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)
});