Что нового для разработчиков в XenForo 2.3?

Как и было обещано, на этой неделе мы собираемся кратко рассмотреть некоторые из наиболее ориентированных на разработчиков изменений, которые появятся в XenForo 2.3.

Если какая-то тема интересует вас больше других, нажмите одну из ссылок ниже:

• JavaScript
• SwiftMailer в Symfony Mail
• Doctrine Cache в Symfony Cache
• Обновленный Emogrifier
• Событие предварительной загрузки реестра
• Собственные методы преобразования IP-адресов
• Поддержка class strings
• Обновления тега <time> - краткий формат даты
• Встраивание названий шаблонов в HTML
• AbstractCollection nth method
• Умный очиститель кеша Javascript
• XF.createElement
• Изменения синтаксиса макросов шаблона
• Direct messages

Хотя нам есть что вам показать, следующие пару недель будут посвящены подготовке XenForo 2.3 к установке здесь и некоторым дополнительным вопросам "Вы видели...?" сообщения могут появиться между этим моментом и публичным бета-выпуском. А пока спасибо, что отправились в это путешествие вместе с нами.

 

[XFI Bot]

JavaScript​

В нашем втором HYS мы объявили о своем решении отойди от jQuery и некоторые из вас уже выпускают обновления для своих дополнений, и это приятно видеть. Ниже следующее служит не исчерпывающим справочником по любым конкретным изменениям платформы, которые могут повлиять на то, как вы будете писать код JavaScript в своих надстройках в будущем.

XF.extendObject​

Это новый метод, который заменяет стандартный метод jQuery. $.extend(). По сути, он работает точно так же, включая возможность «глубокого» клонирования.

XF.createElementFromString​

jQuery поддерживает создание нового элемента с различными свойствами и атрибутами полностью из строки, например:

const $input = $('<input type="text" readonly class="input" />')

Нам хотелось иметь что-то похожее на это, поэтому мы добавили метод, который работает аналогичным образом:

const input = XF.createElementFromString('<input type="text" readonly class="input" />')

У нас также есть совершенно новая концепция под названием XF.createElement о чем вы можете прочитать в следующем посте.

Управление событиями​

Некоторые возможности управления событиями в jQuery довольно круты, поэтому мы максимально воспроизвели их. Примечательно, что мы поддерживаем события в пространстве имен аналогично jQuery, а также эквивалентные jQuery методы с именем XF.on(), XF.off(), XF.trigger() и XF.customEvent(). Для обработки делегированных событий у нас есть новый XF.onDelegated метод. Если вы ранее использовали jQuery one чтобы прослушиватель событий удалялся после его первого запуска, теперь вы можете просто передать { once: true } в твой XF.on().

Изменения в XF.ajax​

В то время как использование XF.ajax() практически не изменился, очевидно, что мы больше не используем jQuery $.ajax() под капотом, который представляет собой обертку вокруг XMLHttpRequest. Мы решили отойти от XMLHttpRequest в пользу более современного Fetch API.

XF.ajax теперь возвращает Promise что похоже на то, что возвращает jQuery, хотя имена методов обещания немного отличаются. Которые были упомянуты в оригинале, вы видели пост.

Другое заметное изменение заключается в том, как запросы AJAX при необходимости прерываются. Раньше объект, возвращаемый jQuery, имел abort метод, который можно вызвать. У Fetch API есть другой способ достижения этой цели, который немного более запутан, поэтому мы создали новый XF.ajaxAbortable метод, который немного упрощает работу, но стоит отметить, что ваше существующее использование XF.ajax если вызов может потребоваться прервать, его необходимо изменить.

Вот пример использования из form.js:

const {
    ajax,
    abortController,
} = XF.ajaxAbortable('post', this.options.descUrl, { id: value }, this.onLoad.bind(this))

if (abortController)
{
    this.abortController = abortController
}

// ... elsewhere in the code

if (this.abortController)
{
    this.abortController.abort()
    this.abortController = null
}

XF.proxy​

XF.proxy метод обычно используется, когда вы хотите изменить контекст this переменная при вызове другой функции. Например, если вы передаете функцию в качестве обратного вызова при прослушивании изображения load событие (или подобное), this в этом обратном вызове обычно будет ссылка на само изображение. Обычно это нежелательно, поэтому XF.proxy помогает нам сохранить this контекст соответствует.

Хотя, конечно, XF.proxy все еще существует и остается неизменным, пожалуйста, считайте, что он устарел и помечен для удаления в будущем.

Вместо этого мы теперь рекомендуем и используем для этого собственный подход JavaScript. Это выглядит так:

XF.on(form, 'reset', this.formReset.bind(this))

В первую очередь это должно помочь уменьшить количество ошибок и облегчить навигацию по коду в вашей IDE.

Анимация JavaScript и переходы на основе CSS​

В jQuery имеется ряд функций анимации, которые, по нашему мнению, стоило сохранить, поэтому мы их переписали. Домом для этих новых методов является новый XF.Animate пространство имен и включает в себя различные подходы к перемещению/затуханию контента.

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

XF.Animate.fadeUp(containerEl, {
    speed: XF.config.speed.fast,
    complete ()
    {
        containerEl.innerHTML = html.innerHTML
        XF.Animate.fadeDown(containerEl)
    },
})

Возможно, вы также знакомы с нашим обычными addClassTransitioned и removeClassTransitioned методами. Раньше они добавлялись как расширения jQuery. Сейчас они перенесены в новое XF.Transition пространство имен и требует, чтобы элемент был передан в качестве первого аргумента.

XF.Transition.addClassTransitioned(this.errorElement, 'is-active')

Изменения в библиотеке поставщиков​

В этом разделе обобщены изменения в библиотеках поставщиков, которые могут повлиять на ваши текущие дополнения.

Select2​

К сожалению, Select2 по-прежнему написан с использованием jQuery в качестве зависимости, поэтому он больше не будет включаться, начиная с XenForo 2.3. Мы используем Select2 только для нашей системы «ввода токенов», которая используется в качестве ввода тегов и для выбора несколькими пользователями (например, в разговорах). Чтобы сохранить эту функциональность, мы теперь включаем библиотеку под названием

У Вас недостаточно прав для просмотра ссылок. Вход или Регистрация

.

Это в значительной степени имеет ту же функциональность, к которой вы привыкли, но, ох, посмотрите, аватары для ввода нескольких пользователей:

Генерация QR-кода​

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

У Вас недостаточно прав для просмотра ссылок. Вход или Регистрация

.

Звездные рейтинги​

Звездные рейтинги, которые вы можете видеть как в XenForo Media Gallery, так и в XenForo Resource Manager, ранее основывались на сторонней библиотеке. Прямой замены на самом деле не существовало, поэтому мы просто конвертировали ее в JavaScript. Теперь это новый класс с именем XF.BarRating[/CODE] который вы можете найти в [ICODE]rating.js.[/CODE]

 

[XFI Bot]

SwiftMailer to Symfony Mail​

Объявление о прекращении существования SwiftMailer было опубликовано

У Вас недостаточно прав для просмотра ссылок. Вход или Регистрация

и мы быстро внедрили Symfony Mail в качестве замены... еще в 2021 году. Хотя мы могли бы внедрить это во время существования XenForo 2.2, есть несколько небольших перерывов в BC.

Любые расширения классов для XF\Mail\Mail и XF\Mail\Mailer вероятно, это будет затронуто, и для работы с XenForo 2.3 потребуются изменения. В основном это повлияет на любые методы, которые в настоящее время получают любой объект с классом, имеющим префикс Swift_ и использование тех объектов, которые могут иметь другой API.

В целом, Symfony Mail — это, по сути, переписанный с нуля SwiftMailer, поэтому процесс преобразования кода для использования Symfony Mail не должен вызывать слишком много проблем.

 

[XFI Bot]

Doctrine Cache в Symfony Cache​

Doctrine Cache также устарел и был заменен компонентом Symfony Cache. Хотя это изменение похоже по объему на Symfony Mailer, оно имеет больше шансов сломать сайты, которые используют плагины, в той или иной форме затрагивающие кеширование.

Учитывая это, мы предусмотрели уровень совместимости, чтобы снизить вероятность возникновения серьезных проблем. При получении адаптера кэша из сервисного контейнера он оборачивается объектом с тем же полным доменным именем и интерфейсом, что и поставщик кэша Doctrine. В большинстве случаев это должно позволить дополнениям продолжать работать без изменений. Мы используем обертку Doctrine Cache в \XF\CssRenderer для сохранения обратной совместимости. Другие классы, которые не используют нашу систему расширений, были обновлены для прямого использования адаптера Symfony Cache.

Чтобы облегчить переход на адаптер Symfony Cache, вы можете получить его с помощью нового логического третьего аргумента метода \XF\App::cache:

$cache = \XF::app()->cache('context', true, false);

// setting a cache item
$item = $cache->getItem($id);
$item->set($data);
$item->expiresAfter($ttl);
$cache->save($item);

// retrieving a cache item
$data = $cache->getItem($id);

Вы можете проверить

У Вас недостаточно прав для просмотра ссылок. Вход или Регистрация

для получения более подробной информации.

 

[XFI Bot]

Обновленный Emogrifier​

Мы обновили включенную библиотеку Emogrifier. Это библиотека, которая преобразует классы CSS, используемые в шаблонах электронной почты, во встроенные стили для улучшения совместимости рендеринга почты в различных почтовых клиентах.

Это привело к небольшому изменению XF\Mail\Styler, где, если вы добавили сюда расширение класса, которое расширяет __construct В частности, вам нужно будет внести изменения, поскольку он больше не получает inliner свойство:

public function __construct(CssRenderer $renderer)

 

[XFI Bot]

Событие предварительной загрузки реестра​

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

Мы представили событие app_preload_extra в XF 2.3, позволяющее плагинам предварительно загружать данные из реестра. Это означает, что все плагины могут загружать данные из реестра вместе в одном запросе, вместо того, чтобы запрашивать данные по отдельности. \XF\App объект также передается, чтобы ключи могли быть привязаны к конкретному приложению:

public static function appPreloadExtra(\XF\App $app, array &$keys): void
{
    if ($app instanceof \XF\Pub\App)
    {
        $keys[] = 'myRegistryKey';
    }
}

 

[XFI Bot]

Собственные методы преобразования IP​

В предыдущих версиях мы использовали собственные методы для преобразования IP-адресов из текстового в двоичный формат. В XF 2.3 мы упразднили \XF\Util\Ip::convertIpStringToBinary и \XF\Util\Ip::convertIpBinaryToString методы в пользу новых \XF\Util\Ip::stringToBinary и \XF\Util\Ip::binaryToString методы. Новые методы используют встроенный PHP. inet_pton и inet_ntop функции, которые более надежны и не приводят к потенциально опасным неоднозначностям.

Если вы используете устаревшие методы в плагине, новые методы в большинстве случаев должны функционировать как замена. Однако есть несколько предостережений, о которых следует знать. Новые методы не будут пытаться обрабатывать ситуации, когда IP-адрес уже преобразован в целевой формат, и выдадут исключение, если по умолчанию будет передан неверный IP-адрес. Вы можете пройти false в качестве последнего аргумента для возврата false вместо того, чтобы генерировать исключение. Метод \XF\Util\Ip::binaryToString также сохраняет поддержку расширения адресов IPv6 там, где это желательно.

 

[XFI Bot]

Поддержка class strings​

Начиная с XF 2.0, мы широко использовали «короткие имена» классов для расширения имен классов и связывания связанных объектов, таких как сущности и средства поиска. Несмотря на удобство, многие чрезвычайно полезные современные инструменты не понимают это соглашение, что требует обходных путей, таких как расширенная генерация метаданных PhpStorm или специальные расширения для инструментов статического анализа.

В XF 2.3 мы теперь поддерживаем использование полных имен классов везде, где поддерживаются короткие имена. Сюда входит извлечение сущностей, средств поиска, репозиториев и других объектов, а также определение метаданных, таких как отношения и поведение сущностей. При использовании полных имен классов IDE лучше справляются с рефакторингами, такими как переименование классов, а статические анализаторы могут лучше определять, какие объекты возвращаются из методов контейнера и фабрики.

use XF\Entity\User;

// ...

$user = \XF::app()->find(User::class, 1);

// ...

$structure->relations = [
    'User' => [
        'entity' => User::class,
        'type' => self::TO_ONE,
        'conditions' => 'user_id',
        'primary' => true,
    ],
];

 

[XFI Bot]

Обновления тега <time> – краткий формат даты​

Разрабатывая то, что теперь стало стилем XenForo 3, мы внесли некоторые улучшения в вывод тега HTML <time> (который отображается при использовании <xf:date> тег в синтаксисе шаблона XenForo).

Хотя эта функция не используется активно в версии 2.3, она не меняет внешний вид выходных данных шаблона, поэтому вместо того, чтобы отменять изменения, мы оставили их в этой версии.

Так что же он на самом деле делает?

В XenForo 2.2 мы выводим теги времени следующим образом:

<time datetime="2023-11-15T09:49:23+0000" data-time="1700041763"
   data-date-string="Nov 15, 2023" data-time-string="9:49 AM"
   title="Nov 15, 2023 at 9:49 AM">51 mins</time>

Затем оно обновляется с помощью Javascript для сохранения времени относительно настоящего.

Для нового стиля нам нужна возможность выводить строку short date, когда пространство ограничено, поэтому 51 минуту назад будет выводиться как 51 м. Для этого мы включаем новый data-short атрибут, содержащий краткий формат даты/времени.

<!-- 2m (2 minutes ago) -->
<time datetime="2023-11-15T10:43:14+0000" data-timestamp="1700044994"
    data-date="Nov 15, 2023" data-time="10:43 AM"
    data-short="2m" title="Nov 15, 2023 at 10:43 AM">2 minutes ago</time>

Тот же Javascript, который обновляет основной вывод, также обновляет атрибут [data-short с текущим коротким форматом.

Другие примеры:

<!-- 13h (13 hours ago) -->
<time datetime="2023-11-14T21:00:23+0000" data-timestamp="1699995623"
    data-date="Nov 14, 2023" data-time="9:00 PM"
    data-short="13h" title="Nov 14, 2023 at 9:00 PM">Yesterday at 9:00 PM</time>

<!-- 2d (2 days ago) -->
<time datetime="2023-11-12T22:46:15+0000" data-timestamp="1699829175"
    data-date="Nov 12, 2023" data-time="10:46 PM"
    data-short="2d" title="Nov 12, 2023 at 10:46 PM">Sunday at 10:46 PM</time>

<!-- Sep 14 (September 14 this year) -->
<time datetime="2023-09-14T14:50:24+0100" data-timestamp="1694699424"
    data-date="Sep 14, 2023" data-time="2:50 PM"
    data-short="Sep 14" title="Sep 14, 2023 at 2:50 PM">Sep 14, 2023</time>

<!-- Nov '18 (November 12 2018) -->
<time datetime="2018-11-12T15:26:22+0000" data-timestamp="1542036382"
    data-date="Nov 12, 2018" data-time="3:26 PM"
    data-short="Nov '18" title="Nov 12, 2018 at 3:26 PM">Nov 12, 2018</time>

Естественно, эти короткие форматы дат интегрируются с языком и системой фраз, поэтому, если 2m не значит 2 минуты на вашем языке вы можете редактировать вывод так же, как и для длинного формата даты.

По умолчанию при отображении даты за год до текущей короткий формат исключает день месяца (22 ноября). M 'y вместо 15 ноября 22 г. M j, 'y), но если вы хотите включить его, вы можете сделать это с помощью специального формата даты, например M j 'y.



Итак, хотя на самом деле вы этого не увидите в использовании в версии 2.3 мы оставили его на месте, чтобы предприимчивые дизайнеры CSS и JS могли использовать его по своему усмотрению.

 

[XFI Bot]

Встраивание названий шаблонов в HTML​

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

Или, по крайней мере, так оно и было.

Хотя ранее мы вывели data-template атрибут в <body> Чтобы помочь разработчикам и дизайнерам определить основной используемый шаблон контента, мы значительно расширили систему.

Теперь, включив Встраивание названий шаблонов в HTML, ваш вывод HTML будет включать атрибуты data-template-name, которые позволяют легко идентифицировать шаблон, отвечающий за конкретную часть проверяемой страницы.



Эти атрибуты отображаются только аутентифицированным администраторам.

<html data-template-name="PAGE_CONTAINER" id="XF" lang="en-US" dir="LTR" data-xf="2.3" data-app="public" ...>

<div data-template-name="thread_view" class="block block--messages" ...>

Эти data-template-name атрибуты не являются частью самих шаблонов, а скорее добавляются окончательным средством рендеринга вывода, поэтому вам не нужно беспокоиться о их обновлении или загромождении процесса редактирования шаблонов.

На практике, data-template-name атрибуты добавляются к самому внешнему отображаемому HTML-тегу в каждом шаблоне. Есть несколько случаев, когда в шаблоне есть контент prior в HTML-тег, и в этом случае средство визуализации выведет это содержимое до помеченного тега, но определить ответственный шаблон все равно будет гораздо проще, чем раньше.

value атрибут принадлежащий data-template-name не ограничивается только именами шаблонов. В случаях, когда выходные данные поступают из шаблона макрос , значение атрибута будет включать в себя как имя шаблона, так и имя шаблона. и имя макроса.

<article data-template-name="post_macros::post" class="message message--post" ...>

Обратите внимание, что при включении эти теги data-template-name выводятся только аутентифицированным администраторам, поэтому не следует полагаться на них как на CSS-селекторы, в отличие от оригинального body[data-template] селектор, который безопасен в использовании.

Мы использовали data-template-name вместо повторного использования data-template как используется в теге <body>, чтобы избежать потенциальных коллизий CSS, если к тегу прикреплен стиль на странице. Атрибут data-template, хотя мы будем вероятно использовать data-template для этой функции в XenForo 3 и переместите data-template атрибут из <body> тег к тегу <html> с более описательным именем, например data-content-template или что-то вроде того...

 

[XFI Bot]

AbstractCollection nth method​

В ответ на недавнее предложение мы реализовали возможность легкого возврата nth из AbstractCollection.

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

Например, если вы запрашиваете коллекцию сообщений и хотите получить доступ к третьей публикации из возвращенной коллекции, вы можете просто вызвать ->nth(3).

$posts = $finder->fetch();
$third = $posts->nth(3);
$fifteenth = $posts->nth(15);

 

[XFI Bot]

Умный очиститель кеша Javascript​

Разве при разработке JavaScript не раздражает принудительное обновление каждый раз, когда вы вносите изменения в свой код?

Мы тоже так подумали, поэтому создали новый умный очиститель кэша, который активируется, когда вы используете

У Вас недостаточно прав для просмотра ссылок. Вход или Регистрация

вариант.

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

Это мелочи...

 

[XFI Bot]

XF.createElement​

Это не является строго заменой какой-либо функциональности jQuery, но он позволяет сократить некоторые довольно утомительные ванильные Javascript, которые обычно используются.

Рассмотрим следующий Javascript:

const el = document.createElement('input')
el.type = 'text'
el.name = 'title'
el.value = 'Hello, world'
parentEl.appendChild(el)

Много el, да?

Благодаря версии 2.3 и XF.createElement() мы теперь можем делать следующее:

const el = XF.createElement('input', {
    type: 'text',
    name: 'title',
    value: 'Hello, world'
}, parentEl)

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

И объект свойств, и узел, к которому можно добавить элемент, являются необязательными параметрами, хотя, если вы не собираетесь добавлять элемент в DOM, было бы бесполезно не присвоить возвращаемое значение переменной.

Объект свойств также поддерживает один уровень вложенности, поэтому вы также можете сделать что-то вроде следующего:

const el = XF.createElement('span', {
    className: 'spanny-spanny-moo-moo',
    title: 'This is a span',
    dataset: {
        foo: 1,
        bar: 2
    },
    style: {
        color: 'red',
        fontWeight: 'bold'
    }
}, parentEl)

Есть еще частный случай attributes свойство, значения которого будут установлены с помощью el.setAttribute(name, value) если вам нужно его использовать.

 

[XFI Bot]

Изменения синтаксиса макросов шаблона​

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

Вот в основном свёрнутый вид публикации XenForo 2.2. PAGE_CONTAINER шаблон в PhpStorm и код Visual Studio.



Довольно бесполезно, правда?

Причина этого в том, что эти древовидные представления игнорируют name атрибут тегов в их сводном представлении. Не заставляйте меня говорить, насколько это глупо, особенно когда name Атрибут имеет решающее значение для таких элементов, как <input>, Но что есть, то есть.



Мы ничего не можем сделать с <input>, <select> или <textarea> но мы можем что-то сделать <xf:macro> чтобы оно имело более полезное представление в виде структуры.

<xf:macro name="m" /> ➡ <xf:macro id="m" />​

Это довольно простое изменение, и оно просто включает в себя переключение name атрибут для id атрибут. Это может привести к тому, что ваша IDE будет жаловаться на то же самое. id тег используется для нескольких элементов, но его можно игнорировать, поскольку эти атрибуты не будут выведены в окончательный визуализируемый HTML-код там, где это имеет значение.

Давайте переключим PAGE_CONTAINER шаблон для использования <xf:macro id...> вместо <xf:macro name...> и посмотрите, как изменится схематический вид.



Разве это не лучше?

name Атрибут все еще доступен, но устарел, поэтому вам следует обновить свои шаблоны.

<xf:macro template="t" name="m"> ➡ <xf:macro id="t::m" />​

Мы также упразднили <xf:macro template="template-name" name="macro-name" /> синтаксис в пользу id="template-name::macro-name" формат, который снова помогает увидеть разумный контур структуры.

 

[XFI Bot]

Direct messages​

Мы уже упоминали об этом в другом месте, но приняли решение переименовать «Conversations» в «Direct messages». Эта терминология более знакома большинству пользователей Интернета и имеет более подходящую аббревиатуру «DM». На протяжении многих лет люди часто до сих пор называют их «PM» для личных сообщений или «PC» для личных разговоров, и это может сбить с толку тех, кто не знаком с программным обеспечением.

В XF 2.3 это полностью визуальное изменение. Все ссылки на код, имена классов и шаблоны остались прежними. Появились новые канонические маршруты под названием direct-messages и direct-messages/replies но все существующие маршруты для conversations и conversations/messages будет правильно перенаправлен на новые маршруты. Изменились только фразы.

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

Мы можем внести более масштабные изменения в будущей версии, и в этом случае мы предоставим большое количество предупреждений.