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

Предыдущие "Вы видели ...?" (HYS) для XF 2.2 были в основном сосредоточены на изменениях для администраторов и пользователей. В то время как мы ссылались на некоторые внутренние технические элементы и на то, что дополнения могут делать с этими элементами, сегодня мы хотим глубже погрузиться в некоторые из изменений с точки зрения разработки.

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

Давайте начнем!

 

[Matew]

Расширения шаблонов

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

<xf:extends template="thread_view" />

<xf:extension name="above_messages">
   <xf:if is="$poll">
      <xf:macro template="poll_macros" name="poll_block" arg-poll="{$poll}" />
   </xf:if>
</xf:extension>

Это шаблон thread_view_type_poll, который используется, если типом темы является опрос. Он является самым простым шаблоном из всех остальных типов.

<xf:extends>

Первая строка является одной из самых значимых. Это помечает текущий шаблон как расширяющий thread_view (стандартный шаблон, используемый при просмотре темы). Когда эта строка присутствует, это по сути означает, что мы выводим именованный шаблон вместо стандартного (хотя это еще не все ?). Если бы в шаблоне больше ничего не было, эта страница выглядела бы в точности как обычная тема.

<xf:extension>

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

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

<xf:macro template="lightbox_macros" name="setup" arg-canViewAttachments="{$thread.canViewAttachments()}" />

<xf:extension name="above_messages"></xf:extension>
<xf:ad position="thread_view_above_messages" arg-thread="{$thread}" />

Если вы сравните его с версией 2.1, то сможете заметить некоторое сходство. Выше был приведен код для вывода опроса, и теперь у нас есть тег <xf: extension>.

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

Это единственный способ использовать теги <xf:extension>. Однако в некоторых случаях шаблон по умолчанию может содержать некоторый контент для отображения. Хорошим примером этого является форум, предназначенный для статей. В шаблоне forum_view у нас теперь есть что-то вроде этого:

<div class="block-body">
   <xf:extension name="thread_list">
      <div class="structItemContainer">
        <!-- all of the standard stuff to display  sticky threads, normal threads, etc -->
      </div>
   </xf:extension>
</div>

Затем в forum_view_type_article мы можем переопределить этот код следующим образом:

<xf:extension name="thread_list">
   <xf:if is="$forum.type_config.display_style == 'expanded' AND $forum.canViewThreadContent()">
      <!-- display extended versions of articles instead of the standard thread list -->
   <xf:else />
      <xf:extensionparent />
   </xf:if>
</xf:extension>

Здесь следует отметить новый тег <xf:extensionparent>. Он позволяет вам выводить родительскую или оригинальную версию расширяемого участка. В этом случае мы используем его как запасной вариант для отображения исходного кода, когда расширенный режим не включен, хотя его также можно использовать для добавления объектов в начало или конец участка кода, а также для обертывания вывода.

Расширение макросов

Макросы также могут быть расширены похожим образом. Дочерний макрос просто должен быть определен так:

<xf:macro name="answer" extends="post_macros::post">...</xf:macro>

С этого момента расширение происходит примерно так, как показано ранее.

Преимущества над встраиванием шаблонов и макросами

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

Примечательно, что разметка участка как точки расширения не требует значительных изменений в родительском шаблоне. В большинстве случаев можно добавить пустую точку расширения, практически не взаимодействуя с окружающим кодом, или добавить «обернутую» точку расширения, просто сделав отступ в соответствующем коде еще раз. Без этой системы рассматриваемый код, скорее всего, станет макросом, который, вероятно, будет перемещен в другое место в шаблоне (или в другой шаблон целиком) и может привести к различным проблемам с областью видимости, что усложнит изменение функциональности.

Другие примечательные особенности

• Теги <xf:extension> также могут быть определены с помощью атрибута value, который позволяет использовать их не только для отображения HTML, но и для передачи данных как в случае с тегом <xf:set>.
• Также есть тег <xf:extensionvalue> и метод шаблона extension_value(). Они позволят вам ссылаться на расширение несколько раз, если это необходимо. Метод шаблона также позволяет использовать расширение с конкретными HTML атрибутами. Мы используем это в нескольких местах для изменения классов элемента.
• <xf:extensionparent> также может принимать имя расширения в качестве атрибута, чтобы отобразить его родительскую версию. Вряд ли это будет использоваться часто, но есть некоторые специфичные случаи, когда сложно обойтись без данного тега.
• При вызове макроса теперь мы обычно предпочитаем <xf:macro name="template_name::macro_name"> вместо <xf:macro template="template_name" name="macro_name">, хотя обе варианта поддерживаются. Подход с одним атрибутом делает более простым динамическое переключение на другой макрос, что довольно часто делается в системе типов форумов и типов тем.
• Теперь мы применяем ограничения a-z, 0-9 и _ для имен макросов. Из-за того, что мы не делали этого раньше, возможно, что дополнениями/модификациями были добавлены неправильно названные макросы. Поэтому ограничение применяется только в режиме разработки, а не при установке, чтобы предотвратить блокировку обновления.

 

[Matew]

Типы форумов и тем

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

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

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

Валидаторы массивов

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

Базовый код похож на определение сущности:

protected function getTypeConfigColumnDefinitions(): array
{
   return [
      'display_style' => ['type' => Entity::STR, 'allowedValues' => ['full', 'expanded']],
      'expanded_snippet' => ['type' => Entity::UINT],
      'expanded_per_page' => ['type' => Entity::UINT],
   ];
}

Типы форумов

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

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

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

Каждый тип форума также определяет разрешенные типы тем в этом форуме. Это повлияет на пользовательский интерфейс при создании темы. Если вы хотите добавить при просмотре форума различные "поведения", которые зависят от типа темы, то вы, вероятно, захотите, чтобы ваш форум принимал только один тип темы. (Обратите внимание, что темы-перенаправления всегда разрешены, так что это то, что вам, возможно, нужно учитывать.) Это делается с помощью:

• getDefaultThreadType - определяет тип, который будет выбран по умолчанию, если существует несколько создаваемых типов, и тип, который будет использоваться, если тема создана способом, который явно не задает тип.
• getExtraAllowedThreadTypes - любые дополнительные типы тем, которые могут быть разрешены.
• getCreatableThreadTypes - потенциально подмножество первых двух методов. Различает типы тем, которые пользователи могут создавать вручную, от тем, которые могут быть созданы только программными методами. Например, темы обсуждений ресурсов могут быть разрешены в обычных форумах, но пользователи не могут создавать их вручную.

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

• Полностью переопределить отображение. Это масштабная опция, но если вы не хотите использовать какой-либо контроллер или отображать код со стандартного форума, вы можете её использовать.
• Переопределить имя представления или шаблона (forum_view), а так же изменить переменные, отправляемые в шаблон.
• Переопределить некоторые из используемых макросов, например, для отображения элементов списка тем или быстрого создания темы, и при необходимости передать дополнительные аргументы макросам.
• Добавить дополнительные способы фильтрации или сортировки тем.
• Модифицировать Finder тем для получения дополнительных данных.
• Изменить количество тем, отображаемых на странице. (В первую очередь для ситуаций, подобных представлению статьи, когда вы переходите от очень небольшого количества контента на тему к большому количеству.)

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

Типы тем

Многие из понятий, которые мы только что объяснили в разделе «Типы форумов», применимы и к типам тем. Тем не менее, иногда функциональность отличается.

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

Данные типа темы отображаются с помощью метода renderExtraDataEdit. Обратите внимание, что он используется как в контексте создания темы, так и при редактировании. Информация о контексте передается в метод, что позволяет вам реагировать соответствующим образом. Например, хотя опросы можно создавать в теме, существуют различные ограничения на редактирование существующего опроса, поэтому мы ничего не показываем, если не находимся в контексте его создания. [П/П: Имеется ввиду аналогия с использованием метода $entity->isUpdate().]

При обработке дополнительных данных существует два подхода: простой и сервис. Простая обработка по сути такая же, как мы видели в типах форумов. Мы используем систему валидации массивов для отображения входных данных на дополнительные данные, которые мы хотим сохранить. Сервисный подход позволяет вам создать объект-сервис для настройки действий, которые вы хотите выполнить. Это будет использоваться в сочетании с базовым сервисом (создание темы, редактирование и т.д.) чтобы гарантировать, что никакие действия не будут предприняты, если только оба сервиса не прошли валидацию и после выполнения действия базового сервиса также будет выполняться сервис для данных используемого типа. Это обобщенно, но примерно похоже на то, как мы обрабатывали создание опросов в 2.1.

С точки зрения просмотра тем, типы тем вводят две новые концепции:

• Закрепленный первый пост - если установлен тип темы, первый пост темы будет закреплен в верхней части каждой страницы. Это интегрировано непосредственно в шаблон thread_view, поэтому простое переключение заставит механизм работать, хотя есть некоторые дополнительные переопределения, которые позволяют легко изменять отображение только закрепленного первого сообщения.
• Выделенные сообщения - это произвольное количество различных сообщений, которые будут запрашиваться на каждой странице. Вы ответственны за контроль того, как и где они будут отображаться. Это то, как сообщение-решение обрабатывается в темах-вопросах, но есть безграничное количество способов, которые могут быть реализованы для улучшения тем.

Кроме того, типы тем позволяют вам переопределять ряд вещей аналогично типам форумов:

• Переопределить отображение потока полностью.
• Переопределите имя используемого представления или шаблона, а так же измените переменные, передаваемые в шаблон.
• Переопределите некоторые из используемых макросов, например, для отображения сообщений, удаленных сообщений или закрепленного первого сообщения, и при необходимости передайте дополнительные аргументы макросам.
• Применение дополнительных фильтров для просмотра тем. Хотя в настоящее время это не используется «из коробки», имело смысл перенести концепцию фильтров на темы, чтобы мы могли применять необходимые изменения поведения при фильтрации.
• Разрешить дополнительные способы сортировки и контролировать порядок по умолчанию. Обратите внимание, что хотя можно изменить порядок потока по умолчанию на что-то отличное от хронологического, хронологическая сортировка всегда будет доступна, и в некоторых случаях мы автоматически переключаемся на нее. Существуют также предостережения о том, что не хронологические порядки отключают некоторые стандартные режимы, в частности, отметки о прочтении темы.
• Настройте Finder для списка сообщений и запрашивайте дополнительные данные для отдельных сообщений.
• Контролировать, когда поддерживается голосование, и проверять соответствующие права.

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

• Методы pre-save, post-save, post-delete для тем.
• Тема сделана видимой или скрытой.
• Тема изменяет свой тип.
• Перестроение счетчиков тем(ы).
• Объединение различных тем.
• Видимое сообщение добавляется в тему или удаляется из нее.
• Сообщение в теме сохранено или удалено.

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

 

[Matew]

Голосование за контент

Голосование за контент — это базовая система для голосования вверх/вниз. Смысл для каждого голосования зависит от содержания, хотя обычно положительный голос представляет что-то хорошее, а отрицательный голос — что-то плохое. Эта система отличается от реакций тем, что положительная реакция не обязательно означает, что контент заслуживает одобрения - забавный пост не обязательно дает хороший ответ на вопрос (на самом деле, вы можете получить несколько «ха-ха», но в итоге иметь отрицательный балл).

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

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

Система предлагает отдельные методы:

• Поддерживается ли голосование.
• Есть ли у пользователя права на голос вверх/вниз.

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

[П\П: Я сильно сомневаюсь в корректности перевода терминов, поэтому если у кого-то есть замечания или предложения - не стесняйтесь их озвучивать. Это касается всего перевода.]

 

[Matew]

Другие примечательные изменения

• Хотя мы упоминали об этом ранее, для XenForo 2.2 теперь потребуется PHP 7.0. Это означает, что мы начали использовать подсказки типов и указывать возвращаемый тип данных там, где это уместно. (Обратите внимание, что типы nullable и void являются частью PHP 7.1, поэтому в настоящее время они не используются.) В настоящее время мы не указываем подсказки типов или возвращаемые типы данных для написанного ранее кода из-за ряда проблем с обратной совместимостью, которые могут появиться.
• Хотя мы не полностью отказались от поддержки IE11, теперь он официально устарел, и посетители, использующие его, увидят баннер, рекомендующий перейти на более новый браузер. Мы прекратим поддержку IE11 в следующем выпуске.
• Мы перенесли все используемые нами компоненты Zend Framework в Laminas. Обычно это просто изменение имени, но пользовательский код, использующий эти компоненты, нуждается в небольшом обновлении. Подробнее об этом читайте в
  У Вас недостаточно прав для просмотра ссылок. Вход или Регистрация
  .
• Хотя здесь мы не будем вдаваться в подробности, новостная рассылка по электронной почте также построена поверх системы обработчиков, что упрощает добавление пользовательских разделов различными дополнениями.
• Аналогично, система создания темы/сообщения перед регистрацией строится поверх общей системы обработчиков «действие перед регистрацией».