テーマ設定用オブジェクトタイプ

テーマ設定のサポート対象タイプに、新しい 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アイコンセットからの単一のアイコン名です。選択したアイコンはスプライトシートに自動的に追加されるため、個別に登録しなくてもレンダリングできます。

APIを通じて objects テーマ設定を更新する場合、tags 配列にはソースタグ名、整数のタグID、またはその両方を含めることができます。IDは検証と保存の前にソース名に解決されます。テーマには引き続きソース名の配列が届きます。数値文字列はIDではなく名前として扱われ、デフォルトでは名前を使用する必要があります。

フロントエンドのデフォルトのタグレンダラーには、IDを持つタグオブジェクト、または tagId オプションとともにレンダリングされるタグ名に対して data-tag-id が含まれます。既存の data-tag-name 属性は変更されません。表示名が変更されても、IDはロケール間で同じままです。IDなしの名前のみのレンダリング呼び出しでは、data-tag-id は省略されます。

直接的な tags プロパティを持つオブジェクトは、フロントエンドの設定で自動的に tag_objects 配列を受け取ります。

{
  tags: ["support"],
  tag_objects: [
    { id: 42, name: "support" }
  ]
}

既存のタグ名配列は変更されません。各コンパニオンオブジェクトには、タグIDと、大文字と小文字の区別を含む、設定からの元のソース名文字列が正確に含まれます。翻訳された表示名に置き換わることはありません。コンポーネントは、IDを使用して選択したタグを参照できます。例えば、CSSで data-tag-id をターゲットする場合などです。コアはこのコンパニオン配列をUIとしてレンダリングせず、これ用の管理設定を追加しません。

コンパニオンは、オブジェクトの直接的な tags の選択を元の順序で結合し、繰り返しの選択を保持します。ネストされたオブジェクトには独自のコンパニオンが付与されます。訪問者に表示されるタグのみが含まれます。見つからない、削除された、または非表示の選択は省略されます。タグが解決されない場合でも、コンパニオンは [] として存在します。そのインデックスが元の文字列配列と一致すると仮定しないでください。

オプトインや追加のブラウザAPIリクエストは不要です。作成者定義のスキーマプロパティ名が tag_objects の場合、そちらが優先されます。コアはそのフィールドを保持し、そのレベルではコンパニオンを生成しません。この名前の既存のカスタムフィールドを宣言してください。宣言されていない tag_objects 値は生成されたメタデータとして扱われ、削除されます。直接的な tags プロパティを持たないオブジェクトや、レガシーなトップレベルのタグリスト設定は変更されません。

コンパニオンは、フロントエンドのページデータに対してのみ生成されます。保存された設定と管理編集値は、既存の形状を維持します。設定APIを通じて送信された生成されたメタデータは破棄されます。コンテキストをサポートするコンポーネントや、このデータのない古いDiscourseバージョンでは、Array.isArray(style.tag_objects) をチェックし、利用できない場合は既存の名前ベースの動作にフォールバックできます。

スキーマが定義されると、以下のように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 ロケールで設定の説明を追加するには、以下のフォーマットでファイル 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: これは sections テーマ設定の説明です
        schema:
          properties:
            name:
              label: 名前
              description: プロパティの説明
            links:
              name:
                label: 名前
                description: プロパティの説明
              url:
                label: URL
                description: プロパティの説明

翻訳可能なオブジェクトテキスト

translation_key という名前の必須の文字列プロパティを宣言し、テキストプロパティに translatable: true をマークして、それらを サイトテキスト で公開します。コアは保存されたオブジェクト設定からデフォルトを読み取り、通常のテーマ翻訳アセットにそれらを含めます。テーマコンポーネントにはバックエンドコードは不要です。

links:
  type: objects
  default:
    - translation_key: guidelines
      label: Community guidelines
  schema:
    name: link
    identifier: label
    properties:
      translation_key:
        type: string
        required: true
      label:
        type: string
        translatable: true

これにより、js.theme_translations.<theme_id>.links.guidelines.label がデフォルトテキスト「Community guidelines」およびデフォルトテキスト言語 en とともに公開されます。フロントエンドは引き続き、設定内の各リンクに対して i18n(themePrefix(`links.${link.translation_key}.label`), { defaultValue: link.label }) を使用します。
エディタは、themePrefix に渡すための相対キーと、コンポーネントにフィルタされたサイトテキストへのリンクをプレビューします。翻訳を管理する前に変更を保存してください。

コアは、インストール済みテーマIDとオブジェクト設定名にキーをスコープします。デフォルトのテキスト言語は en です。変更するには、ルートスキーマに translations: { default_locale: fr } を任意で設定します。それ以外に translations ブロックは必要ありません。ネストされたスキーマは、それぞれ独自の必須文字列 translation_key プロパティを宣言し、翻訳可能なプロパティをマークします。祖先オブジェクトキーとコレクションプロパティ名は、各ネストされたキーに含まれます。例えば、キー getting_started を持つセクションにキー guidelines を持つリンクが含まれている場合、resource_sections 設定に対して theme_translations.<theme_id>.resource_sections.getting_started.links.guidelines.label が生成されます。

翻訳可能なフィールドを持つスキーマ(その祖先オブジェクトスキーマを含む)は、type: string と required: true で translation_key を宣言する必要があります。スキーマ検証は、デフォルトのオブジェクトリストが空の場合でもこれを確認します。別個の schema.identifier: label オプションは、エディタの表示ラベルを選択しますが、翻訳識別子を選択するものではありません。

小文字で始まり、小文字、数字、アンダースコアのみを含む、安定した手動で割り当てられた識別子を使用します。識別子は最大80文字で、各コレクション内で一意である必要があります。翻訳可能な設定名、フィールド名、およびネストされたコレクション名も、小文字で始まり、小文字、数字、アンダースコアのみを含みます。並べ替えは翻訳を保持します。識別子を変更すると、新しい翻訳キーが作成されます。オブジェクトを複製するには、別のキーが必要です。個別のコンポーネントインストールは、独立した名前空間を持ちます。

既存のコンポーネントに翻訳可能なフィールドを追加する際は、カスタマイズされたオブジェクトに有効な translation_key 値を追加する設定マイグレーションを提供してください。コンポーネントのアップデートは、最終的なオブジェクト翻訳キーを検証し、設定マイグレーションが完了した後に翻訳を再構築します。無効な最終キーはアップデートをロールバックします。通常のオブジェクトエディタの保存はすぐに検証されます。保存されたオブジェクト識別子が無効な場合、読み取りパスはオブジェクトのデフォルトを省略するため、ロケールファイルの翻訳とアセットは利用可能のままです。オブジェクト設定の保存とマイグレーションの適用は、引き続き厳密に検証されます。

translatable: true でマークされた文字列フィールドのみが参加します。マークされていないフィールドと translatable: false のフィールドは除外されます。空のオプションフィールドは、そのキーと既存の翻訳を保持します。デフォルトテキストをクリアしても翻訳は削除されません。ネストされたコレクションは、キーにそのプロパティ名を含めるため、個別のコレクションで同じオブジェクト識別子を再利用できます。

デフォルトには、テーマのデフォルトとインポートされた設定が含まれます。デフォルトテキストを変更すると、翻訳が古いとマークされます。デフォルトはオブジェクト設定に残ります。翻訳は、ロケールファイルフィールドと同様に、既存の ThemeTranslationOverride モデルを使用します。別個のテキストレジストリはありません。

オブジェクト、翻訳可能なフィールド宣言、またはロケールファイルキーを削除しても、その保存された翻訳オーバーライドは削除されません。現在のソースを持たないオーバーライドには deprecated ステータスがあり、設定の保存、マイグレーション、およびコンポーネントのアップデートを通じて保持されます。同じ翻訳キーを復元すると、コンポーネントのロールバック後も、保存されたカスタマイズが再利用されます。これにより、オブジェクト翻訳にオプトインしないコンポーネントの既存のロケールファイル翻訳動作が保持されます。削除されたキーは、そのソース宣言が戻るまでサイトテキストにリストされません。
スキーマ変更により、保持されたキーが現在のキーのネスト構造と競合する場合、現在の宣言がランタイム形状を決定します。両方の保存されたオーバーライドは、スキーマがロールバックされた場合に復元のために利用可能のままです。

翻訳を明示的に元に戻すと、そのオーバーライドが削除され、選択されたロケールの出荷時デフォルトが復元されます。コンポーネントを削除すると、そのすべての翻訳オーバーライドが削除されます。

サイトテキストは、編集可能な翻訳と一緒にデフォルトテキストとその言語を表示します。オブジェクトエディタフィールドとロケールファイルに出荷された文字列の両方が、サイトテキストで js.theme_translations.<theme_id>.<key> を使用します。デフォルト追跡が利用可能になる前に保存された翻訳には、不明なベースラインがあり、古いフィルターから除外されます。現在のデフォルトを確認すると、翻訳を変更せずにベースラインが確立されます。オブジェクトフィールドの補間プレースホルダーは、宣言されたソーステキストに対してチェックされ、カスタムソースオーバーライドに対してはチェックされません。複数形は、兄弟の other フォームで宣言されたプレースホルダーを使用できます。ロケールファイルのオーバーライドは、コンポーネントが出荷テキストで使用していないランタイム引数を供給できる可能性があるため、既存の無制限のプレースホルダー動作を保持します。サイトテキストはこれらの引数を無効としてマークしません。

デフォルト追跡は、保存されたオブジェクトフィールドまたは出荷された英語テキストを使用し、英語キーが存在しない場合は選択されたロケールの出荷テキストにフォールバックします。ソースロケールのオーバーライドはこのベースラインを置き換えません。デフォルトの言語が明示的に表示され、ロケールファイルのオーバーライドを元に戻すと、選択されたロケールに出荷されたテキストが復元されます。

設定名は、テーマ内で名前空間を予約します。ロケールファイルはその設定のルートキーをさらに定義することはできません。オブジェクト設定の保存またはテーマの更新は、その競合を拒否します。テキストは、アクティブなテーマとそのコンポーネント(プレビューを含む)に対してのみ、既存のキャッシュされたテーマ翻訳アセットを通じて配信されます。


このドキュメントはバージョン管理されています - 変更は github で提案してください。

「いいね!」 16

jsonスキーマ形式の廃止が良い考えであるとは、まだ納得できません。

これらは非常に複雑になり、最も「開発者に優しい」形式ではない(そのため、この点では素晴らしい変更です)一方で、jsonスキーマを検証するためのオンラインツールがあり、スキーマとデフォルトデータの両方を検証するのに非常に役立ちます。

例:https://www.jsonschemavalidator.net/

この新しい世界では、それはどのように機能するのでしょうか?

「いいね!」 2

テーマをアップロードする際に、デフォルトデータを定義されたスキーマに対して検証します。とはいえ、現時点ではスキーマ定義自体が有効であるかの検証は行っていませんが、それを行うことは難しくありません。現在のJSONスキーマ設定についても、デフォルトデータを定義されたスキーマに対して検証しているわけではないと思います。

現在のJSONスキーマ型設定の実装は、管理インターフェースのエディタなど、多くの点で不完全です。内部で議論した結果、JSONスキーマが持つすべての可能性を許可するよりも、私たち自身が定義した限定的なスキーマ形式を維持する方が、はるかに管理しやすいという結論に至りました。

「いいね!」 2

クールな機能がいくつかあります。

  • JSON.parse を削除して、設定に直接アクセスしてオブジェクトを取得できるのは非常に便利です。

  • URLバリデーター!

:chefs_kiss: :chefs_kiss:

「いいね!」 5

エディタで複数行を尊重する方法はありますか?

このデフォルトは機能します。

- name: markdown
  value: >
    ## Heading
      * first bullet
      * second bullet

しかし、これを編集すると、キャリッジリターンが失われます。

さらに、「text」タイプがあれば、より長文のデータを格納でき、おそらくより大きな「textarea」エディタを公開できると良いでしょう。

「いいね!」 5

フィードバックをいくつかご紹介します。

「いいね!」 2

これに気づき、修正されました

「いいね!」 1

インターフェースでアイテムを並べ替えることはできますか?

例えば、これはeasy footer theme componentのオブジェクト設定エディタです。現時点では何も並べ替えることができません。

「いいね!」 4

私もこの機能をお願いしたかったです!:+1:


ちなみに、最初の投稿に identifier プロパティに関する情報が含まれていると役立ちます。

上記の Nolo の画像を見るまで、デフォルトの子ラベルをプロパティ値に置き換えることは不可能だと思っていました。コードを見た後、identifier プロパティを見つけました。

「いいね!」 4

並べ替えは、確かに内部でも提起されていることです。今週中に実装できるよう試みます。

承知しました。最初の投稿を identifier プロパティについて更新します。

「いいね!」 5

はい、(まもなく廃止される?)JSONシステムを置き換えるには、古いインターフェイスと同等かそれ以上である必要があります。

順序付けも含まれます。

「いいね!」 1

他にサポートするフィールドタイプはありますか?

例えば:

  • Markdown形式のlong_string。ツールバーをカスタマイズできるかもしれません。
  • dateフィールド(検証ルール付き)。
  • colorフィールド(検証ルール付き)?
「いいね!」 1

現在のところ予定はありませんが、有用であることには同意します。私自身もiconフィールドが欲しいです。

「いいね!」 8

私の経験では、これは保存されたプリセットのように機能するようです。この例では、最初の2つのエントリはこれらのプリセットから恩恵を受けることができますが、それ以降はすべて新しいエントリが最初は空白で表示されます。

これは、フィールドごとにデフォルト値を設定できないことも意味します。たとえば、チェックボックスを開始時にチェックされた状態にしたい場合、それはできません。

links:
  type: objects
  default:
    - name: link 1
      title: link 1 title
    - name: link 2
      title: link 2 title
  schema:
    name: link
    properties:
      is_active:
        type: boolean
        default: true

default: true は、期待どおりには機能しません。

作成された各エントリのフィールドごとにデフォルト値を設定する方法はありますか?

Sassでオブジェクトプロパティを変数にインポートする方法はありますか?

文字列を解析することはいつでも可能ですが、そのように宣伝するのはあまり良い考えではないように思えますね。:sweat_smile:

「いいね!」 1

例を共有していただきありがとうございます!確かに…あまり魅力的には見えませんね :upside_down_face:

「いいね!」 1

ちなみに、あまり時間をかけずに調べてみたのですが、この件はどこまで進んでいますか?

「いいね!」 2

はい、あまり良くないですね。やめましょう。:smile: 可能性を確認するための試みでしたが、合理的なアプローチではありませんでした。
私も同感です。直接的な方法があるといいですね!:+1:

私も知りたいです!
また、もし私が正しければ、それはjson_schemaとの機能パリティにおける唯一の不足機能になるでしょう。

「いいね!」 2

アップロードタイプが利用可能であると思って探していましたが、利用できませんでした。
コアをざっと見たところ、トピック、投稿、アップロードタイプはサーバーサイドで実装されているものの、フロントエンドでは実装されていないことがわかりました。何か特別な理由があるのでしょうか? :thinking: