テーマをダウンロードすると、エクスポートされたファイルにはmanifest.jsonという名前のファイルが含まれます。このファイルが、Guideのテーマの設定パネルを定義します。

このマニュアルでは、マニフェストファイルとは何か、このファイルを使用して何ができるかについて説明します。また、仕様のリファレンスも提供します。たとえば、テーマをエクスポートし、テキストエディタでmanifest.jsonファイルを開きます。

次のトピックについて説明します。

• manifest.jsonファイルの概要
• manifest.jsonの設定を変数として使用する
• manifest.jsonファイルを変更する
• マニフェストオブジェクト
• 設定オブジェクト
• 変数オブジェクト
• typeプロパティ
• file型
• list型
• range型
• 翻訳

manifest.jsonファイルの概要

テーマをエクスポートすると、エクスポートされたファイルにはmanifest.jsonという名前のファイルが含まれます。このマニフェストファイルを使用して、Guideのテーマの設定パネルを定義できます。

パネル内で既存の設定を変更することも、新しい設定を作成することもできます。次の例では、マニフェストファイルは、"＃30aabc"のデフォルト値をcolor_brand_text設定に割り当てます。

"settings": [
  {
    "label": "Colors",
    "variables": [
      {
        "identifier": "color_brand_text",
        "type": "color",
        "description": "color_brand_text_description",
        "label": "color_brand_text_label",
        "value": "#30aabc"
      },
      ...
    ]
  },
  ...
]

Guideへテーマをインポートした後、設定パネルの「ブランドのテキストの色」にマニフェストファイルの"label"プロパティで指定されたcolor_brand_text設定が表示されます。デフォルトで、"value"プロパティによって指定されるカラーピッカーの16進数値は#30aabcです。

manifest.jsonの設定を変数として使用する

テーマのファイルでは、設定の識別子を変数として使用できるため、設定は「変数」とも呼ばれます。設定パネルで値を変更すると、変数を使用するすべてのファイルの値が更新されます。

変数は、$identifier構文を使用してテーマのstyle.cssファイルに変数を挿入するか、Curlybarsでsettings.identifierヘルパーを使用してページテンプレートに挿入することができます。次に例を示します。

style.css

input:focus {
  border: 1px solid $color_brand_text;
}

次のように、1組の中括弧を使用してヘルパーをCSS式に埋め込むこともできます。

max-width: #{$search_width}px;

ページテンプレート

<div style="background-color:{{settings.color_brand_text}}">

manifest.jsonファイルを変更する

manifest.jsonファイルは、ヘルプセンターの「コードを編集」ページにあるファイルのリストには含まれていません。manifest.jsonファイルを編集するには、テーマをファイルにエクスポートし、システムのマニフェストファイルを変更してから、Guideでテーマをインポートする必要があります。

テーマをエクスポートするには

• 詳しくは「ヘルプセンターのテーマをダウンロードする」を参照してください。

変更したテーマをインポートするには

• 詳しくは「ヘルプセンターのテーマをインポートする」を参照してください。

マニフェストオブジェクト

マニフェストのドキュメントルートオブジェクトには、次のプロパティがあります。

名前	タイプ	コメント
name	文字列	テーマ名
author	文字列	テーマを作成した人、チーム、または組織
version	文字列	Semantic Versioning 2.0.0標準に従ったテーマのバージョン
api_version	文字列	テンプレートAPI
settings	配列	設定オブジェクトのリスト。詳しくは「設定オブジェクト」を参照。

例

{
  "name": "My second theme",
  "author": "Jane Doe",
  "version": "1.0.1",
  "api_version": 3,
  "settings": [
    ...
  ]
}

設定オブジェクト

マニフェストファイルとGuideの設定パネルの両方で、この設定は、色やフォントなどのグループ別に分かれています。各設定グループは、マニフェストファイル内で設定オブジェクトによって定義されます。各オブジェクトは、1つのラベルと、ブランドカラーやテキストカラーなどの1つ以上の設定で構成されています。

既定オブジェクトを編集することも、独自のオブジェクトを作成することもできます。Guideでテーマを読み込むと、オブジェクトがテーマの設定パネルに反映されます。

各設定オブジェクトに、次のプロパティがあります。

名前	タイプ	コメント
label	文字列	翻訳プロパティ名。「翻訳」を参照。設定グループのタイトルを表示します。
variables	配列	グループ内の設定のリスト。変数とも呼ばれます。「変数オブジェクト」を参照。マニフェストファイルは、最大200個の変数オブジェクトを持つことができます。 詳しくは「ヘルプセンターに関するGuide製品の制限事項」の「manifest.json内の設定の総数」を参照してください。

例

"settings": [
  {
    "label": "colors_group_label",
    "variables": [{...}, ...]
  },
  {
    "label": "fonts_group_label",
    "variables": [{...}, ...]
  },
  {
    "label": "brand_group_label",
    "variables": [{...}, ...]
  },
  {
    "label": "banners_group_label",
    "variables": [{...}, ...]
  }
]

この例では、設定パネルに次のカテゴリを作成します。

変数オブジェクト

各設定オブジェクトには、実際の設定をリストするvariables配列があります。この配列を「variables」と呼ぶのは、変数としてヘルプセンターテンプレートやCSSに挿入できるからです。詳しくは「ヘルプセンターに関するGuide製品の制限事項」の「manifest.json内の設定の総数」を参照してください。

任意の変数を定義することができます。ただし、マニフェストファイルには、"logo"と"favicon"の2つ識別子を持つファイル変数が必要です。「必須変数」を参照。

各変数には、次のプロパティがあります。

名前	タイプ	コメント
identifier	文字列	CSSまたはCurlybars式で使用できる変数名。30文字以内で、英数字とアンダースコア（_）のみを含むこと。
type	文字列	ユーザーの値を取得するGuideの設定パネルのUIコントロール。text、list、checkbox、color、file、rangeのいずれか。「typeプロパティ」を参照。
label	文字列	設定パネルのUIコントロールの横に表示される設定の名前。40文字以内で指定します。 この値を翻訳するには、翻訳プロパティ名を使用します。詳しくは「翻訳」を参照。翻訳には文字数の制限はありません。
description	文字列	設定パネルのUIコントロールの横に表示される設定の短い説明。80文字以内で指定します。 この値を翻訳するには、翻訳プロパティ名を使用します。詳しくは「翻訳」を参照。翻訳には文字数の制限はありません。
value	文字列	デフォルト値の設定
options	配列	list型のみ。リストアイテムの配列。「optionオブジェクト」を参照。
min	整数	range型のみ。範囲の最小値。
max	整数	range型のみ。範囲の最大値。

例

"variables": [
  {
    "identifier": "color_brand",
    "type": "color",
    "label": "color_brand_label",
    "description": "color_brand_description",
    "value": "#0072EF"
  },
  ...
]

この例では、設定パネルに次のラベルとコントロールを作成します。

必須変数

マニフェストファイルに次の2つの変数を指定する必要があります。指定しない場合、インポート時にファイルが拒否されます。

• logo - identifierは "logo"、typeは "file" でなければなりません
• favicon - identifierは "favicon"、typeは "file" でなければなりません

例

"variables": [
  {
    "identifier": "logo",
    "type": "file",
    "description": "logo_description",
    "label": "logo_label"
  },
  {
    "identifier": "favicon",
    "type": "file",
    "description": "favicon_description",
    "label": "favicon_label"
  }
]

typeプロパティ

各variableオブジェクトには、typeプロパティがあります。このプロパティは、Guideの設定パネルで、設定値を設定するUIコントロールを指定します。次のいずれかの値をとります。

• text - テキスト入力フィールド。各テキストフィールドの文字数制限は最大1,000文字です。
• list - ドロップダウンリスト。リスト項目のoptionオブジェクトのリストを含みます。「list型」を参照。
• checkbox - チェックボックス。「checkbox型」を参照。
• color - カラーピッカー
• file - ファイルアップローダー。「file型」を参照。
• range - 範囲の入力フィールド。「range型」を参照。

例

{
  "identifier": "color_headings",
  "type": "color",
  ...
}

list型

変数オブジェクトの型が"list"の場合、オブジェクトにはドロップダウンリストの項目となるoptions配列が含まれます。リストの各オプションには、次のプロパティがあります。

名前	タイプ	コメント
label	文字列	リスト項目に表示されるわかりやすいテキスト。 40文以内で指定します。 この値を翻訳するには、翻訳プロパティ名を使用します。詳しくは「翻訳」を参照。翻訳には文字数の制限はありません。
value	文字列	リスト項目を構成する値

配列には複数のオプションを指定する必要があります。複数指定しない場合、テーマをインポートできません。オプションの数は20を超えてはなりません。ヘルプセンターのGuide製品の制限で、「リストタイプ設定におけるオプションの総数」の項を参照してください。

例

{
  "identifier": "font_headings",
  "type": "list",
  "label": "Heading",
  "description": "Font for headings",
  "value": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
  "options": [
    {
      "label": "Arial",
      "value": "Arial, 'Helvetica Neue', Helvetica, sans-serif"
    },
    {
      "label": "Copperplate Light",
      "value": "'Copperplate Light', 'Copperplate Gothic Light', serif"
    },
    {
      "label": "Baskerville",
      "value": "Baskerville, 'Times New Roman', Times, serif"
    }
  ]
}

checkbox型

変数オブジェクトの型が"checkbox"の場合は、オブジェクトのvalueプロパティを使用して、ユーザーがチェックボックスを選択したときに設定される値を指定します。必ずブール値を指定します。

名前	タイプ	コメント
value	ブール値	trueまたはfalse

例

{
  "identifier": "scoped_hc_search",
  "type": "checkbox",
  "description": "scoped_help_center_search_description",
  "label": "scoped_help_center_search_label",
  "value": true
}

file型

"file"型のvariableオブジェクトは、設定パネルでファイルアップローダーコントロールを追加します。この型の変数には、valueプロパティはありません。以下に例を示します。

{
  "identifier": "community_image",
  "type": "file",
  "description": "community_image_description",
  "label": "community_image_label"
}

値は、システムによって決定されるファイルURLです。

テーマのデフォルトファイルを用意する必要があります。このファイルが、ユーザーが別のファイルをアップロードするまで使用されます。デフォルトファイルの名前は、変数の識別子と一致する必要があります。テーマファイルのsettingsフォルダにファイルを置きます。以下に例を示します。

テーマファイル内のURLを指定する場所にファイル変数を使用します。次に例を示します。

style.css

.community_banner {
    background-image: url($community_image);
}

ページテンプレート

<img src="{{settings.community_image}}">

range型

"range"型のvariableオブジェクトは、設定パネルでスライダーコントロールを追加します。以下に例を示します。

range変数には、minプロパティとmaxプロパティが含まれており、スライダーを動かす範囲の値を指定します。必ず整数を指定します。

例

{
  "identifier": "font_size",
  "type": "range",
  "description": "font_size_description",
  "label": "font_size_label",
  "min": 70,
  "max": 150,
  "value": 100
}

翻訳

設定パネルの表示可能な文字列は、すべて翻訳で定義されています。翻訳は、プロパティ名と値で構成されます。以下に例を示します。

"text_color_label": "Text color"

プロパティ名は任意です。どのような名前でも指定できます。

翻訳は、テーマのrootフォルダ内のtranslationsフォルダにある言語固有のJSONファイルに格納されます。

/ translations
   - en-us.json
   - es.json
   - fr.json
   - ...

各ファイルは、翻訳のリストを含むJSONオブジェクトで構成されています。

en-us.json

{
  "brand_color_description": "Brand color for major navigational elements",
  "brand_color_label": "Brand color",
  ...
}

翻訳は、「設定」パネルでラベルと説明を指定するために使用されます。

ラベルと説明のための文字列を指定するには

1. 翻訳フォルダで、ヘルプセンターのデフォルト言語用のJSONファイルを探します。例：en-us.json

2. 既存のプロパティの値を更新するか、新しいプロパティを追加します。以下に例を示します。

   {
     "text_color_label": "Text color",
     "text_color_description": "Text color for body and heading elements",
     ...
   }
   

3. 変数では、翻訳プロパティ名を"label"または"description"属性の値として使用します。

   "variables": [
     {
       "identifier": "color_text",
       "type": "color",
       "label": "text_color_label",
       "description": "text_color_description",
       "value": "#0072EF"
     },
     ...
   ]
   

   「変数オブジェクト」を参照。プロパティを作成したり、プロパティ名を変更したりする場合は、変数を必ず更新してください。

設定パネルでラベルと説明をローカライズすることができます。ローカライズされた文字列は自分で用意する必要があります。

ラベルと説明をローカライズするには

1. 翻訳フォルダで、サポートする追加の言語用のJSONファイルを探します。

2. デフォルトの翻訳ファイルで定義されているプロパティ名をコピーします。以下に例を示します。

   {
     "text_color_description": "",
     "text_color_label": "",
     ...
   }
   

3. 各プロパティに、ローカライズされた文字列を指定します。次に例を示します。

   fr.json

   {
     "text_color_description": "Couleur du texte pour les éléments du titre et du corps",
     "text_color_label": "Couleur du texte",
     ...
   }