テーマ設定のサポート対象タイプに新しい type: objects を導入します。これは、近く廃止予定の既存の json_schema タイプを置き換えるために使用できます。
objects タイプのテーマ設定の定義
objects タイプのテーマ設定を作成するには、まず、通常のテーマ設定と同様に、トップレベルのキー（設定名として使用されます）を定義します。
links: ...
次に、type、default、schema のキーワードを設定に追加します。
links:
type: objects
default: []
schema: ...
type: objects は、これが objects タイプの設定であることを示します。default: [] の記述は、設定のデフォルト値を空の配列に設定します。デフォルト値には、オブジェクトの配列を指定することもでき、schema が定義された後にその例を示します。
スキーマを定義するには、まず以下のようにスキーマの name を定義します。
links:
type: objects
default: []
schema:
name: link
次に、スキーマに properties キーワードを追加します。これにより、各オブジェクトがどのように見えるべきかを定義し、検証することができます。
links:
type: objects
default: []
schema:
name: link
properties:
name: ...
上記の例では、link オブジェクトに name プロパティがあると述べています。期待されるデータの種類を定義するために、各プロパティは type キーワードを定義する必要があります。
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
上記のスキーマ定義は、link オブジェクトに string 型の name プロパティがあることを示しており、そのプロパティには文字列値のみが受け入れられることを意味します。現在、以下のタイプがサポートされています:
-
string: プロパティの値は文字列として保存されます。拡張テキストエリアを使用するにはtextarea: trueを設定します:description: type: string textarea: true validations: max_length: 500 -
integer: プロパティの値は整数として保存されます。 -
float: プロパティの値は浮動小数点数として保存されます。 -
boolean: プロパティの値はtrueまたはfalseです。 -
upload: プロパティの値は添付ファイルの URL です。 -
enum: プロパティの値は、choicesキーワードで定義された値のいずれかでなければなりません。links: type: objects default: [] schema: name: link properties: name: type: enum choices: - name 1 - name 2 - name 3 -
categories: プロパティの値は、有効なカテゴリ ID の配列です。 -
groups: プロパティの値は、有効なグループ ID の配列です。 -
tags: プロパティの値は、有効なタグ名の配列です。 -
icon: プロパティの値は、Discourse アイコンセットからの単一のアイコン名です。選択されたアイコンはスプライトシートに自動的に追加されるため、個別に登録せずにレンダリングできます。
スキーマが定義されると、設定のデフォルト値を以下のように yaml で配列を定義することで設定できるようになります:
links:
type: objects
default:
- name: link 1
title: link 1 title
- name: link 2
title: link 2 title
schema:
name: link
properties:
name:
type: string
title:
type: string
必須プロパティ
定義されたすべてのプロパティは、デフォルトでオプションです。プロパティを必須としてマークするには、required: true でプロパティに注釈を付けます。また、required: false でプロパティに注釈を付けて、オプションとしてマークすることもできます。
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
title:
type: string
required: false
空の string、datetime、icon の値や、空の categories、groups、tags のリストは、欠落しているものとして扱われます。必須プロパティはこれらを拒否し、オプションプロパティはそれらの検証をスキップします。false は設定済みとして扱われます。
カスタム検証
特定のプロパティタイプでは、validations キーワードでプロパティに注釈を付けることで宣言できるカスタム検証の組み込みサポートがあります。
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
validations:
min_length: 1
max_length: 2048
url: true
string タイプの検証
min_length: プロパティの最小長。キーワードの値は整数でなければなりません。max_length: プロパティの最大長。キーワードの値は整数でなければなりません。url: プロパティが有効な URL であることを検証します。キーワードの値はtrue/falseで指定できます。
integer および float タイプの検証
min: プロパティの最小値。キーワードの値は整数でなければなりません。max: プロパティの最大値。キーワードの値は整数でなければなりません。
tags、groups、categories タイプの検証
min: プロパティの最小レコード数。キーワードの値は整数でなければなりません。max: プロパティの最大レコード数。キーワードの値は整数でなければなりません。
グループメンバーシップの解決
オブジェクト設定では、type: groups プロパティを現在のユーザーに対するブール値に解決できます。これは、テーマコードが現在のユーザーが設定されたグループのいずれかに属しているかどうかだけを必要とする場合に有用です。なぜなら、currentUser.groups にはユーザーに表示されるグループのみが含まれるからです。
groups プロパティに resolve_group_membership: true を追加します:
menu_sections:
type: objects
default:
- name: section 1
groups:
- 1
- 3
schema:
name: menu section
properties:
name:
type: string
groups:
type: groups
resolve_group_membership: true
管理 UI と保存された設定値は、元の groups 配列のままです。フロントエンドのランタイム settings オブジェクトでは、Discourse は各オブジェクトからグループ ID を削除し、user_in_ を接頭辞に付けた同じプロパティ名のブール値を追加します:
for (const section of settings.menu_sections) {
if (section.user_in_groups) {
// このセクションで選択された少なくとも1つのグループにユーザーが含まれています。
}
}
このオプションは、type: groups を持つオブジェクトスキーマプロパティに対してのみ有効です。また、ネストされたオブジェクトスキーマや、logged_in_users や anonymous_users などの自動グループでも機能します。
ネストされたオブジェクト構造
オブジェクトは、オブジェクトの配列を含むプロパティを持つこともできます。ネストされたオブジェクト構造を作成するには、プロパティに type: objects と関連する schema 定義で注釈を付けることもできます。
sections:
type: objects
default:
- name: section 1
links:
- name: link 1
url: /some/url
- name: link 2
url: /some/other/url
schema:
name: section
properties:
name:
type: string
required: true
links:
type: objects
schema:
name: link
properties:
name:
type: string
url:
type: string
設定の説明とローカライズ
en ロケールで設定の説明を追加するには、以下の objects タイプのテーマ設定が与えられた場合、次の形式で locales/en.yml ファイルを作成します。
sections:
type: objects
default:
- name: section 1
links:
- name: link 1
url: /some/url
- name: link 2
url: /some/other/url
schema:
name: section
properties:
name:
type: string
required: true
links:
type: objects
schema:
name: link
properties:
name:
type: string
url:
type: string
en:
theme_metadata:
settings:
sections:
description: This is a description for the sections theme setting
schema:
properties:
name:
label: Name
description: The description for the property
links:
name:
label: Name
description: The description for the property
url:
label: URL
description: The description for the property
このドキュメントはバージョン管理されています - 変更提案は github でお願いします。
可能性を確認するための試みでしたが、合理的なアプローチではありませんでした。