Discourse のヘッダーを従来の「ウィジェット」レンダリングシステムから現代的な Glimmer コンポーネントへ更新する作業を最近 行ってきました。この変更は、Discourse コアにおいて glimmer header mode サイト設定の背後で利用可能になりました。
概算タイムライン
(非常に大まかな見積もりです。前後する可能性があります)
2024 年第 1 四半期:
-
コア実装完了、Meta で有効化 -
アップグレードに関するアドバイス公開、コンソール上の非推奨メッセージ有効化 -
公式およびサードパーティ製プラグイン/テーマの更新作業開始
2024 年第 2 四半期:
-
新しいヘッダー実装のデフォルト有効化開始 -
公式およびサードパーティ製テーマ/プラグインがアップグレードに対応 -
非推奨メッセージにより、残存する問題に対して管理者警告バナーが表示され始める
2024 年第 3 四半期:
-
広範な周知のためのアナウンストピック投稿:Preparing your community for behind-the-scenes header changes -
2024 年 8 月 5 日週(v3.4.0.beta1):新しいヘッダーがすべてのサイトでデフォルトで有効化されます。管理者は glimmer header modeサイト設定を切り替えることで、引き続き旧ヘッダーに戻すことが可能です。 -
2024 年 9 月 2 日週:機能フラグとレガシーコードの最終削除
これは私にとって何を意味しますか?
プラグインやテーマがヘッダーのカスタマイズに「ウィジェット」API を使用している場合、新しいヘッダーとの互換性のために更新が必要です。
新しいヘッダーを試すには?
Discourse の最新バージョンでは、すべてのテーマ/プラグインが互換性がある場合、新しいヘッダーが自動的に有効になります。
テーマ/プラグインが互換性がない場合、レガシーヘッダーが引き続き使用され、既存の非推奨メッセージ alongside コンソールに警告が出力されます。また、UI 上でも管理者に警告バナーが表示されます。
まれに、この自動システムが期待通りに動作しない場合、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
インスタンスで複数のテーマを使用している場合は、すべてを確認してください。
管理者通知
2024 年 6 月 20 日より、上記の非推奨に関する管理者通知を有効にしました。
この日以降にデプロイされたインスタンスで、現在のプラグイン、テーマ、またはテーマコンポーネントが非推奨警告のいずれかをトリガーする場合、以下のメッセージが管理者*のみに表示されます。
このメッセージは、影響を受けるカスタマイズを近代化するために早急に対応する必要があることを管理者に警告するものです。レガシーコードベースが削除されるまで、古いカスタマイズは引き続き機能します。
代替手段は何ですか?
テーマやプラグインはそれぞれ異なりますが、最も一般的なユースケースに対するガイダンスを以下に示します。
addToHeaderIcons
カスタムヘッダーアイコンについては、コードを削除し、公式の Custom Header Links (Icons) Theme Component をインストールすることを推奨します。要件を満たさない場合は、必要なコード変更の詳細については以下をご覧ください。
addToHeaderIcons プラグイン API は、新しい headerIcons API の採用により非推奨となりました。ヘッダー内のアイコンの追加、削除、または並べ替えを可能にするために存在します。コンポーネントの渡しが必須です。
コンポーネントは以下のように渡します。
| 以前 | 以後 |
|---|---|
| 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” }) |
この例では、Ember の Template Tag Format (gjs) を使用して、コンポーネントをインラインで定義し、headerButtons.add API に渡しています。
// .../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>);
});
または、ドロップダウンの場合は、<DButton の代わりに <DMenu を使用できます。
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="User 1" @href="/u/user1" />
<DButton @translatedLabel="User 2" @href="/u/user2" />
<DButton @translatedLabel="User 3" @href="/u/user3" />
</DMenu>
</li>
</template>);
});
アップグレードのコミット例:
decorateWidget("header-buttons:*")
カスタムヘッダーリンクについては、コードを削除し、公式の Custom Header Links Theme Component をインストールすることを推奨します。要件を満たさない場合は、必要なコード変更の詳細については以下をご覧ください。
header-buttons ウィジェットは非推奨となり、新しい headerButtons プラグイン API が導入されました。ヘッダー内のボタンの追加、削除、または並べ替えを可能にするために存在します。コンポーネントの渡しが必須です。
| 以前 | 以後 |
|---|---|
| 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の最も一般的な使用例は、以下のテーマコンポーネントで達成できます。これらがユースケースに合わない場合は、以下をお読みください…
ヘッダーウィジェットのカスタマイズの一部は、changeWidgetSetting API を使用していました。
上記のようなカスタマイズに対する直接的な代替手段はありませんが、Glimmer コンポーネントのフィールドの動作方法により、Discourse 3.3.0.beta3 でこれらのケースの一部を処理するための新しいプラグイン API が導入されました。
registerValueTransformer は、ソースコード内で上書き可能としてタグ付けされた値を上書きするために使用できます。これは、プラグイン outlets が機能する方法と類似したアプローチです。
ソースコードベースで一般的に見つかったユースケースに対して、すでに 2 つのトランスフォーマーを追加しました。
-
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:before または home-logo:after のウィジェット装飾に代わるものとして、home-logo プラグイン outlet を導入しました。コネクタファイルで自動的な __before および __after 命名規則を使用して、カスタムコンテンツを配置する場所を指定できます。
前後のコネクタファイル命名に関する詳細は こちら で確認できます。
| 以前 | 以後 |
|---|---|
| api.decorateWidget(“home-logo:before”) | コンテンツを /connectors/home-logo__before に移動 |
| api.decorateWidget(“header-buttons:after”) | コンテンツを /connectors/home-logo__after に移動 |
ホームロゴアンカー URL の変更:
非常に一般的な要件として、home-logo がリンクする URL を変更する場合があります。これに対処するために 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 とプラグイン outlets は、新しいヘッダーと古いヘッダーの両方でサポートされています。したがって、テーマ/プラグインの更新は現在 1 回だけで済み、ユーザーは切り替えの準備が整います。




