モジュールとテーマのフィールドの概要
モジュールとテーマ内では、コンテンツクリエイターがウェブサイトのモジュールとテーマのスタイルと機能を制御するためのフィールドが使用されます。モジュールまたはテーマを開発する場合は、fields.json
ファイルにフィールドを組み込み、テーマエディターとコンテンツエディターに変換します。
この記事では、モジュールとテーマのフィールドのオプションを作成および管理する方法を詳しく説明します。特定のフィールドタイプの詳細については、モジュールおよびフィールドタイプのリファレンスガイドをご覧ください。
モジュールのfields.json
ファイルには、HubSpot CLIを使用してローカル環境で、またはアプリ内のモジュールエディター上でフィールドを追加できます。テーマにフィールドを追加するには、CLIを使用してテーマのfields.json
ファイルをローカル環境で更新する必要があります。
モジュールフィールドとテーマフィールドをローカル環境で構築する場合、モジュールまたはテーマのフォルダー内にあるfields.json
ファイル経由で編集できます。モジュールの場合、hs create module
コマンドを使用すると、このファイルが自動作成されます。モジュールエディターで利用可能な全てのフィールドオプションは、fields.json
ファイルで追加または編集できるプロパティーとして使用できます。これには、リピーターフィールド、グループ、条件が含まれます。ローカル編集の利点の1つは、gitのようなバージョン管理システムにモジュールを含めることが容易になることです。
デザインマネージャーには組み込みのモジュールエディターUIがあり、モジュールフィールドの作成、グループ化、編集に使用できます。モジュールエディターにはモジュールのプレビューがあるため、モジュールの外観の確認とフィールドのテストができます。モジュールは、常に使用する予定のテンプレートでモジュールをテストして、どのようなテンプレートでのスタイルからの影響があるかを確認する必要があります。なお、ロックされたフォルダーにモジュールが含まれている場合は、この方法で編集できないことに注意してください。

注:主にローカル環境で作業し、フィールドの設定にモジュールエディターを使用する場合は、必ず変更をfetch(フェッチ)してください。gitのようなバージョン管理システムを使用する場合には、特に重要です。
既定では、コンテンツエディターではモジュールフィールドは縦方向に配置されます。しかし、モジュールフィールドは横並びに配列することもできます。このためには、fields.json
ファイルのフィールドにdisplay_width
プロパティーを追加し、値をhalf_width
に設定します。
display_width
をhalf_width
に設定した1つのフィールドは、コンテンツエディターでは半分の幅で表示されます。fields.json
内のこのフィールドの上または下にあるフィールドをhalf_width
に設定すると、フィールドが横並びに配置されます。
フィールドが互いに関連している場合、グループ化して表示することが適切な場合が少なくありません。モジュールもテーマも複数のフィールドのグループ化に対応しています。

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

フィールドグループはネストできます。別のフィールドグループを含むフィールドグループはボタンとして表示されます。ボタンをクリックすると、グループの内容が表示されます。
フィールドグループは、3階層までネストできます。つまり、モジュールフィールドの深さは4階層まで設定できます。フィールドの関係性と深さが分かるユーザーインターフェイスを簡単に作成できます。
フィールド グループ オブジェクトは、他のフィールドグループの子になることができます。構造はフィールド自体と非常に似ていますが、含まれるフィールドとグループの配列、「children」パラメーターという特別なパラメーターがあります。
フィールドグループは、上記のコード例で示されているように、fields.jsonグループプロパティー内でexpanded
ブール値プロパティーをtrue
に設定することで、既定で展開できます。フィールドグループは既定で展開されないため、ネストされたフィールドグループを使用する場合には、親グループにこのプロパティーを使用することはできません。
フィールドグループでは、出力するフィールド値を含むディクショナリー(辞書型)が作成されます。フィールドグループをネストした場合、ネストされたフィールドグループは外側のフィールド グループ ディクショナリー内にディクショナリーとして格納されます。このデータにアクセスするには、状況に応じてルートのテーマまたはモジュール変数からツリー内を走査する必要があります。
スタイルフィールドは、モジュールまたはテーマのfields.json
ファイルの特殊なフィールド グループ タイプで、これによって制作担当者がモジュールやテーマのスタイルをページエディターとテーマエディター上で制御できるようになります。モジュールまたはテーマにスタイルフィールドを追加する方法を以下に示します。スタイルフィールドの使用と整理に関するベストプラクティスを参照してください。
モジュールのスタイルフィールド
モジュールに追加したスタイルフィールドは、モジュール編集時のページエディターの[スタイル]タブに表示されます。
スタイルフィールドをモジュールのfields.json
ファイルに追加する場合は、全てのフィールドを1つのスタイルグループ内に追加します。ただし、次のようにこのグループ内に複数のグループを含めることができます。
テーマのスタイルフィールド
テーマに追加したスタイルフィールドは、テーマエディターの左のサイドバーに表示されます。
以下のように、テーマのfields.json
ファイル内にある全てのスタイルフィールドは、テーマエディターの左のサイドバーに追加され、スタイルグループに追加する必要はありません。
モジュールのスタイルフィールドとして使用できるフィールドを以下に示します。各フィールドタイプについては、モジュールとフィールドタイプのガイドをご確認ください。
モジュールとテーマのフィールドタイプをご覧ください。
テーマのfields.json
ファイル内のスタイルフィールドの例については、CMSボイラープレートを参照してください。
注:マーケットプレイスで提供している場合は、既存のモジュール内の既存のコンテンツフィールドをスタイルフィールドで置き換えないでください。fields.json
ファイルのフィールド階層を変更すると、既存のモジュールインスタンスのデータが失われることがあります。代わりに、新しいスタイルフィールドの追加、またはフィールドを適切にグループ化した新しいリストの作成ができます。これにより、貴社の更新によって、貴社のテーマを利用している顧客のコンテンツが破損するような変更は避けられます。以前のモジュールの移行パスについては、HubSpotアイデアフォーラム(英語)を参照してください。
情報を形成するモジュールを作成する際には、繰り返し使用される情報があります。例えば、レシピモジュールに「材料」のフィールドがあるとします。ほとんどのレシピの材料は1つにとどまりません。リッチ テキスト フィールドを利用した場合、スタイルの一貫性を確保したり、材料別の機能を追加したりすることはできなくなります。このような状況ではリピーターが役に立ちます。HubSpotには繰り返しフィールドと繰り返しグループという2つの形式のリピーターがあります。
繰り返しフィールドは通常のフィールドですが、制作担当者がフィールドのインスタンスを追加、削除、再配置できます。上記のレシピモジュールの例では、各材料を繰り返しテキストフィールドにできます。

これにより、制作担当者は必要な数の材料を追加できます。開発者の観点からは、ループ処理によって材料のリストを出力できる配列を使用して、必要な書式と機能を適用できます。
繰り返しフィールドは非常にシンプルな状況に最適です。一般的には、繰り返しグループが適切なケースが多くあります。
注:現在のところ、繰り返しフィールドの既定の順序を設定することはできません。
繰り返しグループは、繰り返しに対応したフィールドグループです。繰り返しグループを使用すると、制作担当者がフィールドのグループを追加、削除、再配置できるようになります。レシピモジュールで、材料リストにショッピングリスト機能を統合するとします。

ショッピングリストでは、材料の数量が重要です。数量がテキストフィールドに入力されると同時に、このモジュールがテキストフィールドを解析して、材料から数量が正常に分離されるようにする必要があります。そこで役立つのが、繰り返しグループです。こうしたフィールドの出力に対し、ループ処理を行うことができます。
編集時の利便性を向上すると共に、プログラム側で未対応の値が入力できないように、繰り返しフィールドや繰り返しグループには、制作担当者による追加可能項目数の最小値と最大値を設定できます。
繰り返しグループでは、リピーターを表示するときに、その項目のラベルとして機能するフィールドを設定することもできます。

Parameter | Type | Description | Default |
---|---|---|---|
max
| 整数 | このグループの最大出現回数。UIからのこの数を超える項目の追加を防止します。 |
null
|
min
| 整数 | このフィールドグループの最小出現数。UIからのこの数を下回る項目数の指定を防止します。 |
null
|
sorting_label_field
| 文字列 | ドラッグ操作可能なカードのUIに表示するテキストを取得できるフィールドのIDです。既定は、グループ内の最初のフィールドです。 |
inherited_value
プロパティーは、他のフィールドから既定値を継承するようにフィールドを設定できます。フィールドの既定値全体を別のフィールド値から設定するには、default_value_path
にターゲットフィールドのフィールド名パスを指定します。default_value_path
を設定すると、フィールドに設定されたdefault
は全て無視されます。
他のフィールドの値にアクセスするには、モジュールのHubLコードでのアクセスと同様に、パスの先頭に module.
を含める必要があります。
複雑なフィールド(値がオブジェクトのフィールド)の場合、ユーザーはproperty_value_path
に継承するプロパティーを細かく指定できます。inherited_value
で参照されるパスにも、複雑なフィールドのフィールド値からのキーを含めることができます。例えば、色フィールドには、色自体と不透明度を含むオブジェクト値があります。そのため、不透明度なしで色自体の値を取得するには、パスの末尾に.color
を指定します。例えばフォントフィールドは、個別の色フィールドから色だけを継承できます。
default_value_path
とproperty_value_paths
の効果を組み合わせて、あるフィールドから既定値を継承しながら、別のフィールドから特定のプロパティー値を継承することもできます。
別のフィールドから継承したフィールドが、ページまたはテーマ設定によって直接変更される場合、制御元のフィールドとの接続は失われます。このフィールドの値に、default_value_path
またはproperty_value_paths
によって関連付けられた他のフィールドから影響を与えることはできなくなります。
カスタムモジュールとテーマフィールドを定義する際に、fields.json
ファイル内のフィールドにvisibility
オブジェクトを追加することで、フィールドが表示される条件を構成できます。例えば、サンキューメッセージが選択されているときにはリッチテキスト領域を表示する一方で、リダイレクトが選択されているときはページセレクターを表示するようにフォームモジュールを設定できます。
表示条件はcontrolling_field_path
の値を基準に設定することも、property
パラメーターを使用してフィールド内の特定のプロパティーを基準に設定することもできます。
また、個々のフィールドに表示条件を適用したり、フィールドのグループに表示条件を適用して、そのグループ内の全ての要素の表示条件を管理したりすることもできます。
Parameter | Type | Description |
---|---|---|
controlling_field_path
| String | 表示条件を管理するフィールドのパス。
|
controlling_value_regex
| String | フィールドを表示するために存在する必要がある制御フィールドの正規表現。正規表現は(部分文字列ではなく)文字列全体に一致する必要があり、大文字と小文字も区別されます。 |
operator
| String |
|
property
| String | ターゲットフィールドの特定のプロパティーに基づく表示条件を設定します。例えば、画像フィールドの |
visibility属性で同時に複数の条件をサポートすることはできません。複数の演算子を使用して複数の条件を追加し、演算の順序も指定するには、advanced_visibility
を使用します。
Parameter | Type | Description |
---|---|---|
visibility_rules
| String | 既定では、このパラメーターの値は |
boolean_operator
| String | 条件付き基準のブール演算子。 |
criteria
| Array | フィールドを表示するために一致する必要がある条件付き基準を定義する、visibilityオブジェクトからなる配列。 |
controlling_field_path
| String | 表示条件を管理するフィールドのパス。
|
controlling_value_regex
| String | フィールドを表示するために一致する必要がある、制御フィールドの値。
|
operator
| String |
|
一例として、以下に既定の支払いモジュールの最初の部分を記載します。完全なコードを確認するには、HubSpotでこのモジュールを複製してからローカル環境にダウンロードして、モジュールのfields.json
ファイルを表示してください。
上記のコードによって、次のような動作になります。
- 最初のフィールド(
payment
)は、コンテンツ制作担当者が特定の支払いリンクを作成するために使用する、必須のフィールド(ドロップダウンメニュー)です。HubSpotでは、コンテンツ制作担当者が最初にこのモジュールをページに追加すると、次のUIが表示されます。
- 支払いリンクを選択すると、上記のUIの後に続いて3つのフィールド(
checkout_location
、button_text
、icon
)が表示されます。このようになるのは、payment
フィールドによって制御され、paymentフィールドのid
パラメーターのID値を必要とするvisibility
属性が、これらのフィールドに設定されているためです。
icon
フィールド自体はadvanced_visibility
を使用しており、payment
フィールドに支払いリンクが存在し、かつ、add_icon
チェックボックスがオンにされている場合にのみ表示されます。
fields.json
内で表示条件を設定するという方法の他に、デザインマネージャーでフィールドの「表示条件」オプションを編集することによっても、表示条件を設定できます。
デザインマネージャーで表示条件を設定した後は、CLIを使用してこのモジュールをフェッチし、モジュールのfields.json
ファイル内でvisibility
属性を確認できます。
フィールドに条件を追加して、指定された条件が満たされたときに編集不可にすることができます。フィールドを無効にした場合、コンテンツエディターでコンテキストを提供するために、フィールドの上に表示するメッセージを設定することもできます。
条件とメッセージは、フィールドのdisabled_controls
オブジェクトで設定されます。フィールドを編集可能にするための条件は、rules
オブジェクト内で設定され、advanced_visibilityと同じ形式に従います。
以下のコードは、rules
基準の単純な実装と高度な実装の両方を示しています。
simple_page
フィールドには、text_field
がtesting
に設定されている場合にフィールドを無効にするロジックが含まれています。fancy_page
フィールドには、text_field
またはtext_field_2
のいずれかがそれぞれtesting
とtesting2
に等しくない値に設定されている場合にフィールドを無効にするロジックが含まれています。
Parameter | Type | Description |
---|---|---|
message
| 文字列 | フィールドが無効になっているときにコンテンツエディターに表示するメッセージ。 |
rules
| オブジェクト | フィールドの編集を有効にするための条件。 |
criteria
| 配列 | フィールドを表示するために満たす必要がある基準を定義する条件オブジェクトの配列。この配列には、 |
boolean_operator
| 文字列 | 条件付き基準のブール演算子。 |
controlling_field_path
| 文字列 | 表示条件を管理するフィールドのパス。
|
controlling_value_regex
| 文字列 | フィールドを表示するために一致する必要がある、制御フィールドの値。
|
operator
| 文字列 |
|
テーマエディターでプレビューハイライト機能を使用すると、コンテンツ作成者が、どのフィールドがどのページ要素を制御しているかを理解するのに役立ちます。プレビューハイライト機能は、テーマフィールドをそのフィールドの影響を受けるCSSセレクターにマッピングすることによって機能します。テーマエディターでフィールドにカーソルを合わせると、そのフィールドがマッピングされている要素がボックスで囲んで表示されるという仕組みです。
テーマフィールドのプレビューハイライト機能を構成するには、テーマのルートディレクトリー内に、テーマフィールドとCSSセレクターのリストとのマッピングを指定するためのeditor-preview.json
ファイルを追加します。このファイルで、関連するCSSセレクターが含まれる、ハイライト表示する対象のスタイルフィールドごとに、次の形式を使用して配列を含めます。
例えば、以下のコードは、プライマリー フォント フィールドによって制御されるページ要素をハイライト表示します。完全な例については、デフォルトのGrowthテーマのeditor-preview.json
ファイルでご確認ください。
このファイルを作成するには、まず、次の CLIコマンドを実行してファイルを生成します。ファイルの生成中にスクリプトが実行されて、初期フィールド セレクター マッピングが設定されます。
Parameter | Description |
---|---|
theme-directory-path
| テーマディレクトリーへのパス。 |
このコマンドを実行した後、editor-preview.json
ファイルを確認し、フィールドとセレクターが適切にマッピングされるように調整する必要があります。generate-selectorsコマンドでは、どのフィールドがどのセレクターに影響するかについて基本的な推測が行われるだけなので、テーマがどのように作成されているかに基づいて修正する必要があります。例えばこのコマンドでは、モジュールがスタイル設定をオーバーライドしていたり、マクロが使用されたりしていても検出できません。
設定されているマッピングをテストするには、テーマをアカウントにアップロードし、そのアカウント内でテーマエディターを表示します([設定]>[ウェブサイト]>[テーマ]>[テーマを表示])。
貴重なご意見をありがとうございました。