HubSpotテンプレートマーケットプレイスでのモジュール要件
テンプレートマーケットプレイスにモジュールを提出するための要件について説明します。これらの要件は、テーマ内のモジュールおよび独立したモジュールの両方に当てはまります。
HubDB、サーバーレス関数の呼び出し、CRMオブジェクトフィールドをモジュールに含めてはなりません。
独立したモジュールとして、次のモジュールタイプを構築しないでください
- HTML
- 全幅モジュール
- フォームとマルチステップフォーム
- スペーサーモジュール、または非UIページ構造を作成するモジュール
- 既定のモジュール機能と重複するモジュール
- コマース固有のモジュール
モジュールラベルとヘルプテキスト、フィールド、既定のコンテンツの要件については、以下で詳しく説明します。
- モジュールには、モジュールの目的を明確に示す記述的なラベルを付ける必要があります。例えば、「視差スクロールを備えたヒーローバナー」というラベルは分かりやすく記述されていますが、「ヒーローバナー」および「ギャラリー」というラベルは説明が不十分です。
- モジュールラベルには、「ヒーローバナー01」のように数字を含めることはできません。
- モジュールラベルには、「カラム（Column）」を表す「Col」のような略語を含めることはできません
- モジュールの使用方法をさらに詳しく伝えるために、モジュールには（該当する場合）インラインのヘルプテキストを含める必要があります。
- モジュールに既定のモジュールと同じ名前を付けることはできません。
- 既定のフィールドに「Lorem ipsum」テキストを含めることはできません。
- 既定のフィールドコンテンツはフィールドの目的を表す必要があります。
- メニューフィールドを含める場合、モジュールでは既定のコンテンツオプションとして「メニューを選択」を使用する必要があります。
- フォームフィールドを含める場合、モジュールでは既定のコンテンツオプションとして「フォームを選択」を使用する必要があります。
- ブログ セレクター フィールドを含める場合、モジュールでは既定のコンテンツオプションとして「ブログを選択」を使用する必要があります。
- モジュールに既定のコンテンツを追加する必要がない場合は、代わりにモジュールプレースホルダーを使用して、コンテンツクリエイターがコンテンツを配置するスペースを視覚的に把握できるようにしてください。
モジュールには、モジュールに割り当てられたカスタムアイコン（既定のアイコンの代わりとなるもの）を含める必要があります。会社のロゴ（AppleやAmazonのロゴなど）をアイコンとして使用しないでください。詳しくはモジュールアイコンの追加方法をご確認ください。
- テーマ内のモジュール：
- テーマ内のモジュールと独立モジュールの両方：
- モジュールフィールド名は、フィールドの目的を説明するものでなければなりません。例えば、役職名の入力用にテキストフィールドが作成されている場合、「役職」は説明として適切ですが、「名称」は不適切です。
- 提出される全てのテンプレートで、HubSpotの全ての既定のモジュールが適切にスタイル設定され表示される必要があります。
テーマと独立モジュールの間の機能互換性を確保するには、モジュールが色フィールドとフォントフィールドを継承する必要があります。そのためには、fields.jsonファイル内でdefault_value_path、property_value_pathsのどちらかまたは両方を定義します。また、module.htmlファイル内でテーマフィールドへの参照を追加します。これらの要件について詳しくご確認ください。
テーマモジュールに必要なすべてのファイル（CSSやJavaScriptなど）がテーマフォルダーに格納されてテーマディレクトリーに入っている必要があります。デザインマネージャーで、リンク済みファイル機能を使用できます。あるいは、require_js()またはrequire_css()関数でファイルへの相対パスを使ってファイルを含めます。
slick.jsなどの一般的なライブラリーの場合、require_js()またはrequire_css()関数で、ホスト場所となっているCDNへの絶対URLを使ってこれらを含めることができます。
独立したモジュールの場合、すべてのCSSおよびJavascriptファイルがmodule.cssまたはmodule.jsに含まれている必要があります。あるいは、require_js()またはrequire_css()関数で、ホスト場所となっているCDNへの絶対URLを使ってファイルを含めます。リンク済みファイル機能をデザインマネージャーで使用することはできません（テーマモジュールでのみ使用可能です）。
module.jsはDOM内でrequire_jsまたはrequire_cssファイルの前に含まれるので、以下のアノテーションを使用して、module.jsセクションに含まれるJavascriptを遅延させる必要があります。
document.addEventListener("DOMContentLoaded", function(){
// Put Javascript here
});すべてのスクリプトとファイルは、モジュールのHTMLの先頭でレンダリングされる必要があります。
以下の制限は、独立したモジュールにのみ当てはまります。
- 可能であれば簡素なJSを使用することをお勧めします。jQueryを使用しないサイトにjQueryライブラリーを追加すると、競合が発生してウェブサイトページの速度が低下する可能性があります。
- jQueryライブラリーを使用する場合は、イベントにそのライブラリーを含める際にrequire_js()関数を使用してください。これにより、ポータル設定のチェックボックス（ブール値）でjQueryが無効になっているイベントでの、複数のjQueryライブラリーによる競合を回避できます。
- すべての独立モジュールには、少なくとも1つのカテゴリーが必要です。テーマの一部分として提出されるモジュールではカテゴリーが必須ではありませんが、ベストプラクティスとして少なくとも1つを含めることをお勧めします。モジュールにカテゴリーを追加する方法についてご確認ください。
- クラス名セレクターの前にモジュール名の接頭辞を付ける必要があり、その際にはスペースをハイフンに置き換えます。例えば、以下に示すのは
example-buttonというボタン用のmodule.htmlファイルで、それぞれのクラス名とCSSセレクターがその名前を反映しています。
- スタイル：
- モジュールには空でないスタイルグループが含まれる必要があります。
- モジュール内でインラインスタイルをハードコーディングすることは推奨されません。代わりに、フィールドでスタイルを制御できるようにして、動的インラインスタイルを使用してください。
- JavaScript：
- JavaScriptは、モジュールの複数インスタンスを表すことができる必要があります。JSペインのJavaScriptは、モジュールの使用回数にかかわらず、1ページにつき一度だけ読み込まれます。
- JavaScriptはモジュール固有のクラス名を使ってDOM要素を参照する必要があります。これにより、モジュール外部の要素に意図しない影響が及ぶのを防げます。JavaScript：
APAC JAPAN (JA) | Dev. Page | Asset Marketplace | Module requirements | 202304という組み込み変数を使用できます。この変数は、複雑なモジュールのCSSとJSマークアップで役立つ、モジュールのインスタンスID（HTML+HubLパネルでのみ使用可能）を取得します。詳しくは開発者ドキュメントをご覧ください。以下のフィールドの構成とグループ化の要件を満たす必要があります。
コンテンツタブ
- フィールドグループ内に少なくとも1つの制御設定がある場合は、全ての制御設定を、その機能によってラベル付けされたカテゴリーにグループ化する必要があります。
- ［コンテンツ］タブに追加されたモジュールフィールドは、モジュールのコンテンツをカスタマイズする方法を提供する必要があります。例えば、画像、アイコン、altテキストの制御設定や、リンクの制御設定などです。
スタイルタブ
モジュールのスタイル フィールド グループは一貫性を持ち、パターンに従う必要があります。以下は、スタイル フィールド グループの推奨される順序です。これらのグループは、トップレベルに配置することも、1つのグループにネストすることもできます。また、空のグループは削除できます。- プリセット
- テキスト
- 背景
- 境界線
- マウスオーバー
- 角
- 間隔
- 位置合わせ
- 上記以外のカスタム スタイル グループ
- 詳細
次のフィールドタイプが存在する場合は、［スタイル］タブに含める必要があります。
- アニメーションオプションは、常にフィールド グループ リストの末尾近くに置く必要があります。
- コンテンツクリエイターがコードスニペットまたはCSSを追加できるようにするオプションは、フィールド グループ リストの末尾にある「詳細」というラベルのフィールドにグループ化する必要があります。
- コントロールは、全てのモジュールで標準化する必要があります。例えば、境界線の半径のコントロールを持つことができる全ての要素は、そのコントロールを提供する必要があります。一部のモジュールで、他のモジュールに存在しないコントロールを提供することは避けてください。
- ［スタイル］タブに追加されたモジュールフィールドは、モジュールのスタイルを設定する方法を提供する必要があります。例として、以下のような場合が挙げられます。
- 色、テキストスタイル、位置合わせ、間隔、境界線、角の半径などのスタイルオプション。
- ホバー効果やスライドイン効果などのアニメーション。
- さまざまなスタイルを同時に変更することを目的とする、ダークテーマとライトテーマなどのプリセット。
フィールドの構成の例
プリセット
プリセットは、限られたオプションのセットをコンテンツクリエイターに提供したい場合に使用でき、通常テーマ設定に紐付けられています。例えば、Growthテーマに含まれている「Icon（アイコン）」モジュールには「ダーク」カラーと「ライト」カラーのプリセットが含まれており、ウェブサイト全体で使用すると一貫性を提供できます。
複数レベルのグループ化
スタイルフィールドをトップレベルに配置するかネストするかを決定する際には、次の例を考慮してください。
Growthテーマに含まれている「Icon（アイコン）」モジュールは、単一のコンポーネントであるため、全てのスタイルオプションがトップレベルに配置されます。したがって、全てのスタイルオプションがこの1つのコンポーネントに影響します。
Growthテーマに含まれている「スピーカーカード」モジュールには、カードの画像とテキストコンテンツという複数のコンポーネントが含まれています。したがって、モジュールスタイルはコンポーネントごとにグループ化されており、コンテンツクリエイターが各コンポーネントのスタイルを設定するためのプロセスが明確化されます。
個々のフィールドのグループ化
以下のボタンモジュールには、［プリセット］、［テキスト］、［背景］などのグループが含まれています。［角］フィールドグループには角の半径のコントロールしか含まれていませんが、一貫性のあるコンテンツ作成体験を提供するためにグループ化されています。
エイリアスマッピングを使用すると、モジュール内にフィールドマッピングを作成して、モジュールを使用しているページに影響を及ぼすことなく、そのフィールドの移動、名前変更、置換を行うことができます。
例えば、ライブページでモジュールが使用されているとします。色やフォントなどの一部のフィールドを［スタイル］タブに移動したいのですが、コンテンツ作成者がエディターでそれらのフィールドの値をすでに選択しています。エイリアスマッピングを設定せずにそれらのフィールドを移動した場合、HubSpotはそれらのフィールドを再配置できず、既定値に戻ります。そのため、ライブページのスタイルは元に戻されます。
代わりに、aliases_mappingプロパティーをフィールドに追加して、別のフィールドにマッピングすることができます。次に、元のフィールドに値が設定されていない場合、HubSpotはマッピングされたフィールドに値が存在するかどうかを確認します。マッピングされたフィールドに値が存在しない場合は、代わりに既定値が使用されます。このプロパティーは、元のフィールドの格納済みのデータ型が新しいフィールドの格納済みのデータ型と同じである場合にのみ、モジュールの異なるバージョン間でフィールド値をマッピングするために使用できます。
この機能の視覚的な解説については、以下の動画をご覧ください。
既存のフィールドをエイリアスに移行する手順は、以下のとおりです。
- 新しいフィールドを作成し、
aliases_mappingプロパティーを使用して古いフィールドにマッピングします。 - 古いフィールド定義を削除します。
- 新しいフィールド定義を使用するように、
module.htmlファイルを更新します。
注：
- データ型が異なるフィールドを相互にマッピングすることはできません。例えば、背景グラデーションフィールドを画像フィールドにマッピングすることはできません。格納される値は、新しいフィールドのタイプで有効な値でなければなりません。
- 元のフィールドへのエイリアスがマッピングされた新しいフィールドを作成する場合、両方のフィールドの既定値と必須プロパティーが同一でなければなりません。
単純な実装の場合は、元のフィールドのフィールドタイプと新しいフィールドのフィールドタイプが同一でなければなりません。例として、以下のような場合が挙げられます。
- 元の色フィールドから新しい色フィールド。
- 元のテキストフィールドから新しいテキストフィールド。
- 元の間隔フィールドから新しい間隔フィールド。
モジュールの［コンテンツ］タブから［スタイル］に色フィールドを移動する場合にaliases_mappingを使用する例を以下に示します。
Example of a v0 module
Example of a v1 module
Complex implementation
より複雑な実装の場合は、データ型が同一で、新しいフィールドのサブフィールドタイプが一致していれば、フィールドをサブフィールドまたは他のモジュールのフィールドタイプにマッピングすることもできます。サブフィールドは、フィールドの格納済みの値オブジェクト内のプロパティーです。例として、以下のような場合が挙げられます。
- 「リッチテキスト」フィールドと「テキスト」フィールドの値は両方とも文字列として格納されるため、前者を後者にマッピングします。
- フォントサイズの数値フィールドを（フォント サイズ サブフィールドを持つ）フォントフィールドに変更するなど、タイポグラフィーフィールドを統合します。
sizeサブフィールドのエイリアスを追加し、ドット表記を使用して元の数値フィールドにマッピングできます。
フォント サイズ オプションを数値フィールドからフォント サイズ サブフィールドを持つフォントフィールドに変更する例を以下に示します。
Example of a v0 module
Example of a v1 module
貴重なご意見をありがとうございました。