テーマ設定のサポート対象タイプに新しい 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: プロパティの値は文字列として保存されます。integer: プロパティの値は整数として保存されます。float: プロパティの値は浮動小数点数として保存されます。boolean: プロパティの値はtrueまたはfalseです。upload: プロパティの値は添付ファイルのURLです。enum: プロパティの値はchoicesキーワードで定義された値の1つでなければなりません。links: type: objects default: [] schema: name: link properties: name: type: enum choices: - name 1 - name 2 - name 3categories: プロパティの値は有効なカテゴリ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 でどうぞ。
可能性を確認するための試みでしたが、合理的なアプローチではありませんでした。