新たに 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
カスタム検証
特定のプロパティ型では、validations キーワードでプロパティに注釈を付けることで宣言できる、組み込みのカスタム検証のサポートがあります。
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
validations:
min: 1
max: 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で行ってください。
可能性を確認するための試みでしたが、合理的なアプローチではありませんでした。