Предстоящие изменения в списке тем — как подготовить темы и плагины

Разработка
1

В рамках нашей ongoing-кампании по стандартизации систем рендеринга в кодовой базе Discourse мы заменяем реализацию списка тем.

Ранее использовался подход «raw handlebars» (.hbr), который можно было кастомизировать через переопределения шаблонов и raw-plugin-outlets. Новая реализация списка тем построена на современных компонентах Glimmer и разработана с нуля для устойчивой и долговечной кастомизации.

Новая реализация доступна через настройку glimmer_topic_list_mode:

  • disabled: используется устаревший «raw handlebars» список тем
  • auto: автоматически определяет совместимость ваших текущих плагинов и тем. Если найдены несовместимые элементы, будет использована устаревшая система; в противном случае — новая реализация.
  • enabled: используется новая реализация списка тем. Если у вас есть несовместимые плагины или темы, сайт может работать некорректно.

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

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

:timer_clock: График внедрения

Это приблизительные оценки, которые могут быть изменены

IV квартал 2024 года:

  • :white_check_mark: реализация в ядре завершена
  • :white_check_mark: обновление официальных тем/плагинов (в процессе)
  • :white_check_mark: включено на Meta
  • :white_check_mark: опубликованы рекомендации по обновлению

I квартал 2025 года:

  • :white_check_mark: обновление официальных тем/плагинов

  • :white_check_mark: настройка glimmer_topic_list_mode по умолчанию установлена в auto; включены сообщения об устаревании в консоли

  • :white_check_mark: предупреждения об устаревании будут вызывать административное предупреждение для любых оставшихся проблем

  • сторонние плагины и темы должны быть обновлены

  • :white_check_mark: 1 марта — включение нового списка тем для всех сайтов. Значение по умолчанию для настройки сайта будет изменено на enabled, но возможность переключения обратно на disabled останется

II квартал 2025 года

  • :white_check_mark: после 1 апреля — окончательное удаление устаревшего режима и связанного кода

:eyes: Что это значит для вас?

Если ваш плагин или тема содержат файлы «raw handlebars» (с именами .hbr или .raw.hbs), их необходимо обновить для совместимости с новой версией. Обычные файлы .hbs для компонентов/маршрутов Ember не затрагиваются этим изменением.

Обновление также потребуется, если вы используете modifyClass для component:topic-list или component:topic-list-item.

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

Какие замены предусмотрены?

Некоторые старые raw-plugin-outlets были преобразованы в обычные Plugin Outlets. Их можно обновить в режиме 1:1.

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

Вот несколько примеров:

:sos: А как насчет других кастомизаций?

Если вашу кастомизацию невозможно реализовать с помощью новых API, которые мы представили, пожалуйста, сообщите нам, создав новую тему Development для обсуждения.

:sparkles: Я автор плагина/темы. Как обновить тему/плагин для поддержки как старого, так и нового списка тем в период перехода?

Новые plugin outlets рендерятся как в старой, так и в новой реализации списка тем. Поэтому: после реализации новой версии просто удалите старый raw-plugin-outlet connector.

Для кастомизаций на основе DAG, которые заменяют переопределения шаблонов или несовременные outlets, необходимо поддерживать обе реализации в течение переходного периода.

Как только ваша тема/плагин поддерживает обе реализации, вы можете добавить этот магический комментарий в начало всех ваших файлов .hbr:

{{!-- has-modern-replacement --}}

Это отключит сообщения об устаревании и позволит использовать новую реализацию в режиме «auto».

2

Извините за придирки, но разве это не означает скорее «если у вашего плагина или темы есть какие-либо файлы «сырых handlebars», которые имеют отношение к списку тем, то их необходимо обновить»?

Мои файлы сырых handlebars, связанные с другими моделями, останутся в порядке, верно? Или файлы сырых handlebars исчезнут полностью? (Кажется, они требуются для дополнительных моделей/маршрутов, верно?)

3

“Raw handlebars” означает наши специфичные для Discourse шаблоны, которые имеют расширение файла .hbr (или исторически .raw.hbs). Мы использовали эту систему только для списка тем и некоторых внутренних механизмов автодополнения.

Другие файлы .hbs (например, для компонентов Ember или маршрутов) не затронуты.

Я обновлю первое сообщение, чтобы сделать это более понятным. Спасибо @pfaffman!

Редактирование: вот так:

4

О. Вы действительно постарались сделать всё максимально понятно. Вы явно указали расширения. Я не думаю, что можно сделать это ещё яснее. Думаю, в этом случае вина на мне. :person_shrugging:

Но, возможно, добавление дополнительного предложения помогло бы мне прочитать это.

5

Спасибо за информацию. Я давно этого боялся, и это происходит… :grimacing: Похоже, это будет непростой путь… :sweat_smile: Но, вероятно, value transformer всё упростит. :crossed_fingers:

6

Полагаю, GitHub - discourse/discourse-topic-excerpts: Add topic excerpts to all topics in the topic list · GitHub ещё не обновлён?

7

Да, у нас ещё много официальных тем/плагинов, требующих обновления. Я перенесу этот пункт в раздел Q1 в исходном сообщении :writing_hand:

8

Спасибо! Пока что мне нравится процесс разработки! Дам знать, если TLP вызовет какие-либо проблемы, когда дойду до этого этапа.

9

Круто! Официальный список тем с миниатюрами — один из тех, которые мы уже обновили, так что это может послужить полезным ориентиром.

10

О, моя ошибка! @isaac обновил topic-excerpts на прошлой неделе: DEV: Update plugin for `glimmer-topic-list` (#34) · discourse/discourse-topic-excerpts@0dd3c6c · GitHub

Так что всё должно работать нормально в новом списке тем :crossed_fingers:

11

Я получаю:

Сообщение об ошибке на веб-сайте с предупреждением об ошибке, вызванной 'Topic List Excerpts'. (Подпись сгенерирована ИИ)
Сообщение об ошибке на веб-сайте с предупреждением об ошибке, вызванной 'Topic List Excerpts'. (Подпись сгенерирована ИИ)1302×164 24.6 KB

image
image644×144 19.5 KB

На изображении показан интерфейс для включения режима «Glimmer topic list mode» с кнопкой сброса. (Подпись сгенерирована ИИ)
На изображении показан интерфейс для включения режима «Glimmer topic list mode» с кнопкой сброса. (Подпись сгенерирована ИИ)1432×300 18.8 KB

Обе версии актуальны.

12

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

Используя:

api.registerValueTransformer("topic-list-header-sortable-column"

в дополнение к другому трансформеру?

      api.registerValueTransformer(
        "topic-list-columns",

Похоже, этого недостаточно само по себе? :thinking:

13

cc @isaac. Если бы мне пришлось гадать: возможно, новую логику нужно обновить, чтобы она обрабатывала темы без категории?

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

Если вы добавляете новый столбец, то вам следует просто определить свой заголовок, используя компонент SortableColumn. Например, вот один из ядра:

(одной из действительно приятных особенностей нового API является то, что все столбцы ядра определяются с использованием того же API, что и вы в темах и плагинах!)

14

Да, я заметил это, когда искал в коде, здорово!

15

Исправлено :slight_smile:

16

Вопрос: Можно ли назначить полный компонент ячейке, а не только <template>?

Например, что если я хочу отобразить прозрачную кнопку в ячейке, для которой требуется минимальная логика JavaScript?

17

Да! Технически, простой тег <template> создаёт «компонент только с шаблоном». Это аналогично типу компонента, который получается при помещении простого файла .hbs в директорию components/.

Так что да, импорт и передача обычного класса компонента будут работать точно так же. Это также будет работать с классическими компонентами! (хотя, конечно, мы рекомендуем использовать более современные компоненты Glimmer).

18

Это просто потрясающе!

Это меняет… очень много! :exploding_head:

20

Возможно, глупый вопрос.

Но как применить изменения к… мобильному списку тем?

21

Для мобильных устройств у нас есть множество новых выходов плагинов (включая обёрнутые выходы).

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

На следующей неделе я планирую написать более подробную инструкцию «Как настроить список тем» Documentation > Developer Guides, поэтому обязательно включу эту информацию туда.