HubL構文

HubSpotのCMSでは、HubSpot Markup Language、略してHubL(発音は「ハブル」)を使用します。HubLは、JinjavaというJinjaベースのテンプレートエンジンをHubSpotが拡張した言語です。HubLは数多くのHubSpot固有のマークアップを採用しています。また、Jinjaの機能のうちサポートされない機能もあります。

この記事では、HubLの機能と構文の基本について説明します。ここでは概要のみを紹介し、HubLのさまざまな機能の詳細については、以降のリファレンス記事で説明します。

区切り文字のタイプ

HubLは、広く利用されている他のテンプレート言語(PHPなど)と同様に、コード テンプレート ファイル、つまりHubLテンプレートモジュール内でHTMLに組み込むことができます。HubLの開始位置と終了位置を示す区切り文字として機能する主な記号を理解しておいてください。

HubL
{% %} - statement delimiters
{{ }} - expression delimiters
{# #} - comment delimiters

HubL文は、編集可能なモジュールの作成、条件付きテンプレートロジックの定義、forループの構成、変数の定義などに使用します。文は{%で区切ります。

式は、テンプレートのコンテキストに格納されている値を出力します。式は{{で区切ります。例えば、変数は文として定義する必要がありますが、変数を出力するにはHubL式を使用します。

式の文

「do」タグは、何も出力しない点を除いて、標準の変数式{{ ... }}と同様に機能します。これはリストやディクショナリーの変更に使用します。

注:配列への追加には.append()を使用し、オブジェクトへの追加には.update()を使用します。

# 配列
{% set navigation = ['Home', 'About'] %}
{% do navigation.append('Contact Us') %}
{{navigation}}

# オブジェクト 
{% set book = {'name' : 'Rocking HubL', 'author' : 'John Smith' }%}
{% do book.update({'ebook' : 'yes'}) %}
{{book}}

コメント

最後に紹介する区切り文字は、HubLコメントです。HubLでの開発時に見かけるだけでなく、実際に使用する機会もあるはずです。コメントは、{#のように定義します。

モジュール

モジュールは、エンドユーザーがコンテンツエディター上でカスタマイズできるテンプレート内の動的な領域です。例えば、テンプレートファイルをゼロからコーディングする場合に、HubLタグを使用してモジュールをテンプレートに追加することにより、制作担当者がページの特定の領域を編集できるようになります。

モジュールタグは以下の要素で構成されます。

  • モジュールのタイプ - レンダリングするモジュールを指定します。使用可能な各種モジュールタイプの一覧については、HubLでサポートされているタグのページを参照してください。
  • モジュールの一意の名前 - テンプレートのコンテキスト内で重複しないIDをモジュールに指定します。
  • パス(タグによって異なります) - デザインマネージャーでのモジュールの位置を定義します。HubSpotの既定モジュールのパスは常に@hubspot/で始まり、その後にモジュールのタイプが続きます。詳しくは、以下の例とテンプレートページでのモジュールの使用のページを参照してください。 
  • パラメーター(任意) - 追加のモジュール情報を指定します。
{% module "unique_module_name",
  path="@hubspot/text",
  label="Single Text Line",
  value="This is a single text line" 
%}

上記の例は、labelパラメーターとvalueパラメーターが指定されたテキストモジュールを示しています。labelはエディターのヘルプテキストを定義し、valueはそのモジュールの既定のテキストを設定します。エディター内でどのように表示されるかについては、以下のサンプルgifを参照してください。

module-label-value-min

変数とマクロ

HubLには、アプリから有用な値を出力する定義済みのHubSpot変数が数多く用意されています。また、テンプレートで独自の変数を定義することもできます。以下の例では、primaryColorという変数を文で定義し、HubL式により出力しています。この例では、HubL変数とCSSを組み合わせています。

{% set primaryColor = '#F7761F' %} {# 変数を定義し、16進数の色を代入 #}
        
a {
  color: {{ primaryColor }}; {# 16進数の変数値を出力 #}
}

HubLマクロでは、動的な値を使用して複数の文を出力できます。この手法は、同様の基本的なコードを繰り返し記述するものの、特定の値だけは変更する場合に役立ちます。以下の例では、マクロを使用して、すべてのベンダープレフィックスが含まれるCSS3 transitionプロパティーを出力しています。マクロについて詳しくは、こちらをご覧ください

{% macro trans(value) %} 
-webkit-transition: {{value}};
-moz-transition: {{value}};
-o-transition: {{value}};
-ms-transition: {{value}};
transition: {{value}};
{% endmacro %}
 

a {
  {{ trans('all .2s ease-in-out') }}
}

フィルターと関数

HubLにフィルターを追加することで、テンプレート変数の値を変換または変更できます。日付変数の書式を設定するシンプルな例を以下に示します。フィルターでは|(パイプライン記号)を使用し、スペースなしで変数に適用します。

以下の例では、ブログ記事が4月29日に公開されたことを想定しています。記事の公開日の書式が、datetimeformatフィルターにより設定されます。すべてのフィルターの一覧については、こちらを参照してください

{{ content.publish_date_local_time|datetimeformat('%B %e, %Y') }} 

フィルターの効果は変数のレンダリングですが、関数では値とアカウント情報を処理し、その情報をレンダリングできます。例えば、特定のブログの合計記事数を取得する場合や、色変数を特定の量だけ明るくするか暗くする場合には、関数を使用します。

この例では、designers.hubspot.com/blogのブログ記事の合計数が出力されます。(ブログダッシュボードのURLに含まれる)ブログIDパラメーターを使用して、ターゲットにするブログを指定します。すべての関数の一覧については、こちらを参照してください

// blog_total_post_count
{{ blog_total_post_count(359485112) }}

if文

if文では、条件ロジックを使用して、ifelifelseendifのHubL文の条件ロジックがテンプレートによってどのようにレンダリングされるかを指示できます。if文は、ifで始まりendifで終わります。

以下の例では、エンドユーザーがドロップダウンから部門を選択できるchoiceモジュールを定義しています。ユーザーがエディターで選択した内容に基づいて、テンプレート上で採用情報ページの見出しが動的に作成されます。この例では、export_to_template_contextパラメーターを使用する必要があります。

HubL
{% choice "department" label='Choose department', value='Marketing', choices='Marketing, Sales, Dev, Services' export_to_template_context=True %}
        
{% if widget_data.department.value == 'Marketing' %}

<h3>Want to join our amazing Marketing team?!</h3>
<h4>We have exciting career opportunities on the {{ widget_data.department.value }} team.</h4>

{% elif widget_data.department.value == 'Sales' %}

<h3>Are you a Sales superstar?</h3>
<h4>We have exciting career opportunities on the {{ widget_data.department.value }} team.</h4>        
        
{% elif widget_data.department.value == 'Dev' %}
        
<h3>Do you love to ship code?</h3>
<h4>We have exciting career opportunities on the {{ widget_data.department.value }} team.</h4>
        
{% else %}
        
<h3>Want to work with our awesome customers?</h3>
<h4>We have exciting career opportunities on the {{ widget_data.department.value }} team.</h4>
        
{% endif %}

forループ

forループを使用すると、シーケンスとして格納されている項目に対し、繰り返し処理を行うことができます。主に、ブログコンテンツをリスト形式でレンダリングする場合に使用されます。forループは、for文で始まりendfor文で終わります。

以下の例では、熊の種類の配列を変数「bears」に格納しています。次に、forループを使用してさまざまな熊の種類を順に処理し、種類ごとにリスト項目として出力しています。 

{% set bears = ['panda bear', 'polar bear', 'black bear', 'grizzly bear', 'koala bear'] %}

<h1>Types of bears</h1>
<ul>
  {% for bear in bears %}
  <li>{{ bear }}</li>
  {% endfor %}
</ul>

その他のHubL機能

HubLでの開発に役立つその他のテンプレート機能を以下で説明します。

HubL区切り文字のエスケープ

HubLと同じ区切り文字を使用する言語は他にも多数存在しています。このことが原因で、CMSでコードファイルを処理する際に問題が生じることがあります。別の言語でHubLの区切り文字を使用する場合は、その言語のコードを次のように囲む必要があります。

{% raw %} {{"Code you want to escape"}} {% endraw %}

ファイルに別のファイルをインクルードする

includeタグを使用することで、複数の.htmlファイルを1つのHubLテンプレートにインクルードできます。標準テンプレート変数を必要としないHTMLファイルを作成するには、[このテンプレートを新しいコンテンツで利用できるようにする]オプションをオフにする必要があります。以下に構文を示します。

HubL
{% include "custom/page/web_page_basic/my_footer.html" %}
{% include "hubspot/styles/patches/recommended.css" %}

また、同じincludeタグを使用して、複数のCSSファイルを1つのCSSファイルにコンパイルすることもできます。親ファイルを公開すると、親のコードによって子ファイルが1つの縮小CSSファイルとしてコンパイルされます。

ブロックと拡張

複雑なテンプレートの作成に使用できる高度な手法として、親テンプレートを拡張する区画のブロックを作成する方法があります。必須のstandard_header_includes変数とstandard_footer_includes変数を含む親テンプレートを作成します。このテンプレート内で、以下の構文を使用して一意のブロックを定義する必要があります。このmy_sidebarは重複しない名前にします。

HubL
{% extends "custom/page/web_page_basic/my_template.html" %}
{% block my_sidebar %}
<h3>Sidebar title</h3>
<ul>
  <li>Bullet 1<li>
  <li>Bullet 2<li>
  <li>Bullet 3<li>
</ul>
{% endblock %}

次に、そのブロックにデータを提供する子HTMLファイルを作成します。まず、親のパスを参照するextends文を宣言する必要があります。このコードブロックは親テンプレートでレンダリングされますが、対応が容易な小さいファイルとして管理できます。この手法はすべてのユーザー向けではありませんが、複雑なEメールテンプレートやページテンプレートをコーディングする際の整理に役立ちます。この手法を使用する場合、コンテンツの作成時に子テンプレートを選択する必要があります。


参考になりましたか? *
こちらのフォームには開発者向けドキュメントに関するご意見をお聞かせください。なお、HubSpot製品に関するご意見は、アイデアフォーラム(英語)にお寄せください。