HubL（HubSpot Markup Language）基礎

HubL とは何か

HubL（ハブエル）は、HubSpotが独自に設計したテンプレートエンジンです。 PythonのJinja2をベースに、HubSpot専用の変数・フィルター・タグが追加されています。 HTMLファイルの中に HubL を埋め込んで書き、サーバーサイドで処理されて最終的にHTMLとして出力されます。

基本構文：3つのデリミタ

HubLには用途の異なる3種類の記法があります。これがHubLの基本単位です。

{# ====== ① 出力タグ {{ }} ====== #}
{# 変数の値をHTMLに出力する #}
<h1>{{ content.name }}</h1>
<p>{{ content.meta_description }}</p>

{# フィルターを使って加工して出力 #}
<p>{{ content.publish_date|datetimeformat("%Y年%m月%d日") }}</p>

{# ====== ② ステートメントタグ {% %} ====== #}
{# 変数に値をセット（出力なし） #}
{% set site_name = "株式会社サンプル" %}

{# 条件分岐（出力なし） #}
{% if content.featured_image %}
  <img src="{{ content.featured_image }}" alt="{{ content.featured_image_alt_text }}">
{% endif %}

{# ====== ③ コメント {# #} ====== #}
{# このコメントはHTMLソースにも表示されない #}
{# TODO: モバイル対応を追加する #}

変数・set・データ型

変数の定義（set）

{% set %} タグで変数を定義します。一度定義した変数はそのテンプレート内で再利用できます。

{# 文字列 #}
{% set company_name = "株式会社サンプル" %}

{# 数値 #}
{% set max_posts = 6 %}

{# 真偽値 #}
{% set is_published = true %}

{# リスト（配列） #}
{% set nav_items = ["ホーム", "サービス", "会社概要", "お問い合わせ"] %}

{# 辞書（dict）— キーと値のペア #}
{% set form_ids = {
  "contact"  : "xxxx-xxxx-contact",
  "seminar"  : "xxxx-xxxx-seminar",
  "download" : "xxxx-xxxx-download"
} %}

{# 辞書からの値取得 #}
{{ form_ids["seminar"] }}
{{ form_ids.contact }}     {# ドット記法でもアクセス可 #}

変数の更新（namespace パターン）

HubLではループ内で外側のスコープの変数を直接書き換えることができません。 namespace を使うことで、ループ内から外側の変数を更新できます。 これは実務でよく使うパターンです。

{# 通常の set はループ内で外側の変数を更新できない（NG） #}
{% set content_type = "blog" %}
{% for tag in content.tag_list %}
  {% set content_type = tag.slug %}  {# ← これはループ内でしか有効にならない！ #}
{% endfor %}

{# ✅ namespace を使った正しいパターン #}
{% set ns = namespace(content_type="blog") %}
{% for tag in content.tag_list %}
  {% if tag.slug starts_with "type:" %}
    {% set ns.content_type = tag.slug|replace("type:", "") %}
  {% endif %}
{% endfor %}

{# ループ後に正しい値が取れる #}
<div class="post-type-{{ ns.content_type }}">...</div>

制御構文：if / for / unless

① 条件分岐（if / elif / else / endif）

{# 基本的な if #}
{% if content.featured_image %}
  <img src="{{ content.featured_image }}" alt="{{ content.featured_image_alt_text }}">
{% endif %}

{# if / elif / else #}
{% if content_type == "seminar" %}
  <span class="badge badge-seminar">セミナー</span>
{% elif content_type == "news" %}
  <span class="badge badge-news">お知らせ</span>
{% elif content_type == "case" %}
  <span class="badge badge-case">事例</span>
{% else %}
  <span class="badge badge-blog">ブログ</span>
{% endif %}

{# not / and / or を使った複合条件 #}
{% if content.featured_image and content.featured_image_alt_text %}
  {# 画像とalt両方ある時だけ表示 #}
{% endif %}

{% if not content.archived %}
  {# アーカイブされていない記事だけ表示 #}
{% endif %}

よく使う比較演算子・テスト演算子

② ループ（for / endfor）

{# リストのループ #}
{% set nav_items = [
  {"label": "ホーム",     "url": "/"},
  {"label": "サービス", "url": "/service"},
  {"label": "会社概要", "url": "/about"}
] %}

<ul>
{% for item in nav_items %}
  <li><a href="{{ item.url }}">{{ item.label }}</a></li>
{% endfor %}
</ul>

{# loop変数（ループ内で使える特殊変数） #}
{% for post in posts %}
  {% if loop.first %}<div class="first-item">{% endif %}

  <article class="post-item post-{{ loop.index }}">
    <h2>{{ post.name }}</h2>
  </article>

  {% if loop.last %}</div>{% endif %}
{% endfor %}

{# range() で数値ループ #}
{% for i in range(1, 6) %}
  <span>{{ i }}</span>   {# 1, 2, 3, 4, 5 #}
{% endfor %}

{# else 節：リストが空の場合 #}
{% for post in posts %}
  <article>...</article>
{% else %}
  <p>記事がありません</p>
{% endfor %}

loop 変数 一覧

③ unless（ifの否定版）

{# unless は「〜でない場合」。not を使った if と同義 #}
{% unless content.archived %}
  <div class="post-content">...</div>
{% endunless %}

{# 上記は以下と同じ #}
{% if not content.archived %}
  <div class="post-content">...</div>
{% endif %}

マクロ（macro）の定義と再利用

マクロは、繰り返し使うHTMLのパターンを関数として定義する仕組みです。 引数を渡せるため、「見た目は同じだが内容が違う」部品を効率よく管理できます。

{# ====== マクロの定義 ====== #}

{# カードコンポーネントのマクロ #}
{% macro render_card(title, description, url, badge="", image="") %}
  <div class="card">
    {% if image %}
      <img src="{{ image }}" alt="{{ title }}">
    {% endif %}
    {% if badge %}
      <span class="badge">{{ badge }}</span>
    {% endif %}
    <h3><a href="{{ url }}">{{ title }}</a></h3>
    <p>{{ description|truncate(80) }}</p>
  </div>
{% endmacro %}

{# ====== マクロの呼び出し ====== #}

{# 基本的な呼び出し #}
{{ render_card(
  title="HubSpotで成果を出す方法",
  description="HubSpotを使ったマーケティング施策の具体的な手法を解説します。",
  url="/blog/hubspot-tips"
) }}

{# バッジ・画像ありの呼び出し #}
{{ render_card(
  title="【セミナー】HubSpot活用術",
  description="2024年最新のHubSpot活用事例を紹介するオンラインセミナーです。",
  url="/blog/seminar-2024",
  badge="セミナー",
  image="https://example.com/seminar.jpg"
) }}

{# ブログ一覧でループと組み合わせる #}
{% set posts = blog_recent_posts("default", 6) %}
{% for post in posts %}
  {{ render_card(
    title=post.name,
    description=post.meta_description,
    url=post.absolute_url,
    image=post.featured_image
  ) }}
{% endfor %}

マクロをファイル分割して import する

マクロが増えてきたら、専用の部品ファイルにまとめて import または from … import で読み込めます。

{% macro render_card(title, description, url, badge="") %}
  ...
{% endmacro %}

{% macro render_badge(label, type="default") %}
  <span class="badge badge--{{ type }}">{{ label }}</span>
{% endmacro %}

{# ファイル全体をインポートして使う #}
{% from "../partials/macros.html" import render_card, render_badge %}

{% set posts = blog_recent_posts("default", 9) %}
{% for post in posts %}
  {{ render_card(post.name, post.meta_description, post.absolute_url) }}
{% endfor %}

組み込み変数一覧

HubSpot CMSのテンプレートでは、特定のコンテキストで使える組み込み変数が多数用意されています。スコープ（使える場所）に注意してください。

content — コンテンツ情報（最重要）

現在表示しているページ・記事・メールなどの情報を持つオブジェクトです。テンプレート全体で使える最も頻用する変数です。

request — リクエスト情報

よく使うその他の変数

フィルター完全ガイド

フィルターは変数の値を加工・変換するための仕組みです。 {{ 変数|フィルター名 }} の形で使い、|（パイプ）でつないで複数のフィルターをチェーンできます。

{# 単一フィルター #}
{{ content.name|upper }}

{# 引数ありフィルター #}
{{ content.meta_description|truncate(100) }}

{# チェーン（複数フィルターを連結） #}
{{ content.name|truncate(30)|upper }}

文字列操作フィルター

日時フィルター

数値・リストフィルター

ブログ専用 HubL 関数一覧

ブログ機能を実装する上で必須の HubL 関数を整理します。これらはブログ関連テンプレートで最も頻繁に使う関数群です。

記事取得関数

{# 最新記事 6件取得 #}
{% set recent_posts = blog_recent_posts("default", 6) %}

{# タグ指定で記事取得（セミナー記事のみ） #}
{% set seminar_posts = blog_posts("default", 3, 0, "seminar") %}

{# offset を使ったページネーション（2ページ目：11〜20件目）#}
{% set page2_posts = blog_posts("default", 10, 10) %}

{# 人気記事 5件 #}
{% set popular = blog_popular_posts("default", 5) %}

{# 記事の総件数 #}
{% set total = blog_total_post_count("default") %}
<p>全{{ total }}件の記事</p>

URL・リンク生成関数

{# タグアーカイブURLを生成 #}
<a href="{{ blog_tag_url("default", "seminar") }}">セミナー一覧へ</a>
{# 出力例: /blog/tag/seminar #}

{# ナビゲーションでタグ一覧リンクを動的生成 #}
{% set tag_nav = [
  {"label": "ブログ",         "slug": "blog"},
  {"label": "セミナー",       "slug": "seminar"},
  {"label": "お知らせ",       "slug": "news"},
  {"label": "導入事例",       "slug": "case"}
] %}

<nav class="blog-nav">
  <a href="/blog">すべて</a>
  {% for tag in tag_nav %}
    <a href="{{ blog_tag_url("default", tag.slug) }}"
       {% if content.tag.slug == tag.slug %}
         class="is-active" aria-current="page"
       {% endif %}>
      {{ tag.label }}
    </a>
  {% endfor %}
</nav>

{# ページネーションURLを生成 #}
<a href="{{ blog_page_link(current_page_num + 1) }}">次へ</a>

記事オブジェクトの主なプロパティ

blog_recent_posts() などで取得した記事オブジェクトで使えるプロパティ一覧です。

HubL と JavaScript の使い分け

HubLとJavaScriptはどちらもHubSpotテンプレートで使いますが、役割が明確に異なります。両者の違いを正しく理解することで、適切な実装を選択できます。

{# HubL でサーバーサイドのデータをJS変数として渡す #}
{# → JSからHubSpotのデータを使いたい場合に使うパターン #}

<script>
  // HubLの変数をJSに渡す
  const hubspotConfig = {
    portalId  : {{ hub_id }},
    pageId    : {{ content.id }},
    pageTitle : "{{ content.name|escape }}",
    contentType: "{{ ns.content_type }}",
    formIds   : {
      seminar  : "{{ form_ids.seminar }}",
      download : "{{ form_ids.download }}"
    }
  };

  // この後はJSとして処理できる
  console.log(hubspotConfig.pageTitle);

  // コンテンツ種別によってフォームを動的に切り替え
  hbspt.forms.create({
    portalId : hubspotConfig.portalId,
    formId   : hubspotConfig.formIds[hubspotConfig.contentType]
               || hubspotConfig.formIds.download,
    target   : '#hs-form-area'
  });
</script>

第2章まとめ