テーマをダウンロードすると、エクスポートされたファイルには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",
...
}
翻訳は、「設定」パネルでラベルと説明を指定するために使用されます。
ラベルと説明のための文字列を指定するには
-
翻訳フォルダで、ヘルプセンターのデフォルト言語用のJSONファイルを探します。例：en-us.json
-
既存のプロパティの値を更新するか、新しいプロパティを追加します。以下に例を示します。
{ "text_color_label": "Text color", "text_color_description": "Text color for body and heading elements", ... } -
変数では、翻訳プロパティ名を
"label"または"description"属性の値として使用します。"variables": [ { "identifier": "color_text", "type": "color", "label": "text_color_label", "description": "text_color_description", "value": "#0072EF" }, ... ]「変数オブジェクト」を参照。プロパティを作成したり、プロパティ名を変更したりする場合は、変数を必ず更新してください。
設定パネルでラベルと説明をローカライズすることができます。ローカライズされた文字列は自分で用意する必要があります。
ラベルと説明をローカライズするには
-
翻訳フォルダで、サポートする追加の言語用のJSONファイルを探します。
-
デフォルトの翻訳ファイルで定義されているプロパティ名をコピーします。以下に例を示します。
{ "text_color_description": "", "text_color_label": "", ... } -
各プロパティに、ローカライズされた文字列を指定します。次に例を示します。
fr.json
{ "text_color_description": "Couleur du texte pour les éléments du titre et du corps", "text_color_label": "Couleur du texte", ... }