Недавно мы работали над обновлением заголовка Discourse: переход от устаревшей системы рендеринга «виджетов» к современным компонентам Glimmer. Это изменение уже доступно в ядре Discourse и управляется настройкой сайта glimmer header mode.
Примерный график
(очень приблизительные оценки — могут измениться в любую сторону)
Q1 2024:
-
реализация в ядре завершена и включена на Meta -
опубликованы рекомендации по обновлению; включены сообщения об устаревании в консоли
-
начата работа по обновлению всех официальных и сторонних плагинов/тем
Q2 2024:
-
начало включения новой реализации заголовка по умолчанию
-
официальные и сторонние темы/плагины готовы к обновлению
-
сообщения об устаревании начинают вызывать предупреждающий баннер для администраторов при наличии оставшихся проблем
Q3 2024:
-
опубликована тема с объявлением для широкого освещения: Preparing your community for behind-the-scenes header changes
-
неделя с 5 августа 2024 года (v3.4.0.beta1): новый заголовок включён по умолчанию для всех сайтов. Администраторы всё ещё смогут переключиться на старый заголовок, изменив настройку сайта
glimmer header mode. -
неделя с 2 сентября 2024 года: окончательное удаление флага функции и устаревшего кода
Что это значит для вас?
Если ваш плагин или тема использует какие-либо API «виджетов» для кастомизации заголовка, их необходимо обновить для совместимости с новым заголовком.
Как попробовать новый заголовок?
В последней версии Discourse новый заголовок автоматически включается, когда все ваши темы и плагины совместимы.
Если ваши темы/плагины не совместимы, будет использоваться старый заголовок, а в консоли вместе с существующими сообщениями об устаревании будет выведено предупреждение. Также администраторам будет показан предупреждающий баннер в интерфейсе.
В маловероятном случае, если эта автоматическая система не сработает как ожидалось, вы можете временно переопределить этот «автоматический флаг функции» через настройку сайта glimmer header mode. Если вы это сделаете, пожалуйста, сообщите нам причину в этой теме.
Нужно ли мне обновлять мой плагин/тему?
Чтобы определить, требует ли ваша кастомизация обновления, проверьте, использует ли она decorateWidget, changeWidgetSetting, reopenWidget или attachWidgetAction для любого из следующих виджетов:
- header
- site-header
- header-contents
- header-buttons
- user-status-bubble
- sidebar-toggle
- header-icons
- header-topic-info
- header-notifications
- home-logo
- user-dropdown
или использует один из следующих методов API плагинов:
addToHeaderIconsaddHeaderPanel
Все эти действия теперь будут вызывать вывод сообщений об устаревании в консоль. ID устаревания:
discourse.add-header-paneldiscourse.header-widget-overrides
Если в вашем экземпляре используется более одной темы, обязательно проверьте все из них.
Уведомление администраторам
По состоянию на 20 июня 2024 года мы включили уведомление администраторам для вышеуказанных устареваний.
Если ваш экземпляр был развёрнут после этой даты и текущие плагины, тема или компоненты темы вашего экземпляра вызывают одно из предупреждений об устаревании, следующее сообщение будет отображаться только для администраторов*:
Это сообщение предназначено только для того, чтобы предупредить администраторов о необходимости скорого принятия мер по модернизации затронутых кастомизаций: старые кастомизации всё ещё будут работать, пока мы не удалим устаревшую кодовую базу.
Чем заменить?
Каждая тема/плагин индивидуальна, но вот рекомендации для наиболее распространённых случаев использования:
addToHeaderIcons
Для пользовательских иконок заголовка мы рекомендуем удалить ваш код и установить официальный компонент темы Custom Header Links (Icons). Если это не отвечает вашим требованиям, см. ниже информацию о необходимых изменениях в коде:
API плагинов addToHeaderIcons устарел в пользу нового API headerIcons. Он предназначен для добавления, удаления или изменения порядка иконок в заголовке. Требуется передача компонента.
Компонент можно передать следующим образом:
| До | После |
|---|---|
| api.addToHeaderIcons(“widget-foo”) | api.headerIcons.add(“foo”, FooIcon) |
| api.decorateWidget(“header-icons:before”, () => return helper.h(“div”, “widget-foo”)) | api.headerIcons.add(“foo”, FooIcon, { before: “search” }) |
| api.decorateWidget(“header-icons:after”, () => return helper.h(“div”, “widget-foo”)) | api.headerIcons.add(“foo”, FooComponent, { after: “search” }) |
В этом примере используется формат шаблонов (gjs) в Ember для определения компонента внутри и передачи его в API headerButtons.add:
// .../discourse/api-initializers/add-my-button.gjs
import DButton from "discourse/components/d-button";
import { apiInitializer } from "discourse/lib/api";
export default apiInitializer("1.0", (api) => {
api.headerIcons.add("some-unique-name", <template>
<li><DButton class="icon btn-flat" @href="/u" @icon="address-book" /></li>
</template>);
});
Или для выпадающего меню можно использовать <DMenu вместо <DButton:
import DButton from "discourse/components/d-button";
import { apiInitializer } from "discourse/lib/api";
import DMenu from "float-kit/components/d-menu";
export default apiInitializer("1.0", (api) => {
api.headerIcons.add("some-unique-name", <template>
<li>
<DMenu class="icon btn-flat" @icon="address-book">
<DButton @translatedLabel="Пользователь 1" @href="/u/user1" />
<DButton @translatedLabel="Пользователь 2" @href="/u/user2" />
<DButton @translatedLabel="Пользователь 3" @href="/u/user3" />
</DMenu>
</li>
</template>);
});
Примеры коммитов обновления:
discourse-icon-header-linksdecorateWidget("header-buttons:*")
Виджет header-buttons устарел, и мы внедрили API плагинов headerButtons. Он предназначен для добавления, удаления или изменения порядка кнопок в заголовке. Требуется передача компонента.
| До | После |
|---|---|
| api.decorateWidget(“header-buttons:before”) | api.headerButtons(“button-name”, ButtonComponent, { before: “auth” }) |
| api.decorateWidget(“header-buttons:after”) | api.headerButtons(“button-name”, ButtonComponent, { after: “auth” }) |
changeWidgetSetting(...) для виджетов заголовка
changeWidgetSettingможно реализовать с помощью следующих компонентов темы:Если они не подходят для вашего случая использования, читайте дальше…
Некоторые кастомизации виджетов заголовка использовали API changeWidgetSetting.
Хотя прямого аналога для кастомизаций, подобных вышеуказанным, нет из-за особенностей работы полей компонентов Glimmer, мы внедрили новый API плагинов в версии Discourse 3.3.0.beta3 для обработки некоторых из этих случаев.
registerValueTransformer можно использовать для переопределения значений, помеченных в исходном коде как переопределяемые; это аналогично тому, как работают выходы плагинов (plugin outlets).
Мы уже добавили два трансформатора для случаев использования, которые часто встречаются в нашей кодовой базе:
-
home-logo-href: можно использовать для переопределения URL в ссылке логотипа главной страницы. См. разделhome-logoниже для примеров. -
header-notifications-avatar-size: можно использовать для изменения размера изображения аватара пользователя в заголовке. Пример:
Код ниже:
api.changeWidgetSetting(
"header-notifications",
"avatarSize",
settings.header_avatars_size
);
Будет преобразован в:
api.registerValueTransformer(
"header-notifications-avatar-size",
() => settings.header_avatars_size
);
Эти трансформаторы необходимо добавить в исходный код Discourse. Если вам нужен другой, пожалуйста, сообщите нам, опубликовав свой случай использования ниже.
Дополнительные сведения о новых API трансформаторов значений можно найти здесь.
home-logo
Мы внедрили выход плагина home-logo вместо декораций виджетов home-logo:before или home-logo:after. Вы можете использовать автоматическое именование __before и __after в вашем файле коннектора, чтобы указать, где должно располагаться ваше пользовательское содержимое.
Дополнительные сведения об именовании файлов коннекторов before/after можно найти здесь.
| До | После |
|---|---|
| api.decorateWidget(“home-logo:before”) | Переместить содержимое в /connectors/home-logo__before |
| api.decorateWidget(“header-buttons:after”) | Переместить содержимое в /connectors/home-logo__after) |
Изменение URL ссылки логотипа главной страницы:
Очень часто возникает необходимость изменить URL, на который ведёт ссылка home-logo. Для решения этой проблемы мы внедрили трансформатор значений home-logo-href. Примеры:
-
для изменения ссылки на статический URL
api.registerValueTransformer("home-logo-href", () => "https://example.com"); -
для возврата динамического URL на основе текущего пользователя
api.registerValueTransformer("home-logo-href", () => { const currentUser = api.getCurrentUser(); return `https://example.com/${currentUser.username}`; }); -
для возврата URL на основе настройки компонента темы
api.registerValueTransformer("home-logo-href", () => { return settings.example_logo_url_setting; });
А как насчет других кастомизаций?
Если вашу кастомизацию невозможно реализовать с помощью CSS, PluginOutlets или новых API, которые мы внедрили, пожалуйста, сообщите нам, создав новую тему в канале Development для обсуждения.
Как обновить тему/плагин для поддержки как старого, так и нового заголовка?
Все новые API и выходы плагинов, перечисленные в этом документе, поддерживаются как в новом, так и в старом заголовке. Поэтому вам нужно внести только одно обновление в вашу тему/плагин сейчас, и пользователи будут готовы к переходу.
Сегодня мы объединили 
действительно верно, и я был более готов учиться, более амбициозен, чувствовал, что это стоит того. С тех пор меня били, сбивали с ног и оставляли умирать.
и ещё раз благодарю за любую помощь, которую другие могут предложить.
