XenForo without secrets: how to write extensions

Основы расширения XenForo 1.5: события, хуки и механизмы

Данная статья будет больше похожа на мини-документацию и примеры по функционалу XenForo, чтобы начинающие кодеры легче писали расширения.

Часть 1: Как правильно ловить появление элементов на странице
Использование setInterval, setTimeout, observer для обработки динамически появляющихся элементов без особой на то причины - дурной тон.
XenForo имеет собственную систему активации элементов через

⁡XenForo.register

⁡ и

⁡.xfActivate()

⁡ . Это позволяет инициализировать скрипты даже на динамически загруженных элементах (overlay, ajax).
​

Примеры

// Регистрация обработчика на CSS-селектор
XenForo.register('.myComponent', 'XenForo.MyHandler');

// Обработчик — функция или класс
XenForo.MyHandler = function($elem) {
// инициализация при появлении элемента
};

// Пример активации вручную:
$('body').append(myHtml).xfActivate();

// Для активации элементов которые были на странице до загрузки вашего расширения можно вызвать:
$('.myComponent').each(function () {
$(this).xfActivate();
});

JavaScript

// Регистрация обработчика на CSS-селектор

XenForo.register('.myComponent', 'XenForo.MyHandler');



// Обработчик — функция или класс

XenForo.MyHandler = function($elem) {

// инициализация при появлении элемента

};



// Пример активации вручную:

$('body').append(myHtml).xfActivate();



// Для активации элементов которые были на странице до загрузки вашего расширения можно вызвать:

$('.myComponent').each(function () {

        $(this).xfActivate();

});

Это позволяет инициировать скрипты даже на элементах, загруженных через AJAX или overlay.

Каждая активация вызывает события:

• ⁡XenForoActivateHtml
  ⁡ — до инициализации HTML
• ⁡XenForoActivatePopups
  ⁡ — после инициализации тултипов
• ⁡XenForoActivationComplete
  ⁡ — в самом конце

$(document).on('XenForoActivateHtml', (e) => {
const $el = $(e.element);
// логика
});

JavaScript

$(document).on('XenForoActivateHtml', (e) => {

const $el = $(e.element);

// логика

});

Часть 2: Полезные события XenForo и кастомные обработчики

Форум создаёт много полезных событий, потенциально полезных для перехвата вашими расширениями:
​

Примеры

// Overlay (вызов, показ)
$(document).on('OverlayOpening', function(e, overlay) {});
$(document).on('OverlayOpened', function(e, overlay) {});

// Обновление списка тем
$('.DiscussionList').on('UpdateSearchResults', function(e) {});

// Загрузка диалога
$('#Conversations').on('LoadConversation', function(e, conversationId) {
console.log('ID:', conversationId);
});

// Popup-меню
$(document).on('PopupMenuShow', function(e) {
const $menu = e.$menu;
const instant = e.instant;
});

// Успешная валидация
$(document).on('AutoValidationComplete', function(e, success) {});

// Открытие Overlay карточки пользователя
$(document).on('XFOverlay', function(e){
let $overlay = e.overlay.getOverlay();
if (!$overlay.is('.memberCard')) return;
});

JavaScript

// Overlay (вызов, показ)

$(document).on('OverlayOpening', function(e, overlay) {});

$(document).on('OverlayOpened', function(e, overlay) {});



// Обновление списка тем

$('.DiscussionList').on('UpdateSearchResults', function(e) {});



// Загрузка диалога

$('#Conversations').on('LoadConversation', function(e, conversationId) {

console.log('ID:', conversationId);

});



// Popup-меню

$(document).on('PopupMenuShow', function(e) {

const $menu = e.$menu;

const instant = e.instant;

});



// Успешная валидация

$(document).on('AutoValidationComplete', function(e, success) {});



// Открытие Overlay карточки пользователя

$(document).on('XFOverlay', function(e){

let $overlay = e.overlay.getOverlay();

if (!$overlay.is('.memberCard')) return;

});

Откройте DevTools → вкладка "Sources" → поиск по

⁡.trigger(

⁡ . Там — всё самое интересное.


Список найденных .trigger в исходниках XenForo.js.​

Часть 3: Объекты ядра XenForo — что внутри

В консоли введите:

⁡XenForo

⁡

Там — десятки доступных модулей. Некоторые из полезных:​

Примеры

XenForo.Tooltip — всплывающие подсказки
XenForo.PopupMenu — выпадающие меню
XenForo.ajax — безопасные ajax-запросы
XenForo.alert, XenForo.stackAlert — уведомления
XenForo.visitor — объект текущего пользователя
XenForo.MultiQuote — множественные цитаты
XenForo.Chatbox — чат и связанный функционал​

Подробнее

Пример безопасного запроса:

XenForo.ajax('/some/url', {param: 1}, function(data) {
if (!XenForo.hasResponseError(data)) {
// Успешно
}
});

JavaScript

XenForo.ajax('/some/url', {param: 1}, function(data) {

if (!XenForo.hasResponseError(data)) {

// Успешно

}

});

XenForo.ajax в отличии $.ajax и fetch освобождает вас от необходимости подставлять xfToken в запрос форума, передавая его автоматически.


Консоль, раскрыто дерево XenForo → список методов и объектов.​

Часть 4: .xf* методы — вставка и анимации

Вместо обычных jQuery методов можно использовать:​

Примеры

xfFadeIn / xfFadeOut — плавное появление/исчезновение
xfInsert — вставка в DOM с анимацией + .xfActivate()
xfRemove — удаление с анимацией
xfSlideIn / xfSlideOut — drawer-анимации
xfShow / xfHide — базовые show/hide
xfSlideIn / xfSlideOut — drawer-подобное выдвижение сверху вниз (используется в ответах, чатах и других интерактивных элементах)​

Эти методы автоматически учитывают скорость анимации через XenForo.speed и вызывают .xfActivate() и события вроде XenForoActivateHtml / XenForoActivationComplete.
Пример:

$('<li class="message">Новый пост</li>')
.xfInsert('appendTo', '#MessageList')
.on('click', function () {
$(this).xfRemove();
});

JavaScript

$('<li class="message">Новый пост</li>')

.xfInsert('appendTo', '#MessageList')

.on('click', function () {

$(this).xfRemove();

});

Часть 5: Контексты и .data() — как получить доступ к логике элементов

Большинство компонентов после активации сохраняются через .data(). Если вы хотите что-то изменить/вызвать/переиспользовать из уже инициализированных компонентов — сначала получите jQuery-элемент и вызовите у него .data('XenForo.ИмяКласса') или .data('Имя.Модуля').
​

Примеры

// Доступ к объектам логики
$('.NodeList.forums').data('XenForo.ForumList');
$('.Popup').data('XenForo.PopupMenu');
$('html').data('Im.Notification');
$('#QuickReply textarea').data('XenForo.EditorSimple');
$('#Conversations').data('Im.Start');

JavaScript

// Доступ к объектам логики

$('.NodeList.forums').data('XenForo.ForumList');

$('.Popup').data('XenForo.PopupMenu');

$('html').data('Im.Notification');

$('#QuickReply textarea').data('XenForo.EditorSimple');

$('#Conversations').data('Im.Start');

Убедитесь, что элемент активирован — иначе .data() вернет undefined.

Пример вызова метода:

// Закрытие popup-меню
$('.Popup').data('XenForo.PopupMenu').hide();

// Пометка беседы как прочитанной
$('#Conversations').data('Im.Start').markConversationAsRead();

//Подписаться на сокет для прослушивания входящих сообщений
ImSocket = $('#Conversations').data('Im.Socket')
ImSocket.socket.then(function(e) {
e.subscribe(`conversation:${Im.conversationId}`, function(data){
//Todo
})
})

JavaScript

// Закрытие popup-меню

$('.Popup').data('XenForo.PopupMenu').hide();



// Пометка беседы как прочитанной

$('#Conversations').data('Im.Start').markConversationAsRead();



//Подписаться на сокет для прослушивания входящих сообщений

ImSocket = $('#Conversations').data('Im.Socket')

ImSocket.socket.then(function(e) {

    e.subscribe(`conversation:${Im.conversationId}`, function(data){

//Todo

})

})

Поиск всех data-объектов на странице:

$('*').each(function () {
const data = $(this).data();
if (Object.keys(data).length > 0) {
console.log(this, data);
}
});

JavaScript

$('*').each(function () {

const data = $(this).data();

if (Object.keys(data).length > 0) {

console.log(this, data);

}

});

Вызов .data() в консоли + найденные объекты Editor, PopupMenu, AutoValidator.​

Заключение

Теперь вы умеете:

Реагировать на динамику через .xfActivate()
Использовать события overlay, popup и ajax
Подключать свои модули через .register()
Использовать встроенные объекты и методы
Управлять поведением без хаков

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


Есть дополнения? Нашли недокументированные события?
Пишите в комментариях или дополняйте статью — вместе сделаем документацию лучше!

—

Автор: MeloniuM для любимого Lolzteam ​