最終更新日: 2025年8月28日
モジュールテーマ内では、フィールドを使用して、制作担当者がモジュールとテーマのスタイルや機能をウェブサイト上で制御できます。モジュールまたはテーマを開発する場合は、fields.jsonファイルにフィールドを組み込み、テーマエディターとコンテンツエディターに変換します。
テーマ設定モジュール
この記事では、モジュールとテーマのフィールドのオプションを、作成および管理する方法を詳しく説明します。特定のフィールドタイプの詳細については、モジュールとテーマのフィールドに関するリファレンスガイドをご覧ください。

フィールドの作成と管理

モジュール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に設定して、モジュールフィールドを横並びに配列することもできます。
横並びのモジュール
display_widthhalf_widthに設定した単一フィールドは、コンテンツエディターでは半分の幅で表示されます。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"
  }
]

フィールドグループ

フィールドが互いに関連している場合、視覚的にグループ化することが適切な場合が少なくありません。これは、モジュールとテーマの両方でサポートされているフィールドグループを作成すれば実現できます。ローカルでフィールドグループを作成するには、fields.json"group"というtypeのオブジェクトを作成します。次に、グループ化したいフィールドを格納するchildren配列を含めます。
シンプルなフィールドグループのサンプル
[
  {
    "id": "9c00985f-01db-ac5d-73f5-80ed6c0c7863",
    "name": "my_text",
    "display_width": null,
    "label": "Text",
    "required": true,
    "locked": false,
    "validation_regex": "",
    "allow_new_line": false,
    "show_emoji_picker": false,
    "type": "text",
    "default": "Add text here"
  },
  {
    "type": "group",
    "name": "recipe_summary_group",
    "label": "Recipe summary",
    "expanded": true,
    "inline_help_text": "Summarize the recipe (title and description)",
    "children": [
      {
        "type": "text",
        "label": "Recipe title",
        "name": "recipe_title",
        "placeholder": "Burrata salad"
      },
      {
        "type": "text",
        "label": "Recipe description",
        "name": "recipe_description",
        "placeholder": "fig mostarda, hazelnuts, arugula, vincotto, prosciutto, toasted sourdough"
      }
    ]
  }
]
最初のchildrenパラメーター内に別の"group"タイプのオブジェクトを追加することで、グループ内にさらにフィールドグループを作成できます。それから、上記と同じ方法でフィールドグループを構築し、childrenを使ってフィールドを格納します。フィールドグループは3レベルでネストできます。
2次グループを含むフィールドグループ
[
  {
    "type": "group",
    "name": "recipe_summary_group",
    "label": "Recipe summary",
    "inline_help_text": "Summarize the recipe (title and description)",
    "display": "inline",
    "children": [
      {
        "type": "text",
        "label": "Recipe title",
        "name": "recipe_title",
        "placeholder": "Burrata salad"
      },
      {
        "type": "text",
        "label": "Recipe description",
        "name": "recipe_description",
        "placeholder": "fig mostarda, hazelnuts, arugula, vincotto, prosciutto, toasted sourdough"
      },
      {
        "type": "group",
        "name": "secondary_group",
        "label": "Secondary group",
        "expanded": false,
        "children": [
          {
            "name": "bg_color",
            "label": "Background color",
            "sortable": false,
            "required": false,
            "locked": false,
            "type": "color",
            "default": {
              "color": "#ff0000",
              "opacity": 100
            }
          }
        ]
      }
    ]
  }
]

フィールドグループの表示オプション

次のフィールドグループの表示動作をカスタマイズできます。
  • 展開: デフォルトでは、フィールドグループはエディター内で折りたたまれた状態で表示されます。ネストされたグループを含むグループはドリルダウンボタンとして表示され、独自のビューで開き、最も内側のグループには区切り線が表示されます。
デフォルト折りたたみグループ
  • 表示タイプ: デフォルトでは、ネストされたグループを含まないグループは、子グループの周囲に視覚的な区切り線が付いた折りたたみ可能なセクションとして表示されます。ネストされたグループを含むグループはドリルダウンボタンとして表示され、独自のビューで開き、最も内側のグループは区切り線付きで表示されます。
  • グループアイコン: 必要に応じて、ラベルの左側に表示する「Font Awesome」アイコンを含めることができます。
アイコンの例
[
  {
    "type": "group",
    "name": "recipe_summary_group",
    "label": "Recipe summary",
    "display": "drilldown",
    "inline_help_text": "Summarize the recipe (title and description)",
    "icon": {
      "name": "star",
      "set": "fontawesome-5.14.0",
      "type": "SOLID"
    },
    "children": [
      {
        "type": "text",
        "label": "Recipe title",
        "name": "recipe_title",
        "placeholder": "Burrata salad"
      },
      {
        "type": "text",
        "label": "Recipe description",
        "name": "recipe_description",
        "placeholder": "fig mostarda, hazelnuts, arugula, vincotto, prosciutto, toasted sourdough"
      }
    ]
  }
]
パラメータータイプ説明
display文字列フィールドグループの表示スタイル。次のいずれかになります。
  • drilldown:折りたたまれたグループに、子グループを独自のパネルで開くためのボタンが表示されます。これは、ネストされたグループを含むグループのデフォルト表示です。
  • accordion:折りたたまれたグループの下に、子グループを展開するボタンを展開可能なセクションとして表示します。これは、ネストされたグループがないグループのデフォルト表示です。
  • inline:グループと子グループをインラインで表示し、グループを折りたたむオプションはありません。
iconオブジェクトラベルの左側にアイコンを追加します。次のパラメーターがあります。
  • name:Font Awesomeアイコンの識別子。
  • set:Font Awesomeのアイコンセット(英語)。
  • type:アイコンのスタイル(例:SOLIDREGULAR)。
expandedブール値フィールドグループがデフォルトで展開されるかどうかを指定します。

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

フィールドグループでは、出力するフィールド値を含むディクショナリー(辞書型)が作成されます。フィールドグループをネストした場合、ネストされたフィールドグループは外側のフィールド グループ ディクショナリー内にディクショナリーとして格納されます。このデータにアクセスするには、状況に応じてルートのテーマまたはモジュール変数からツリー内を走査する必要があります。
<div>
{# printing a value from a field group `recipe_summary` is the field group,
`title` is the text field. #} {{module.recipe_summary.title}}
</div>

フィールドグループの特集項目

フィールドグループが繰り返される状況では、出現するフィールドグループのうち1つ以上をキービジュアル項目として指定できます。これにより、項目を個別にスタイル設定して目立たせることができます。例えば、強調表示したいおすすめの製品を表示する製品ページで特に便利です。 フィールドグループあたりの特集項目の最大数を指定できます。その後、制作担当者はエディターで必要に応じて項目を特集項目としてマークできます。
cms-field-group-featured-in-app (1)
) フィールドグループ内で特集項目を有効にするには、フィールドグループの設定にgroup_occurrence_metaプロパティーを含めます。このプロパティーには次のプロパティーが格納されます。
  • featured_enabledtrueに設定すると、特集項目が有効になります。
  • featured_limit:使用できる特集項目の最大数。
フィールドグループにはoccurrenceプロパティーも含める必要があります。
// Field group example
{
  "label": "Card",
  "name": "card",
  "type": "group",
  "occurrence": {
    "default": 2,
    "min": 1,
    "sorting_label_field": "card.title"
  },
  "group_occurrence_meta": {
    "featured_enabled": true,
    "featured_limit": 3
  },
  "children": [
    {
      "label": "Image",
      "name": "image",
      "type": "image",
      "responsive": true,
      "resizable": true,
      "show_loading": true,
      "default": {
        "loading": "lazy"
      }
    },
    {
      "label": "Content",
      "name": "text",
      "type": "richtext",
      "enabled_features": [
        "advanced_emphasis",
        "alignment",
        "block",
        "emoji",
        "font_family",
        "font_size",
        "lists",
        "standard_emphasis"
      ],
      "default": "<h3>This is a title</h3><p>Contextual advertising can be profitable. It can either pay for your hosting and maintenance costs for you website or it can pay for a lot more.</p>"
    }
  ],
  "default": [
    {
      "image": {
        "loading": "lazy"
      },
      "text": "<h3>This is a title</h3><p>Contextual advertising can be profitable. It can either pay for your hosting and maintenance costs for you website or it can pay for a lot more.</p>"
    },
    {
      "image": {
        "loading": "lazy"
      },
      "text": "<h3>This is a title</h3><p>Contextual advertising can be profitable. It can either pay for your hosting and maintenance costs for you website or it can pay for a lot more.</p>"
    }
  ]
}
繰り返しグループ内の項目がキービジュアルであるかどうかを確認するには、hs_metaプロパティーを照会します。以下のコードでは、forループを使用して、特集項目に設定されているフィールドグループ項目を確認し、各項目のタイトルをh3ヘッダーとして表示しています。 {{ repeated_group_item.hs_meta.occurrence.featured }}
<div>
  <h2>Check out this week's featured items:</h2>
  <div>
    {% for item in module.card %}
        {% if item.hs_meta.occurrence.featured %}
            <h3>{{item.title}}</h3>
        {% endif %}
    {% endfor %}
  </div>
</div>

スタイルフィールド

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

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

モジュールに追加したスタイルフィールドは、モジュール編集時のページエディターの[スタイル]タブに表示されます。
スタイルフィールド-モジュールエディター
スタイルフィールドをモジュールの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ボイラープレート(英語)をご参照ください。

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

テーマに追加したスタイルフィールドは、テーマエディターの左のサイドバーに表示されます。
スタイルフィールド-テーマエディター
以下のように、テーマの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.style.gradient.css %}
  background: {{ module.style.gradient.css }};
  {% endif %}
  {{ module.style.bg_img.css }}
  {{ module.style.spacing.css }}
  {{ module.style.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",
}
パラメータータイプ説明デフォルト値
max整数このグループの最大出現回数。制作担当者がUIにこの数以上のアイテムを追加できないようにします。null
min整数このフィールドグループの最小出現数。UIに表示されるアイテムがこの数より少なくなるのを防ぎます。null
sorting_label_field文字列ドラッグ操作可能なカード上の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_paths" : {
      "font": "module.body_font.font",
      "font_set": "module.body_font.font_set"
    }
  }
}
フォントファミリーはfontfont_setの組み合わせによって決まるため、フォントフィールドの継承にはこの両方を含める必要があります。詳しくはフォントフィールドをご確認ください。
複雑なフィールド(値がオブジェクトのフィールド)の場合、ユーザーは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 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によって関連付けられた他のフィールドから影響を与えることはできなくなります。

フィールドの可視性

カスタムモジュールとテーマフィールドを定義する際に、fields.jsonファイル内のフィールドにvisibilityオブジェクトを追加することで、フィールドが表示される条件を構成できます。例えば、サンキューメッセージが選択されているときにはリッチテキスト領域を表示する一方で、リダイレクトが選択されているときはページセレクターを表示するようにフォームモジュールを設定できます。 表示条件はcontrolling_field_pathの値を基準に設定することも、propertyパラメーターを使用してフィールド内の特定のプロパティーを基準に設定することもできます。また、個々のフィールドに表示条件を適用したり、フィールドのグループに表示条件を適用して、そのグループ内の全ての要素の表示条件を管理したりすることもできます。
"visibility" : {
 "controlling_field_path" : "field_name",
 "controlling_value_regex" : "regular_expression_in_controlling_field",
 "property": "src",
 "operator" : "EQUAL"
  }
パラメータータイプ説明
controlling_field_path文字列表示条件を制御するフィールドのパス。
  • フィールドがフィールドグループ内にネストされていない場合は、フィールドの名前(つまりfield_name)を使用します。
  • グループ内にネストされたフィールドの場合、パスはピリオドで区切られたグループ化構造と一致する必要があります。例:
    • field_group_name.field_name
    • parent_group.child_group.field_name
controlling_value_regex文字列フィールドを表示するために存在する必要がある制御フィールドの正規表現。正規表現は(部分文字列ではなく)文字列全体に一致する必要があり、大文字と小文字も区別されます。
operator文字列controlling_value_regex値との一致方法を定義する演算子。次のいずれかの演算子を使用できます。
  • NOT_EQUAL
  • EQUAL
  • EMPTY
  • NOT_EMPTY
  • MATCHES_REGEX
property文字列文字列ターゲットフィールドの特定のプロパティーに基づいて表示条件を設定します。例えば、画像フィールドのsrcプロパティーが特定の値と等しい場合に、このフィールドが表示されるようにできます。デフォルトでは、このフィールドに値が指定されていない場合、表示条件は文字列に変換されたcontrolling_value_regex値に基づくことになります。
visibilityオブジェクト内にoccurrence_optionsオブジェクトを含めると、繰り返されるフィールドの値数をターゲットにすることもできます。このオブジェクトには、比較するcountoperatorの定義を含める必要があります。例えば、別の繰り返しフィールドに少なくとも2つの項目がある場合にのみテキストフィールドを表示するには、visibilityを次のように定義します。
[
  {
    "type": "group",
    "name": "ingredients",
    "label": "Recipe ingredients",
    "display": "drilldown",
    "children": [
      {
        "name": "ingredient",
        "label": "Ingredient",
        "occurrence": {
          "min": 1,
          "max": null,
          "default": 1
        },
        "type": "text",
        "default": ["1 cup water"]
      },
      {
        "type": "text",
        "label": "Conditional field",
        "name": "conditional_field",
        "visibility": {
          "controlling_field_path": "ingredients.ingredient",
          "occurrence_options": {
            "count": 2,
            "operator": "GREATER_THAN_OR_EQUAL"
          }
        }
      }
    ]
  }
]
次のいずれかのoperaterの値を使用できます。
  • "NOT_EQUAL"
  • "EQUAL"
  • "EMPTY"
  • "NOT_EMPTY"
  • "GREATER_THAN"
  • "GREATER_THAN_OR_EQUAL"
  • "LESS_THAN"
  • "LESS_THAN_OR_EQUAL"

高度な可視性

visibility属性で同時に複数の条件をサポートすることはできません。複数の演算子を使用して複数の条件を追加し、演算の順序も指定するには、advanced_visibilityを使用します。
"visibility_rules" : "ADVANCED",
"advanced_visibility" : {
   "boolean_operator" : "AND",
   "criteria" : [{
     "controlling_field_path" : "field_name",
     "controlling_value_regex" : "regular_expression_in_controlling_field",
      "operator" : "MATCHES_REGEX"
    },
    {
     "controlling_field_path" : "field_name",
     "controlling_value_regex" : "regular_expression_in_controlling_field",
     "operator" : "EQUAL"
    }]
}
パラメータータイプ説明
visibility_rules文字列デフォルトでは、このパラメーターの値はSIMPLEに設定されます。advanced_visibilityを使用する場合は、ADVANCEDに設定します。
boolean_operator文字列条件付き基準のブール演算子。ANDまたはORのいずれかにできます。
criteria配列フィールドを表示するために一致する必要がある条件付き基準を定義する、visibilityオブジェクトからなる配列。
controlling_field_path文字列表示条件を制御するフィールドのドットパス。
  • フィールドがフィールドグループ内にネストされていない場合は、フィールドの名前(つまりfield_name)を使用します。
  • グループにネストされたフィールドの場合、パスはピリオドで区切られたグループ化構造と一致する必要があります。例:
    • field_group_name.field_name
    • parent_group.child_group.field_name
controlling_value_regex文字列フィールドを表示するために一致する必要がある、制御フィールドの値。MATCHES_REGEX演算子を使用する場合、正規表現は(部分文字列ではなく)文字列全体に一致する必要があり、大文字と小文字も区別されます。controlling_field_pathが設定されている一方、controlling_value_regexは設定されていないフィールドは、制御フィールドの値がnullでも空白でもない場合に表示されます。
operator文字列controlling_value_regex値との一致方法を定義する演算子。次のいずれかの演算子を使用できます。
  • NOT_EQUAL
  • EQUAL
  • EMPTY
  • NOT_EMPTY
  • MATCHES_REGEX
MATCHES_REGEXを使用する場合は、正規表現の構文が必要です。
一例として、以下にデフォルトの支払いモジュールの最初の部分を記載します。完全なコードを確認するには、HubSpotでこのモジュールを複製してからローカル環境にダウンロードして、モジュールのfields.jsonファイルを表示してください。
[
  {
    "id": "payment",
    "name": "payment",
    "display_width": null,
    "label": "Payment",
    "required": true,
    "locked": false,
    "type": "payment",
    "default": {
      "id": null,
      "properties": {}
    }
  },
  {
    "id": "checkout_location",
    "name": "checkout_location",
    "display_width": null,
    "label": "Checkout behavior",
    "required": false,
    "locked": false,
    "visibility": {
      "controlling_field_path": "payment",
      "controlling_value_regex": "id\":\\d+",
      "operator": "MATCHES_REGEX"
    },
    "display": "radio",
    "choices": [
      ["new_tab", "Open in a new tab"],
      ["overlay", "Sliding overlay"]
    ],
    "type": "choice",
    "default": "new_tab"
  },
  {
    "id": "button_text",
    "name": "button_text",
    "display_width": null,
    "label": "Button text",
    "required": true,
    "locked": false,
    "validation_regex": "",
    "visibility": {
      "controlling_field_path": "payment",
      "controlling_value_regex": "id\":\\d+",
      "operator": "MATCHES_REGEX"
    },
    "allow_new_line": false,
    "show_emoji_picker": false,
    "type": "text",
    "default": "Checkout"
  },
  {
    "id": "icon",
    "name": "icon",
    "display_width": null,
    "label": "Icon",
    "required": false,
    "locked": false,
    "visibility_rules": "ADVANCED",
    "advanced_visibility": {
      "boolean_operator": "AND",
      "criteria": [
        {
          "controlling_field_path": "payment",
          "controlling_value_regex": "id\":\\d+",
          "operator": "MATCHES_REGEX"
        },
        {
          "controlling_field_path": "add_icon",
          "controlling_value_regex": "true",
          "operator": "EQUAL"
        }
      ],
      "children": []
    },
    "children": [
      {
        "id": "icon.icon",
        "name": "icon",
        "display_width": null,
        "label": "Icon",
        "required": true,
        "locked": false,
        "icon_set": "fontawesome-5.0.10",
        "type": "icon",
        "default": {
          "name": "hubspot",
          "type": "SOLID",
          "unicode": "f3b2"
        }
      },
      {
        "id": "icon.position",
        "name": "position",
        "display_width": null,
        "label": "Position",
        "required": true,
        "locked": false,
        "display": "select",
        "choices": [
          ["left", "Left"],
          ["right", "Right"]
        ],
        "type": "choice",
        "default": "left"
      }
    ],
    "tab": "CONTENT",
    "expanded": false,
    "type": "group"
  }
  // rest of fields.json code
]
上記のコードによって、次のような動作になります。 最初のフィールド(payment)は、コンテンツ制作担当者が特定の支払いリンクを作成するために使用する、必須のフィールド(ドロップダウンメニュー)です。HubSpotでは、コンテンツ制作担当者が最初にこのモジュールをページに追加すると、次のUIが表示されます。
支払いリンクの選択肢
支払いリンクを選択すると、上記のUIの後に続いて3つのフィールド(checkout_locationbutton_texticon)が表示されます。このようになるのは、paymentフィールドによって制御され、paymentフィールドのidパラメーターのID値を必要とするvisibility属性が、これらのフィールドに設定されているためです。 iconフィールド自体はadvanced_visibilityを使用しており、paymentフィールドに支払いリンクが存在し、かつ、add_iconチェックボックスがオンにされている場合にのみ表示されます。 fields.json内で可視性を設定するだけでなく、デザインマネージャーでフィールドの「表示条件」オプションを編集して可視性を設定することもできます。
表示条件オプション
デザインマネージャーで表示条件を設定した後は、CLIを使用してこのモジュールをフェッチし、モジュールのfields.jsonファイル内でvisibility属性を確認できます。

条件付きフィールドの無効化

フィールドに条件を追加して、指定された条件が満たされたときに編集不可にすることができます。フィールドを無効にした場合、コンテンツエディターでコンテキストを提供するために、フィールドの上に表示するメッセージを設定することもできます。
Screenshot 2023-05-23 at 4.10.28 PM
条件とメッセージは、フィールドのdisabled_controlsオブジェクトで設定されます。フィールドを編集可能にするための条件は、rulesオブジェクト内で設定され、advanced_visibilityと同じ形式に従います。 以下のコードは、rules基準の単純な実装と高度な実装の両方を示しています。
  • simple_pageフィールドには、text_fieldtestingに設定されている場合にフィールドを無効にするロジックが含まれています。
  • fancy_pageフィールドには、text_fieldまたはtext_field_2のいずれかがそれぞれtestingtesting2に等しくない値に設定されている場合にフィールドを無効にするロジックが含まれています。
// example fields.json
[
  {
    "type": "text",
    "name": "text_field",
    "label": "Text field"
  },
  {
    "type": "text",
    "name": "text_field_2",
    "label": "Text field 2"
  },
  {
    "type": "page",
    "label": "Simple Page",
    "name": "simple_page",
    "disabled_controls": {
      "message": "This field is disabled",
      "rules": {
        "criteria": [
          {
            "controlling_field_path": "text_field",
            "operator": "EQUAL",
            "controlling_value_regex": "testing"
          }
        ]
      }
    }
  },
  {
    "type": "page",
    "label": "Fancy Page",
    "name": "fancy_page",
    "disabled_controls": {
      "message": "This field is disabled",
      "rules": {
        "boolean_operator": "OR",
        "criteria": [
          {
            "controlling_field_path": "text_field",
            "operator": "NOT_EQUAL",
            "controlling_value_regex": "testing"
          },
          {
            "controlling_field_path": "text_field_2",
            "operator": "NOT_EQUAL",
            "controlling_value_regex": "testing2"
          }
        ]
      }
    }
  }
]
パラメータータイプ説明
message文字列フィールドが無効な場合にコンテンツエディターに表示するメッセージ。
rulesオブジェクトフィールドの編集を有効にするための条件。
criteria配列フィールドを表示するために満たす必要がある基準を定義する条件オブジェクトの配列。この配列には、boolean_operatorパラメーターを使用してANDまたはORロジックで区切られた複数の条件オブジェクトを含めることができます。
boolean_operator文字列条件付き基準のブール演算子。ANDまたはORのいずれかにできます。指定しなかった場合、デフォルトでANDになります。
controlling_field_path文字列表示条件を制御するフィールドのドットパス。
  • フィールドがフィールドグループ内にネストされていない場合は、フィールドの名前(つまりfield_name)を使用します。
  • グループにネストされたフィールドの場合、パスはピリオドで区切られたグループ化構造と一致する必要があります。例:
    • field_group_name.field_name
    • parent_group.child_group.field_name
controlling_value_regex文字列フィールドを表示するために一致する必要がある、制御フィールドの値。MATCHES_REGEX演算子を使用する場合、正規表現は(部分文字列ではなく)文字列全体に一致する必要があり、大文字と小文字も区別されます。controlling_field_pathが設定されている一方、controlling_value_regexは設定されていないフィールドは、制御フィールドの値がnullでも空白でもない場合に表示されます。
operator文字列controlling_value_regex値との一致方法を定義する演算子。次のいずれかの演算子を使用できます。
  • NOT_EQUAL
  • EQUAL
  • EMPTY
  • NOT_EMPTY
  • MATCHES_REGEX
MATCHES_REGEXを使用する場合は、正規表現の構文が必要です。

テーマ エディター フィールドのハイライト機能

テーマエディターでプレビューハイライト機能を使用すると、コンテンツ作成者が、どのフィールドがどのページ要素を制御しているかを理解するのに役立ちます。プレビューハイライト機能は、テーマフィールドをそのフィールドの影響を受けるCSSセレクターにマッピングすることによって機能します。テーマエディターでフィールドにカーソルを合わせると、そのフィールドがマッピングされている要素がボックスで囲んで表示されるという仕組みです。 テーマフィールドのプレビューハイライト機能を構成するには、テーマのルートディレクトリー内に、テーマフィールドとCSSセレクターのリストとのマッピングを指定するためのeditor-preview.jsonファイルを追加します。このファイルで、関連するCSSセレクターが含まれる、ハイライト表示する対象のスタイルフィールドごとに、次の形式を使用して配列を含めます。
// editor-preview.json
{
  "selectors": {
    "theme.settings.path.1": [ <CSS selectors> ],
    "theme.settings.path.2": [ <CSS selectors> ],
  }
}
例えば、以下のコードは、プライマリー フォント フィールドによって制御されるページ要素をハイライト表示します。完全な例については、デフォルトのGrowthテーマのeditor-preview.jsonファイルでご確認ください。
// editor-preview.json
{
  "selectors": {
    "fonts.primary": [
      "button, .button, .hs-button",
      "form input[type='submit'], form .hs-button",
      ".error-page:before",
      "p",
      "blockquote > footer",
      "form td.is-today .pika-button",
      "form .is-selected .pika-button",
      "th, td",
      ".blog-listing__post-tag",
      ".blog-listing__post-author-name, .blog-post__author-name",
      ".pagination__link-icon svg",
      ".tabs__tab",
      "a",
      ".button.button--simple",
      ".pagination__link .pagination__link-icon svg",
      ".card--dark",
      ".card--light",
      ".card--light summary, .card--light p, .card--light h1, .card--light h2, .card--light h3, .card--light h4, .card--light h5, .card--light h6, .card--light a:not(.button), .card--light span, .card--light div, .card--light li, .card--light blockquote",
      ".card--light .accordion__summary:before",
      "tfoot th, tfoot td",
      ".header__language-switcher-current-label > span",
      ".header__language-switcher-child-toggle svg",
      ".header__language-switcher .lang_list_class a:not(.button)",
      ".header__menu-link",
      ".header__menu-item--depth-1 > .header__menu-link:not(.button)",
      ".header__menu-item--depth-1 .header__menu-child-toggle svg",
      ".header__menu-toggle svg",
      ".header__language-switcher .header__language-switcher-current-label > span",
      ".header p, .header h1, .header h2, .header h3, .header h4, .header h5, .header h6, .header a:not(.button), .header span, .header li, .header blockquote, .header .tabs__tab, .header .tabs__tab, .header .tabs__tab, .header .tabs__tab",
      ".footer .hs-menu-wrapper a",
      ".footer h1, .footer h2, .footer h3, .footer h4, .footer h5, .footer h6, .footer p, .footer a:not(.button), .footer span, .footer div, .footer li, .footer blockquote, .footer .tabs__tab, .footer .tabs__tab, .footer .tabs__tab, .footer .tabs__tab",
      ".footer hr",
      "form label",
      "#email-prefs-form, #email-prefs-form h1, #email-prefs-form h2",
      "form legend",
      "form input[type='text'], form input[type='email'], form input[type='password'], form input[type='tel'], form input[type='number'], form input[type='search'], form select, form textarea",
      ".backup-unsubscribe input[type='email']",
      "form .legal-consent-container, form .legal-consent-container .hs-richtext, form .legal-consent-container .hs-richtext p",
      "form .hs-richtext, form .hs-richtext *, form .hs-richtext p, form .hs-richtext h1, form .hs-richtext h2, form .hs-richtext h3, form .hs-richtext h4, form .hs-richtext h5, form .hs-richtext h6",
      "button, button, button, .button, .button, .button, .hs-button, .hs-button, .hs-button",
      "button, .button, .hs-button",
      ".button.button--secondary, .button.button--secondary, .button.button--secondary",
      ".button.button--secondary",
      ".header__menu-item--depth-1 > .header__menu-link, .header__menu-item--depth-1 > .header__menu-link",
      ".header__menu-item--depth-1 > .header__menu-link",
      ".header__menu-submenu .header__menu-link, .header__menu-submenu .header__menu-link",
      ".header__language-switcher .lang_list_class a, .header__language-switcher .lang_list_class a",
      ".header__menu-submenu .header__menu-link:not(.button)",
      ".footer .hs-menu-wrapper a, .footer .hs-menu-wrapper a",
      ".footer .hs-menu-wrapper a",
      "form .hs-richtext a",
      ".header__menu-item--depth-1 > .header__menu-link--active-link:not(.button)",
      ".footer .hs-menu-wrapper .active > a"
    ]
  }
}
Growthテーマ-hover
このファイルを作成するには、まず、次のCLIコマンドを実行してファイルを生成します。ファイルの生成中にスクリプトが実行されて、初期フィールド セレクター マッピングが設定されます。
hs theme generate-selectors <theme-directory-path>
パラメーター説明
theme-directory-pathテーマディレクトリーへのパス。
このコマンドを実行した後、editor-preview.jsonファイルを確認し、フィールドとセレクターが適切にマッピングされるように調整する必要があります。Generate-selectorsコマンドでは、どのフィールドがどのセレクターに影響するかについて基本的な推測が行われるだけなので、テーマがどのように作成されているかに基づいて修正する必要があります。例えばこのコマンドでは、モジュールがスタイル設定をオーバーライドしていたり、マクロが使用されたりしていても検出できません。 設定されているマッピングをテストするには、テーマをアカウントにアップロードし、そのアカウント内でテーマエディターを表示します([設定]>[ウェブサイト]>[テーマ]>[テーマを表示])。