モジュールとテーマのフィールドの概要

モジュールテーマには、フィールドの概念があります。フィールドはモジュールまたはテーマをカスタマイズするフォームフィールドです。フィールドは、サイトで使用するモジュールやテーマのスタイルおよび機能の制御に使用します。

フィールドの作成と管理

モジュールfields.jsonファイルには、HubSpot CLIを使用してローカル環境で、またはアプリ内のモジュールエディター上でフィールドを追加できます。テーマにフィールドを追加するには、CLIを使用してテーマのfields.jsonファイルをローカル環境で更新する必要があります。 

HubSpot CLI

モジュールフィールドとテーマフィールドをローカル環境で構築する場合、モジュールまたはテーマのフォルダー内にあるfields.jsonファイル経由で編集できます。モジュールの場合、hs create moduleコマンドを使用すると、このファイルが自動作成されます。モジュールエディターで利用可能な全てのフィールドオプションは、fields.jsonファイルで追加または編集できるプロパティーとして使用できます。これには、リピーターフィールド、グループ、条件が含まれます。ローカル編集の利点の1つは、gitのようなバージョン管理システムにモジュールを含めることが容易になることです。

モジュールエディター

デザインマネージャーには組み込みのモジュールエディターUIがあり、モジュールフィールドの作成、グループ化、編集に使用できます。モジュールエディターにはモジュールのプレビューがあるため、モジュールの外観の確認とフィールドのテストができます。モジュールは、常に使用する予定のテンプレートでモジュールをテストして、どのようなテンプレートでのスタイルからの影響があるかを確認する必要があります。なお、ロックされたフォルダーにモジュールが含まれている場合は、この方法で編集できないことに注意してください。

デザインマネージャーのモジュールエディター

注:主にローカル環境で作業し、フィールドの設定にモジュールエディターを使用する場合は、必ず変更をfetch(フェッチ)してください。gitのようなバージョン管理システムを使用する場合には、特に重要です。

フィールドの横配置

既定では、コンテンツエディターではモジュールフィールドは縦方向に配置されます。しかし、モジュールフィールドは横並びに配列することもできます。このためには、fields.jsonファイルのフィールドにdisplay_widthプロパティーを追加し、値をhalf_widthに設定します。 

side-by-side-modules0

display_widthhalf_widthに設定した1つのフィールドは、コンテンツエディターでは半分の幅で表示されます。fields.json内のこのフィールドの上または下にあるフィールドをhalf_widthに設定すると、フィールドが横並びに配置されます。

// Example module fields.json file [ { "name": "number_field", "label": "Number", "required": false, "locked": false, "display": "slider", "min": 1, "max": 10, "step": 1, "type": "number", "prefix": "", "suffix": "", "default": null, "display_width":"half_width" }, { "label": "Description", "name": "description", "type": "text", "required": true, "default": "Add a description", "display_width": "half_width" } ]

フィールドグループ

フィールドが互いに関連している場合、グループ化して表示することが適切な場合が少なくありません。モジュールもテーマも複数のフィールドのグループ化に対応しています。 

ネストされたフィールドグループがないフィールドグループ

ネストされたフィールドグループがないフィールドグループは、グループの上下に区切り線が表示され、グループのラベルがグループの最上部に表示されます。

ネストされたフィールドグループ

フィールドグループはネストできます。別のフィールドグループを含むフィールドグループはボタンとして表示されます。ボタンをクリックすると、グループの内容が表示されます。

フィールドグループは、3階層までネストできます。つまり、モジュールフィールドの深さは4階層まで設定できます。フィールドの関係性と深さが分かるユーザーインターフェイスを簡単に作成できます。

fields.json内のフィールドグループ

フィールド グループ オブジェクトは、他のフィールドグループの子になることができます。構造はフィールド自体と非常に似ていますが、含まれるフィールドとグループの配列、「children」パラメーターという特別なパラメーターがあります。

// Field group example { "type": "group", "name": "typography", "label": "Typography", "expanded": true, "children": [ { "type": "font", "name": "h1_font", "label": "Heading 1", "load_external_fonts": true, "default": { "color": "#000", "font": "Merriweather", "font_set": "GOOGLE", "variant": "700", "size": "48" } } ] } // Field group inside of a field group { "type": "group", "name": "header", "label": "Header", "children": [ { "type": "font", "name": "h1_font", "label": "Heading 1", "load_external_fonts": true, "default": { "color": "#000", "font": "Merriweather", "font_set": "GOOGLE", "variant": "700", "size": "48" } { "type": "group", "name": "navigation", "label": "Navigation", "expanded": false, "children": [ { "name" : "bg_color", "label" : "Background color", "sortable" : false, "required" : false, "locked" : false, "type" : "color", "default" : { "color" : "#ff0000", "opacity" : 100 } } ] } } ] }

既定でのフィールドグループの展開

フィールドグループは、上記のコード例で示されているように、fields.jsonグループプロパティー内でexpandedブール値プロパティーをtrueに設定することで、既定で展開できます。フィールドグループは既定で展開されないため、ネストされたフィールドグループを使用する場合には、親グループにこのプロパティーを使用することはできません。

フィールドグループ内のフィールド値の出力

フィールドグループでは、出力するフィールド値を含むディクショナリー(辞書型)が作成されます。フィールドグループをネストした場合、ネストされたフィールドグループは外側のフィールド グループ ディクショナリー内にディクショナリーとして格納されます。このデータにアクセスするには、状況に応じてルートのテーマまたはモジュール変数からツリー内を走査する必要があります。

<div> {# printing a value from a field group `recipe_summary` is the field group, `title` is the text field. #} {{module.recipe_summary.title}} </div>/* Printing a Font field's color value, when the font field is within a field group. `typography` is the field group, `h1_font` is the field */ h1{ color: {{ theme.typography.h1_font.color }}; }

スタイルフィールド

スタイルフィールドは、モジュールまたはテーマのfields.jsonファイルの特殊なフィールド グループ タイプで、これによって制作担当者がモジュールやテーマのスタイルをページエディターとテーマエディター上で制御できるようになります。モジュールまたはテーマにスタイルフィールドを追加する方法を以下に示します。スタイルフィールドの使用と整理に関するベストプラクティスを参照してください。

モジュールのスタイルフィールド

モジュールに追加したスタイルフィールドは、モジュール編集時のページエディターの[スタイル]タブに表示されます。

style-field-module-editor0

スタイルフィールドをモジュールのfields.jsonファイルに追加する場合は、全てのフィールドを1つのスタイルグループ内に追加します。ただし、次のようにこのグループ内に複数のグループを含めることができます。

// Module style fields [ { "type": "group", "name": "styles", "tab": "STYLE", "children": [{ "name": "img_spacing", "label": "Spacing around image", "required": false, "type": "spacing", "default": { "padding": { "top": { "value": 10, "units": "px" }, "bottom": { "value": 10, "units": "px" }, "left": { "value": 10, "units": "px" }, "right": { "value": 10, "units": "px" } }, "margin": { "top": { "value": 10, "units": "px" }, "bottom": { "value": 10, "units": "px" } } } }] } ]

モジュールのスタイルフィールドとして使用できるフィールドを以下に示します。各フィールドタイプについては、モジュールとフィールドタイプのガイドをご確認ください。

モジュールとテーマのフィールドタイプをご覧ください。

モジュールのfields.jsonファイル内のスタイルフィールドの例については、CMSボイラープレートを参照してください。

テーマのスタイルフィールド

テーマに追加したスタイルフィールドは、テーマエディターの左のサイドバーに表示されます。

style-field-theme-editor0

以下のように、テーマのfields.jsonファイル内にある全てのスタイルフィールドは、テーマエディターの左のサイドバーに追加され、スタイルグループに追加する必要はありません。

// Theme style fields [ { "label": "Global colors", "name": "global_colors", "type": "group", "children": [ { "label": "Primary", "name": "primary", "type": "color", "visibility": { "hidden_subfields": { "opacity": true } }, "default": { "color": "#494A52" } }, { "label": "Secondary", "name": "secondary", "type": "color", "visibility": { "hidden_subfields": { "opacity": true } }, "default": { "color": "#F8FAFC" } } ] }, { "label": "Global fonts", "name": "global_fonts", "type": "group", "children": [ { "label": "Primary", "name": "primary", "type": "font", "visibility": { "hidden_subfields": { "size": true, "styles": true } }, "inherited_value": { "property_value_paths": { "color": "theme.global_colors.primary.color" } }, "default": { "fallback": "sans-serif", "font": "Lato", "font_set": "GOOGLE" } }, { "label": "Secondary", "name": "secondary", "type": "font", "visibility": { "hidden_subfields": { "size": true, "styles": true } }, "inherited_value": { "property_value_paths": { "color": "theme.global_colors.primary.color" } }, "default": { "fallback": "serif", "font": "Merriweather", "font_set": "GOOGLE" } } ] }, { "name": "branding_color", "label": "branding_color", "type": "color", "default": { "color": "#3b7bc0", "opacity": 60 }, "inherited_value": { "property_value_paths": { "color": "brand_settings.primaryColor" } } }, { "name": "secondary_branding_color", "label": "Secondary Branding color", "type": "color", "default": { "color": "#ff6b6b", "opacity": 60 }, "inherited_value": { "property_value_paths": { "color": "brand_settings.colors[2]" } } } ] } ]

モジュールのスタイルフィールドとして使用できるフィールドを以下に示します。各フィールドタイプについては、モジュールとフィールドタイプのガイドをご確認ください。

モジュールとテーマのフィールドタイプをご覧ください。

テーマのfields.jsonファイル内のスタイルフィールドの例については、CMSボイラープレートを参照してください。 

注:マーケットプレイスで提供している場合は、既存のモジュール内の既存のコンテンツフィールドをスタイルフィールドで置き換えないでくださいfields.jsonファイルのフィールド階層を変更すると、既存のモジュールインスタンスのデータが失われることがあります。代わりに、新しいスタイルフィールドの追加、またはフィールドを適切にグループ化した新しいリストの作成ができます。これにより、貴社の更新によって、貴社のテーマを利用している顧客のコンテンツが破損するような変更は避けられます。以前のモジュールの移行パスについては、HubSpotアイデアフォーラム(英語)を参照してください。

生成されるCSS

一部のスタイルフィールドには、フィールドの値に基づいてCSSを直接出力する仕組みがあります。これは、グラデーションなどの複雑なスタイルを制御できるフィールドの場合に特に役立ちます。生成される.cssプロパティーを備えているフィールドタイプは次のとおりです。

  • グラデーション(スタイルフィールドとしてのみ使用可能)
  • 間隔(スタイルフィールドとしてのみ使用可能)
  • 背景画像(スタイルフィールドとしてのみ使用可能)
  • 境界線(スタイルフィールドとしてのみ使用可能)
{% require_css %} <style> {% scope_css %} .team-member { {% if module.styles.gradient.css %} background: {{ module.styles.gradient.css }}; {% endif %} {{ module.styles.bg_img.css }} {{ module.styles.spacing.css }} {{ module.styles.border.css }} } {% end_scope_css %} </style> {% end_require_css %}

リピーター

情報を形成するモジュールを作成する際には、繰り返し使用される情報があります。例えば、レシピモジュールには「材料」のフィールドがあると考えられます。また、ほとんどのレシピの材料は1つにとどまりません。リッチ テキスト フィールドを利用した場合、スタイルの一貫性を確保したり、材料別の機能を追加したりすることはできなくなります。このような状況でリピーターが役に立ちます。HubSpotには2つの形式のリピーターがあります。繰り返しフィールドと繰り返しグループです。

繰り返しフィールド

繰り返しフィールドは通常のフィールドですが、制作担当者がフィールドのインスタンスを追加、削除、再配置できます。前述のレシピモジュールの例では、各材料を繰り返しテキストフィールドにできます。これにより、制作担当者は必要な数の材料を追加できます。開発者の観点からは、ループ処理によって材料のリストを出力できる配列を利用でき、必要な書式と機能を適用できます。 

リピーターフィールド

繰り返しフィールドは非常にシンプルな状況に最適です。一般的には、繰り返しグループが適切なケースが多くあります。

fields.json内の繰り返しフィールド

// Repeating field example { "name" : "ingredient", "label" : "Ingredient", "required" : false, "locked" : false, "occurrence" : { "min" : 1, "max" : null, "sorting_label_field" : null, "default" : 1 }, "allow_new_line" : false, "show_emoji_picker" : true, "type" : "text", "default" : [ "1 cup water" ] }

モジュールのHTML+HubLでの項目のループ

<!--Looping through a repeating field--> <ul> {% for item in module.ingredient %} <li>{{ item }}</li> {% endfor %} </ul>

繰り返しグループ

繰り返しグループは、繰り返しに対応したフィールドグループです。繰り返しグループを使用すると、制作担当者がフィールドのグループを追加、削除、再配置できるようになります。再びレシピモジュールを例に、材料リストをショッピングリスト機能と連携する状況を考えてみます。材料の量は重要です。誰かが量をテキストフィールドに入力した場合に、テキストフィールドを解析して材料から量の情報を取り出すとします。ここで繰り返しグループが役に立ちます。こうしたフィールドの出力に対し、ループ処理を行うことができます。

フィールドの繰り返しグループ

fields.json内の繰り返しグループ

// Repeating field group example { "id" : "ingredients", "name" : "ingredients", "label" : "Ingredients", "required" : false, "locked" : false, "occurrence" : { "min" : 1, "max" : null, "sorting_label_field" : "ingredients.ingredient", "default" : null }, "children" : [ { "id" : "ingredients.ingredient", "name" : "ingredient", "label" : "Ingredient", "required" : false, "locked" : false, "validation_regex" : "", "allow_new_line" : false, "show_emoji_picker" : false, "type" : "text", "default" : "Water" }, { "id" : "ingredients.quantity", "name" : "quantity", "label" : "Quantity", "required" : false, "locked" : false, "display" : "text", "min" : 0, "step" : 1, "type" : "number", "default" : 1 }, { "id" : "ingredients.measurement", "name" : "measurement", "label" : "Measurement", "help_text" : "Unit of measurement (cups, tbsp, etc.)", "required" : false, "locked" : false, "allow_new_line" : false, "show_emoji_picker" : false, "type" : "text", "default" : "cups" } ], "type" : "group", "default" : [ { "ingredient" : "Water", "quantity" : 1, "measurement" : "cups" } ] }

モジュール内の繰り返しフィールドのループ処理

<h2>Ingredients</h2> <ul> {% for ingredient in module.ingredients %} <li> <button data-quantity="{{ ingredient.quantity }}" data-unit="{{ ingredient.measurement }}" data-ingredient="{{ ingredient.ingredient }}"> Add to cart </button> {{ ingredient.quantity }} {{ ingredient.measurement }} {{ ingredient.ingredient }} </li> {% endfor %} </ul>

リピーターオプション

編集時の利便性を向上すると共に、プログラム側で未対応の値が入力できないように、繰り返しフィールドや繰り返しグループには、制作担当者による追加可能項目数の最小値と最大値を設定できます。 

繰り返しグループでは、リピーターを表示するときに、その項目のラベルとして機能するフィールドを設定することもできます。

最大出現数
"occurrence" : { "min" : 1, "max" : 4, "sorting_label_field" : "ingredients.ingredient", }
リピーターオプション
ParameterTypeDescription Default
max
Integer

このグループの最大出現回数。UIからのこの数を超える項目の追加を防止します。

null
min
Integer

このフィールドグループの最小出現数。UIからのこの数を下回る項目数の指定を防止します。

null
sorting_label_field
String

ドラッグ操作可能なカードのUIに表示するテキストを取得できるフィールドのIDです。既定は、グループ内の最初のフィールドです。

継承フィールド

inherited_valueプロパティーは、他のフィールドから既定値を継承するようにフィールドを設定できます。フィールドの既定値全体を別のフィールド値から設定するには、default_value_pathにターゲットフィールドのフィールド名パスを指定します。default_value_pathを設定すると、フィールドに設定されたdefaultは全て無視されます。

他のフィールドの値にアクセスするには、モジュールのHubLコードでのアクセスと同様に、パスの先頭に module.を含める必要があります。

// Inherited fields { "name": "body_font", "type": "font", "default": { "font": "Helvetica", "color": "#C27BA0" } }, { "name": "h1_font", "type": "font", "default": {}, "inherited_value": { "default_value_path": "module.body_font" } }

複雑なフィールド(値がオブジェクトのフィールド)の場合、ユーザーはproperty_value_pathに継承するプロパティーを細かく指定できます。inherited_valueで参照されるパスにも、複雑なフィールドのフィールド値からのキーを含めることができます。例えば、色フィールドには、色自体と不透明度を含むオブジェクト値があります。そのため、不透明度なしで色自体の値を取得するには、パスの末尾に.colorを指定します。例えばフォントフィールドは、個別の色フィールドから色だけを継承できます。

// Inherited fields with objects { "name": "secondary_color", "type": "color", "default": { "color": "#C27BA0", "opacity": 100 } }, { "name": "h1_font", "type": "font", "default": { "font": "Helvetica", "size": 12, "size_unit": "px" }, "inherited_value": { "property_value_paths": { "color": "module.secondary_color.color" } } }

default_value_pathproperty_value_pathsの効果を組み合わせて、あるフィールドから既定値を継承しながら、別のフィールドから特定のプロパティー値を継承することもできます。

// combining the effects of default_value_path and property_value_paths { "name": "body_font", "type": "font", "default": { "font": "Helvetica", "color": "#000000" } }, { "name": "secondary_color", "type": "color", "default": { "color": "#C27BA0", "opacity": 100 } }, { "name": "h1_font", "type": "font", "default": {}, "inherited_value": { "default_value_path": "module.body_font", "property_value_paths": { "color": "module.secondary_color.color" } } }

別のフィールドから継承したフィールドが、ページまたはテーマ設定によって直接変更される場合、制御元のフィールドとの接続は失われます。このフィールドの値に、default_value_pathまたはproperty_value_pathsによって関連付けられた他のフィールドから影響を与えることはできなくなります。

フィールドタイプ

情報の参照のしやすさを考慮し、フィールドタイプの情報は、全般的なフィールドの情報と分けました。モジュールとテーマフィールドのリファレンスページにあります。


参考になりましたか?
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。