これらのガイドラインは、使いやすさ、アクセシビリティ、構造化されたレイアウトに焦点を当てて、一貫性のある管理インターフェースを作成することを目的としています。目次を参照して、含まれている内容を確認し、各セクションに簡単に移動してください。
注: ここで使用されている用語は、管理インターフェース用語集で定義されています。
0. 序論 - 設定ページの構造とサイドバーリンク
管理インターフェースに新しい設定ページを追加する際、各ページにはサイドバー用のリンクが必要であり、またタイトルとヘッダーの説明の両方が必要になります。これはどこでも一貫性を保つためであり、将来の管理検索の機能強化により、管理インターフェースのレイアウト全体を表示できるようにするためです。
一般的に、管理インターフェースの構造は次のようになります。
- 管理インターフェース
- 設定ページ（サイドバーに表示）
- 設定タブ
- オプションの他の3階層タブ
- リソース用の編集/新規3階層ページ
- 設定ページ（サイドバーに表示）
最終的に、「セクション概要」がルートインターフェースと設定ページの間に挿入されます。
サイドバーリンク
すべての管理ページは、discourse/frontend/discourse/app/lib/sidebar/admin-nav-map.js at main · discourse/discourse · GitHub の ADMIN_NAV_MAP に追加される必要があります。各項目には、少なくとも次のキーが必要です。
name- リンク用の一意の識別子で、snake_caseにする必要がありますrouteまたはhref-routeはadminUsersのような Ember ルート識別子です。管理者用は 管理ルートマップ で定義されています。hrefを代わりに使用することもできますが、routeが推奨されます。labelまたはtext- Label は I18n キーで、通常admin.config.page_name.titleである必要があります（下の翻訳セクションを参照）。textを使用する場合、すでに翻訳されたテキストになります。
次のオプションのキーも提供できます。
description- これも提供することを推奨します。I18n キーで、通常admin.config.page_name.header_descriptionである必要があります。icon- これも推奨されます。サイドバーのリンクの横に表示されます。routeModels- ルートパラメータの場合のURLデータの配列。例えばadminCustomizeThemesには:typeルートパラメータがあるため、routeModels: ["components"]を渡すことができます。配列の項目は、ルートパラメータが出現する順序と同じ順序で使用されます。moderator: モデレーターがサイドバーにこのページを表示する必要がある場合は、これをtrueに設定します。keywords: I18n キーで、|で区切られたサイドバーリンクのキーワードリスト。ページをフィルタリング/検索する際の追加の「検索ジュース」に使用されます。links: サイドバー上のページの下の3階層ルートのリスト。これらはサイドバー自体には表示されません。これは将来の管理検索機能で使用されます。settings_areaとsettings_category: ページがフィルタリングされたサイト設定のリストのみを表示する場合、これらのいずれかが入力される必要があります。サイト設定にAdminAreaSettingsで使用されるareaが定義されている場合、settings_areaを使用します。ページに設定の entire カテゴリが表示されており、AdminAreaSettingsでも使用されている場合、settings_categoryを使用します。multi_tabbed: ページに設定タブと他のタブがある場合、これを true に設定します。管理検索システムのリンク生成に役立ちます。
翻訳
すべての設定ページのタイトルとヘッダー説明は、次の下に配置される必要があります。
- admin
- config
- page_name
- title: “Page title”
- header_description: “This page is for xyz”
- page_name
- config
これの例はここで確認できます。
1. パンくずリスト
パンくずリストはナビゲーションツールとして機能し、ユーザーが管理インターフェース内での現在の場所、コンテンツ構造、階層を理解するのを助けます。
Admin > Breadcrumb > Trail
Page title
デザイン
構造
- Admin: 各パンくずリストの先頭に表示される固定プレフィックスで、
/adminにリンクします - Link: ページを同じウィンドウで開きます
- Separator:
angle-rightアイコンが各リンクを区切ります
使用法
いつ使用する:
- すべての管理ページに表示されます
- コンテンツ（タイトル、説明、タブ）の上に配置されます
- 現在選択されているページを表示します
いつ使用しない:
- 新規または編集ルートにアクセスする場合
コンテンツ
- 各項目には、関連ページへのリンクが含まれます
- 現在選択されているページを表示します
アクセシビリティ
aria-label="Breadcrumb"を持つnav要素が順序付きリストを囲み、ナビゲーションランドマークを提供します- 最後のリンクに
aria-current="page"を適用して、それが現在のページであることを示します - 詳細については、WAI-ARIA Authoring Practices Breadcrumb Example を参照してください
実装
DBreadcrumbsContainer コンポーネントをページのどこかに配置する必要があります。
<DBreadcrumbsContainer />
その後、ルートまたは子ルート上の任意のコンポーネントに追加されたすべての DBreadcrumbsItem 要素が、このコンテナにレンダリングされます。各 DBreadcrumbsItem には、@label と @path を提供する必要があります。
<DBreadcrumbsItem @path="/admin" @label={{i18n "admin_title"}} />
<DBreadcrumbsItem
@path="/admin/plugins"
@label={{i18n "admin.plugins.title"}}
/>
<DBreadcrumbsItem
@path="/admin/plugins/{{@plugin.name}}"
@label={{@plugin.nameTitleized}}
/>
Discourse AI プラグインを使用した視覚的な例:
2. ページヘッダーとタイトル
管理ページの上部セクションで、ページタイトル、オプションのアクション、説明を含みます。
デザイン
構造
-
ページタイトル: ページのタイトル
-
ページ説明: コンテンツの内容に関する導入または説明 (オプション)
-
プライマリアクション: ページタイトルのプライマリアクション (オプション)
-
セカンダリアクション: ページタイトルのセカンダリアクションボタン設定 (オプション)
使用法とコンテンツ
-
ページタイトル: ヘディングレベル1を使用して、ページの本題をセンテンスケースで説明します。通常、I18n 翻訳は
admin.config.your_page.titleの下にある必要があります。 -
ページ説明:
_italic_、**bold**、[link name](url)などの基本的なマークダウンノードをサポートします -
プライマリアクション:
btn-primaryを使用します。アイコンを含めないでください。通常、I18n 翻訳はadmin.config.your_page.header_descriptionの下にある必要があります。 -
セカンダリアクション:
btn-defaultボタン設定を使用し、プライマリアクションが存在する場合のみ表示されます。アイコンを含めないでください。
アクションボタンは明確にしてください。例えば、「Add emoji」のような記述的なラベルを使用し、「Add」のみにして曖昧さを減らします。
実装
ここで DPageHeader コンポーネントが使用されます。これは @titleLabel、@descriptionLabel、@learnMoreUrl、@shouldDisplay の引数を受け取ります。Ember の名前付き yields を使用して、コンテンツ用の5つの名前付きブロックを提供します。
breadcrumbs- ページ用の追加のDBreadcrumbsItemコンポーネントをここに配置します。actions- タイトルの右側のボタンを定義するために使用されます。Default、Primary、Danger、Wrappedボタンをレンダリングするために使用できるactionsというオブジェクトを yield します。title-@titleLabelの代替で、ヘディング内にカスタムマークアップを許可します。drawer-@showDrawerが true の場合に表示されるオプションの折りたたみ式ドロワーセクション。tabs-NavItemコンポーネントを使用してページのタブを定義するために使用されます。@hideTabsを使用して、必要ない場合はヘッダーのこの部分を削除できます。
完全な例は以下です。
<DPageHeader
@titleLabel={{i18n "admin.config.backups.title"}}
@descriptionLabel={{i18n "admin.config.backups.header_description"}}
@learnMoreUrl="https://meta.discourse.org/t/create-download-and-restore-a-backup-of-your-discourse-database/122710"
>
<:breadcrumbs>
<DBreadcrumbsItem
@path="/admin/backups"
@label={{i18n "admin.backups.title"}}
/>
</:breadcrumbs>
<:actions as |actions|>
<actions.Primary
@action={{routeAction "showStartBackupModal"}}
@title="admin.backups.operations.backup.title"
@label="admin.backups.operations.backup.label"
class="admin-backups__start"
/>
</:actions>
<:tabs>
<NavItem
@route="admin.backups.settings"
@label="settings"
class="admin-backups-tabs__settings"
/>
<NavItem
@route="admin.backups.index"
@label="admin.backups.menu.backup_files"
class="admin-backups-tabs__files"
/>
<NavItem
@route="admin.backups.logs"
@label="admin.backups.menu.logs"
class="admin-backups-tabs__logs"
/>
<PluginOutlet @name="downloader" @connectorTagName="div" />
</:tabs>
</DPageHeader>
ブラウザタブのページタイトルは、titleToken 機能を使用して Ember ルートで処理されます。これをルートで使用するたびに、トークンがブラウザタブタイトルの末尾に追加されます。これを実行するには、通常の Ember の Route ではなく DiscourseRoute クラスを拡張して必ず使用してください。
titleToken() {
return i18n("admin.config.backups.title");
}
/newおよび/editパスに対して自動的に非表示になります。@shouldDisplay引数を使用して上書きできます。
3. タブ
設定や機能のより深いレベルへのアクセスを提供するオプションのナビゲーションです。これを「3階層」ページまたはナビゲーションとも呼びます。
デザイン
同じコンテキスト内の異なるが関連するビュー間で切り替えるためにタブを使用しています。
使用法
- プライマリナビゲーションには使用しません
- 一度に1つのみがアクティブです
実装
ページヘッダーの詳細を参照してください。タブは DPageHeader コンポーネントで定義されています。
4. 概要/セクションランディングページ
サイドバーが折りたたまれている場合やモバイルの場合など、セクションの内容を表示できるようにします。
デザイン
構造
グリッドシステムを使用して3つの等しい列レイアウトを使用します。小さな画面では、これらの列は垂直に積み重なります。
デザインと使用法
- パンくずリスト（Admin > Community > Overview）を介してアクセスできます
- プラグイン（インストール済みを表示）とレポート（1ページのみ）を除き、各セクションに1つある必要があります
- アイテムには次のものがあります。
- 名前 - セクションリンクと同じ
- 説明 - ページの内容に関する短い説明
- アイコン - サイドバーに使用される同じアイコン
実装
コードスニペットまたはトピック/GitHubへのリンク
5. ページコンテンツ
設定、構成、その他のコンテンツが表示され、相互作用が行われる管理ページのメインエリアです。
デザイン
構造
グリッドシステムを使用して2/3 + 1/3のレイアウトを使用します。プライマリセクションは3分の2を占め、セカンダリセクションは3分の1を占めます。小さな画面では、これらの列は垂直に積み重なります。
- 設定エリア: 設定と構成に専念したページコンテンツ内の特定のセクション。
- ヘルプ/リファレンス/インセット: ガイド、ドキュメント、または追加の文脈情報を提供するページコンテンツ内のエリア。(オプション)
デザインと使用法
- 類似した設定とアクションをカードにグループ化します
- プライマリ/セカンダリレイアウトを構造化し、プライマリ（2/3）セクションをメイン設定に、セカンダリ（1/3）セクションを追加情報や有用な文脈に使用します
- セカンダリセクションが利用できない場合、プライマリセクションの幅を同じに保ちます
コンテンツ
実装
コードスニペットまたはGitHubリンク
5.a. サブヘッダー
サブヘッダーは、セクション下のコンテンツを区切るために使用される二次的な見出しで、通常タブの下にあります。
構造
- サブヘッダー: コンテンツの内容に関するサブヘッダー (オプション)
- プライマリアクション: サブヘッダーのプライマリアクション (オプション)
- セカンダリアクション: サブヘッダーのセカンダリアクションボタン設定 (オプション)
使用法とコンテンツ
-
サブヘッダー: ヘディングレベル2を使用して、関連コンテンツの本題を説明します。次の場合にのみ含みます。
- プライマリアクションボタンがある場合、または
- セクションを説明する説明がある場合。
-
プライマリアクション:
btn-primaryを使用します。アイコンを含めないでください。 -
セカンダリアクション:
btn-defaultボタン設定を使用し、プライマリアクションが存在する場合のみ表示されます。アイコンを含めないでください。 アクションボタンは明確にしてください。例えば、「Add emoji」のような記述的なラベルを使用し、「Add」のみにして曖昧さを減らします。
実装
これは DPageHeader に似ており、DPageSubheader コンポーネントがあります。主な違いは、actions のための単一の名前付き yield しかないことです。
actions- タイトルの右側のボタンを定義するために使用されます。Default、Primary、Danger、Wrappedボタンをレンダリングするために使用できるactionsというオブジェクトを yield します。
<DPageSubheader @titleLabel="admin.config.backups.subheader.title">
<:actions>
<actions.Primary
@action={{routeAction "showStartBackupModal"}}
@title="admin.backups.operations.backup.title"
@label="admin.backups.operations.backup.label"
class="admin-backups__start"
/>
</:actions>
</DPageSubheader>
5.b. 設定エリア
設定エリアはカードまたはセクションで構成されています。カードは関連する情報とタスクをグループ化するのに優れており、ユーザーがコンテンツをスキャンし、優先順位をつけるのを容易にします。
デザイン
カード
カードは2pxのボーダー半径で設定され、--secondary の背景を使用します。また、--primary-low の1pxのソリッドボーダーと、コンテンツの周りの20pxのパディングがあります。
デフォルトバリエーション
アコーディオンバリエーション
デザインと使用法
- 関連する情報をグループ化します
- 管理者とモデレーターが最も重要なものを最初に表示するように情報を表示します
- カードの目的を明確に説明する見出しを使用します
- 必要に応じて、複雑なものを複数のセクションに分割します
デフォルトバリエーション
- カードあたり1つのプライマリコールトゥアクションにこだわります
- 次のステップのために、プライマリコールトゥアクションをカードの底部に配置します
アコーディオンバリエーション
- カードの右上隅を「View all」などのオプションのアクションに使用します
コンテンツ
-
すべてのフォームは、ドキュメントで説明されているコアの FormKit Ember コンポーネントを使用する必要があります
-
カードヘッダーはセンテンスケースにする必要があります
推奨
非推奨General settings General Settings Contact information CONTACT INFORMATION
実装
これらのすべてのカードに使用される AdminConfigAreaCard コンポーネントがあります。現在、これには @translatedHeading と @heading 引数のみが含まれていますが、将来アクションを追加して折りたたみ可能などにすることができます。
<AdminConfigAreaCard
@heading="admin.config_areas.about.general_settings"
class="admin-config-area-about__general-settings-section"
>
<AdminConfigAreasAboutGeneralSettings
@generalSettings={{this.generalSettings}}
@setGlobalSavingStatus={{this.setSavingStatus}}
@globalSavingStatus={{this.saving}}
/>
</AdminConfigAreaCard>
埋め込みサイト設定
このセクションは進行中です。
5.c. ヘルプインセット
このセクションは、ページコンテンツ内で追加のガイダンス、ドキュメント、または文脈を提供します。
v1
デザイン
デザインと使用法
- ページのコンテンツに関する関連ドキュメントまたはガイドを表示して、有用な情報を提供します
- 見出しにアイコンを含めて、簡単に認識できるようにします
- このセクションをセカンダリ（1/3）レイアウトエリアに配置します
コンテンツ
- ヘッダーはセンテンスケースにする必要があります
実装
コードスニペットまたはトピック/GitHubへのリンク
5.d. テーブル
テーブルは情報をセル、列、行のグリッドで表示し、管理者がアイテムをすばやくスキャンしてアクションを実行しやすくします。
デザイン
使用法
- 各エントリが同じ属性を共有する構造化されたコンテンツを表示するためにテーブルを使用します。
- 管理者がデータセットを確認、有効/無効、編集、削除できるようにします。
- 時間とともに成長し続けるデータセットに適しています。
デザイン
- 行の間に水平線を使用して視覚的にコンテンツを区切り、最後の行も含めます。テーブルがネットのように見えないようにするために、テーブルの周りにボーダーまたはフレームを使用しないでください。
- 列の間に垂直線を適用しないでください。垂直線のないテーブルは一般的にスキャンしやすく、読みやすいです。
追加アクション
- 行アクション: 各テーブル行の最右列に追加アクションを含めます。
- インタラクティブな要素が2つ以上ある場合、プライマリアクション（例：「Edit」）はテキストボタンにする必要があり、他のすべての行アクション（「Delete」を含む）は
[...]ドロップダウンにグループ化する必要があります。ドロップダウンメニュー内のアイコンは、視覚的に区切るために推奨されます。 - 「Delete」アクションのみがあり、プライマリアクションがない場合、
btn-defaultスタイルのインライン「Delete」テキストボタンを使用します。 - メイン列のテキスト（一般的に
d-table__cell --overview）を、行に対応する Show/Edit ページに直接管理者を連れて行くリンクでラップする必要があります。
- インタラクティブな要素が2つ以上ある場合、プライマリアクション（例：「Edit」）はテキストボタンにする必要があり、他のすべての行アクション（「Delete」を含む）は
- 削除確認: すべての「Delete」ボタンは、アクションを実行する前に確認を表示する必要があります。
コンテンツ
- ヘッダー: テーブルヘッダーは、下の列を識別する最上段です。データが記述的でないか曖昧な場合、特に明確さを提供します。ヘッダーは短く、記述的で、関連性があり、タイトルケースを使用する必要があります。下の行のコンテンツに対して長すぎるヘッダーを避けてください。
- 列: 優先順位またはデータと連なる物語を語る方法で列を順序付けます。列のサイズはコンテンツに合わせて、小さなコンテンツには狭い列、段落には広い列を使用します。
- 行: 行は、データプレゼンテーションを強化するためにテキスト、ボタン、リンク、アイコンをサポートする必要があります。
- データなし: 空のリストは、
AdminConfigAreaEmptyListコンポーネントを使用して、CTAボタンとラベルでユーザーを新しいレコードの作成に導きます
実装
テーブルをモバイルとデスクトップでうまく機能させるために使用される必要があるCSSクラスの小さなコレクションがあります。
<table> 要素には d-table クラスを適用する必要があります。
<thead> 要素には d-table__header クラスを適用する必要があります。
<tr> 要素には d-table__row クラスを適用する必要があります。
<td> 要素（通常は最左列）に多くの記述的なテキストが含まれている場合、d-table__cell --overview クラスを使用する必要があります。他のすべてのセルは d-table__cell --detail を使用します。
<td> 要素に d-table__cell --overview クラスがある場合、内部の行コンテンツを、行の Edit/Show ページに直接管理者を連れて行くリンクでラップできます。このリンクは次の構造に従い、d-table__overview-link CSSクラスを適用する必要があります。理想적으로는 LinkTo コンポーネントを使用すべきですが、getURL と一緒に使用すれば <a> でも問題ありません。
d-table__overview-name クラスは、ここでの名前部分に適用する必要がありますが、説明には適用しません。
<td class="d-table__cell --overview">
<LinkTo
class="d-table__overview-link"
@route="adminPlugins.show.explorer.details"
@model={{query.id}}
>
<strong class="query-name d-table__overview-name">{{query.name}}</strong>
{{#if query.is_default}}
<span class="query-badge">{{i18n
"explorer.default_query"
}}</span>
{{/if}}
<div class="query-desc">{{query.description}}</div>
</LinkTo>
</td>
<td class="d-table__cell --overview">
<a class="d-table__overview-name admin-flag-item__name d-table__overview-link" href={{this.editUrl}}>
{{@flag.name}}
</a>
</td>
各列のボタンをラップする <td> 要素には、d-table-cell --controls CSSクラスを適用する必要があります。これにより、ボタンが整列します。各ボタンにも btn-small クラスを適用する必要があります。
モバイルの場合、d-table-cell --overview 以外の各 <td> 要素には、d-table__mobile-label クラスを持つ <div> を含める必要があります。これは、その列の <th> と同じI18nラベルを含みます。
<td class="d-table__cell --detail">
<div class="d-table__mobile-label">
{{i18n "chat.incoming_webhooks.emoji"}}
</div>
{{replaceEmoji webhook.emoji}}
</td>
これにより、テーブル行はモバイルで読みやすいカードベースのフォーマットとして表示されます。
[...] ドロップダウンメニューには、DropdownMenu と一緒に DMenu を使用する必要があります。例は次の通りです。
<DMenu
@identifier="backup-item-menu"
@title={{i18n "more_options"}}
@icon="ellipsis-vertical"
class="btn-small"
>
<:content>
<DropdownMenu as |dropdown|>
<dropdown.item>
<DButton ...[button args here] />
</dropdown.item>
<dropdown.item>
<DButton ...[button args here] />
</dropdown.item>
</DropdownMenu>
</:content>
</DMenu>
テーブル行内のトグルは、DToggleSwitch コンポーネントを使用して処理されます。
<DToggleSwitch
@state={{this.enabled}}
class="admin-flag-item__toggle {{@flag.name_key}}"
{{on "click" (fn this.toggleFlagEnabled @flag)}}
/>
すべてをまとめた最小限の管理テーブルの例は次の通りです。
<table class="d-table">
<thead class="d-table__header">
<tr>
<th>Name</th>
<th>Description</th>
<th></th>
</tr>
</thead>
<tbody>
<tr class="d-table__row">
<td class="d-table__cell --overview">
<LinkTo @route="admin.exampleRoute" class="d-table__overview-link">
<span class="d-table__overview-name">Example Item</span>
<span class="d-table__overview-about">A short description</span>
</LinkTo>
</td>
<td class="d-table__cell --detail">
<span class="d-table__mobile-label">Description</span>
Some detail content here
</td>
<td class="d-table__cell --controls">
<div class="d-table__cell-actions">
<button class="btn btn-default btn-small">Edit</button>
</div>
</td>
</tr>
</tbody>
</table>
5.e 3階層ルート
3階層ルートは、設定エリアからのみ到達できるルートです。これらは通常、次のようなフラグ用の編集/新規ルートの形をしています。
ほとんどの場合、FormKit を使用したフォームがここに表示されます。
これらには標準の RESTful ルートを使用します。
| アクション | パス |
|---|---|
| 新規 | <resource>/new |
| 編集 | <resource>/:id/edit |
そして、ルートがバックエンドでもルーティングされていることを確認してください。（新規または編集ページをリロードしてもエラーが発生しないようにします。）
デザイン
使用法
- メインルートまたはテーブル内のインラインフォームよりも、これらの3階層ルートを持つことを優先します。スタンドアロンの編集および新規ルートが最善です。これらは簡単にリンクに含めることができます。
- ページUIの上部部分（パンくずリスト、ページヘッダー、サブヘッダー）を表示しないでください
- その代わりに、管理者がメイン設定エリアに到達できるようにする単一の「Back to X」リンクを表示します
- ページのコンテンツは、少なくとも1つの
AdminConfigAreaCardでラップする必要があります - ページ上の任意のサブタイトルは、設定エリアカードで実行する必要があります
実装
ページの上部で使用できる単純な BackButton コンポーネントがあります。
<BackButton
@route="adminConfig.flags"
@label="admin.config_areas.flags.back"
/>
6. フィルタリングされた設定構成ページ
管理インターフェースの設定ページの多くは、フィルタリングされたサイト設定の単純なリストです。これにより、管理者は、/admin/config/about/ のようなより専門的な設定ページを作成するまで、完全な「All site settings」リストに圧倒されずに、関連する設定グループを見つけることができます。
実装
これらのルートの1つを追加するには、いくつかのことを行う必要があります。まず、site_settings.yml のトップレベルキー（例：branding:）であるサイト設定の entire category を表示するか、設定 area を使用できます。
サイト設定は複数の area に存在し、同じページに1つ以上表示できます。
adminConfigの下に管理ルートマップにルートを追加します。例えば:
this.route("trustLevels", { path: "/trust-levels" }, function () {
this.route("settings", {
path: "/",
});
});
- 新しいルート .js ファイルを追加します。ファイルは、新しいルートの名前に応じて
frontend/discourse/admin/routes/admin-config/localization.jsのようなパスと一致します。これはAdminConfigWithSettingsRouteから継承し、titleToken()を含める必要があります。
import { i18n } from "discourse-i18n";
import AdminConfigWithSettingsRoute from "../admin-config-with-settings-route";
export default class AdminConfigLocalizationRoute extends AdminConfigWithSettingsRoute {
titleToken() {
return i18n("admin.config.localization.title");
}
}
- コントローラーを追加します。これは主に設定検索とフィルタリングを有効にするためです。
AdminAreaSettingsBaseControllerから継承する必要があります。
import AdminAreaSettingsBaseController from "discourse/admin/controllers/admin-area-settings-base";
export default class AdminConfigLocalizationSettingsController extends AdminAreaSettingsBaseController {}
- 最後に、
.gjs形式のルートテンプレートファイルを、frontend/discourse/admin/templates/admin-config/localization/settings.gjsのようなパスに追加します。これには通常のDPageHeaderとパンくずリストが含まれますが、設定を表示するにはAdminAreaSettingsが必要です。
<div class="admin-config-page__main-area">
<AdminAreaSettings
@showBreadcrumb={{false}}
@area="localization"
@path="/admin/config/localization"
@filter={{@controller.filter}}
@adminSettingsFilterChangedCallback={{@controller.adminSettingsFilterChangedCallback}}
/>
</div>
ここで変更する重要なことは @path と @area（または代わりに @categories を使用）です。前述のように、表示したいサイト設定のエリアまたはカテゴリを入力します。
7. 一般的なガイダンス
-
URLスラッグは、単語内のスペースを示すためにアンダースコア（
_）ではなくハイフン（-）を使用する必要があります。 -
管理インターフェースのすべてのテキストは、ここで概要されているテキストフォーマットガイドラインに従う必要があります。
8. プラグイン
一部のプラグインは、サイト設定のコレクションだけでなく、プラグイン用の詳細な構成UI（例：AI、Automation、Gamification）を必要とします。例えば、Discourse AI は次のようになります。
これを使用しているプラグインの例は次の通りです。
- Discourse AI GitHub - discourse/discourse-ai: Discourse AI now lives in the discourse/discourse repo · GitHub
- Discourse Gamification GitHub - discourse/discourse-gamification · GitHub
- Discourse Chat (core)
デザイン
使用法
- 独立したプラグインUIを作成する際は、一般的な管理UIガイドラインに従う必要があります。
実装
Ember ルーティング
- すべてのルートテンプレートは
admin/assets/javascripts/discourse/templates/admin-plugins/show/の下にあります - すべてのルートjsファイルは
admin/assets/javascripts/discourse/routes/の下にあり、
admin-plugins-show-でプレフィックスされます - 管理ルートマップは
admin-PLUGIN-NAME-plugin-route-map.jsのようなファイルにある必要があります - ルートマップは次のような構造を持つ必要があります。重要な点は、
admin.adminPlugins.showをresourceとして使用することです。
export default {
resource: "admin.adminPlugins.show",
path: "/plugins",
map() {
this.route("discourse-ai-personas", { path: "ai-personas" }, function () {
this.route("new");
this.route("show", { path: "/:id" });
});
},
};
- これのすべてがどのように機能するかは、Discourse AI プラグインで
/admin/plugins/discourse-ai/ai-personasに移動すると確認できます - 「トップレベル」ルートのみがある場合、つまりサブルートを定義しない場合、テンプレートパスは
admin/assets/javascripts/discourse/templates/admin-plugins/show/your-route-name.gjsのようになります。サブルートがある場合、index.gjs、show.gjs、new.gjsテンプレートなどが必要になります。
ナビゲーション
プラグインは、内部サイドバーまたは上部のタブ付きナビゲーションバーでナビゲーションを表示できます。後者が強く推奨され、将来内部サイドバーのサポートは削除される可能性があります。
- プラグインの表示ページで上部バーまたは内部サイドバーに表示されるすべてのリンクは、
イニシャライザー（例：
assets/javascripts/initializers/admin-plugin-configuration-nav.js）で定義する必要があります。
api.addAdminPluginConfigurationNavを使用します。リンクにはlabel、route、description（管理検索に使用）が必要です - このイニシャライザーは、ユーザーが管理者の場合にのみ実行する必要があります。
- プラグインのサイト設定リンクは自動的に生成されるため、ここに含まれる必要はありません。
- 例はここで確認できます discourse-ai/assets/javascripts/initializers/admin-plugin-configuration-nav.js at ab4544d8977ec0e9d6aa42b4551df8317aa9b365 · discourse/discourse-ai · GitHub .
サーバーサイド
add_admin_routeは、カスタム管理ルートを管理サイドバーと上部のタブ付き /plugins インデックスから表示するためにまだ使用されています。基本的に、これはプラグインUIのルートページを定義します。- 新しいプラグイン表示ページが使用されるように、
use_new_show_route: trueを追加引数として渡す必要があります。
- 新しいプラグイン表示ページが使用されるように、
UI 慣習
- プラグインの各インデックスルートは、ルートの意図を説明し、関連するアクションボタンを追加するために
DPageSubheaderコンポーネントを表示する必要があります。 - メインプラグインページヘッダーにレンダリングされる必要があるアクションボタンは、専用コンポーネントを使用して
admin-plugin-config-page-actionsアウトレットを使用する必要があります。これを行う最適な場所は、addAdminPluginConfigurationNavが使用されている同じイニシャライザー内です。pluginとactionsがoutletArgsとして渡されます。pluginは現在のプラグインのモデル表現であり、プラグインの名前などにアクセスできます。actionsはDPageHeaderから yield されたアクションボタンコンポーネントです。
api.renderInOutlet(
"admin-plugin-config-page-actions",
ChatAdminPluginActions
);
関連トピック: