Handlebarsの使用

Twilio SendGridの動的トランザクションテンプレートとMarketing Campaignsデザインでは、APIにより送信するパーソナライゼーションと、Marketing Campaignsのコンタクトに保存される置換タグのレンダリングで、Handlebarsテンプレート言語がサポートされています。

Handlebarsの構文を使用すると、テンプレートのメッセージに顧客の名前などのデータを挿入してパーソナライズし、それぞれの受信者に適した内容のメールを送ることができます。例えば、"name"'というJSONプロパティに顧客の名前を保存している場合、顧客の名前を表示したい場所に}`を追加すると、このプロパティの値をテンプレートに挿入できます。

Handlebarsの構文を使用すると、コードベースとは独立してすべての動的なテンプレート処理が実行されます。そのため、コードベースを更新することなく、テンプレートを迅速に変更できます。

独自のテンプレートシステムを使用したい場合は、置換タグを使用して動的にデータを挿入できます。

Handlebarsを使用したメールのパーソナライズ

動的トランザクションテンプレートAPIを使用して、テンプレートをプログラムで管理することができます。

Handlebars言語は、基本的な変数の置換以外にも、反復(ループ)や条件文などの多くの機能を備えています。テンプレートやデザインではHandlebarsのほとんどの機能をサポートしていますが、一部サポートされていない機能もあります。現在、動的テンプレートでは以下のヘルパーがサポートされています。

置換
条件文
反復

すべてのヘルパーの詳細については、このページのHandlebarsリファレンスを参照してください。

ユースケース

以下のユースケース例は、メールテンプレートのGitHubリポジトリの動的テンプレートのセクションに用意されているものです。それぞれの例にはファイルへのリンクが示されており、GitHubで確認できます。これらのテンプレートは、動的トランザクションテンプレートとMarketing Campaignsデザインライブラリーにあるコードエディタを利用してアップロードし、使用することもできます。

以下に、それぞれのユースケースと、作成に使用されているHandlebarsヘルパーを示します。

領収書

この領収書サンプルテンプレートでは、以下のヘルパーを使用しています。

置換
条件文
反復

パスワードのリセット

このトランザクションサンプルテンプレートでは、以下のヘルパーを使用しています。

置換

複数言語

この複数言語でコンテンツを記述できるサンプルテンプレートでは、以下のヘルパーを使用しています。

-条件文-if/else

ニュースレター

このニュースレターサンプルテンプレートでは、以下のヘルパーを使用しています。

置換
反復

以下のリファレンスでは、HTMLメールのスニペットとJSONテストデータを含む、各ヘルパーのサンプルコードブロックを示しています。コード例は、3つのタブに分かれています。1つ目のHandlebarsのタブでは、Handlebarsのタグを示しています。2つ目のJSONのタブでは、Handlebarsタグへの入力に使用されるサンプルデータを示しています。3つ目のHTMLのタブでは、メールでHandlebarsタグがレンダリングされた最終的な出力を示しています。それぞれのタブをクリックし、コードサンプルを切り替えることができます。

置換

Twilio SendGridテンプレートでは、以下の置換をサポートします。

基本的な置換
Dynamic linkの値
ディープオブジェクトの置換
オブジェクトがない場合
HTMLでの置換
formatDate
挿入

基本的な置換

<!--テンプレート-->
<p>Hello {{ firstName }}</p>

//テストデータ
{ "firstName": "Ben" }

<!-- Resulting HTML !-->
<p>Hello Ben</p>

動的リンク値

<!--テンプレート -->
<p><a href="{{ url }}">Click Me</a></p>

//テストデータ
{ "url": "https://example.com/shop" }

<!--Resulting HTML !-->
<p><a href="https://example.com/shop">Click Me</a></p>

ディープオブジェクトの置換

<!--テンプレート-->
<p>Hello {{user.profile.firstName}}</p>

//テストデータ
{
  "user": {
    "profile": {
      "firstName": "Ben"
    }
  }
}

<!--結果のHTML-->
<p>Hello Ben</p>

オブジェクトがない場合

<!--テンプレート-->
<p>Hello {{user.profile.firstName}}</p>

//テストデータ
{
  "user": {
    "orderHistory": [
      {
        "date": "2/1/2018",
        "item": "shoes"
      },
      {
        "date": "1/4/2017",
        "item": "hat"
      }
    ]
  }
}

<!--結果のHTML-->
<p>Hello</p>

HTMLでの置換

件名行の置換で、'、"または&の文字が含まれている場合は、以下のように3つの波括弧を使用します。

<!--テンプレート -->
<!-- Handlebarsのドキュメントより: Handlebarsで値をエスケープしたくない場合は、"3重の中括弧"({{{)を使用します-->
<p>Hello {{{firstName}}}</p>

//テストデータ
{ "firstName": "<strong>Ben</strong>" }

<!--結果のHTML-->
<p>Hello <strong>Ben</strong></p>

formatDate

formatDateヘルパーは、エポックかISO8601の形式の日時を受け取り、以下の表に示すトークンを使用して指定した書式に変換します。変換せずに日付フィールドを送信すると、完全なタイムスタンプ付きのISO8601形式で表示されます(例: 2020-01-01T23:00:00.000Z)。以下の例は、太平洋標準時の2020年1月1日(火)午後3時の表示結果です。

トークン	表示結果
YYYY	2020
YY	20
MMMM	January
MMM	Jan
MM	01
M	1
DD	01
D	1
dddd	Tuesday
ddd	Tue
hh	03
h	3
HH	00
H	00
mm	00
m	0
ss	00
s	0
A	PM
ZZ	-0800
Z	-08:00

<!--タイムゾーンオフセットがないテンプレート-->
<p>Join us {{formatDate timeStamp dateFormat}}</p>

<!-- タイムゾーンオフセットを含むテンプレート-->
<p>Join us {{formatDate timeStamp dateFormat timezoneOffset}}</p>

//テストデータ
{
  "timeStamp": "2020-01-01T23:00:00.000Z",
  "dateFormat": "MMMM DD, YYYY h:mm:ss A",
  "timezoneOffset": "-0800"
}

<!--タイムゾーンがない結果のHTML-->
<p>Join us January 01, 2020 11:00:00 PM</p>

<!-- タイムゾーンを含む結果のHTML-->
<p>Join us January 01, 2020 3:00:00 PM</p>

Insert

<!--デフォルト値を挿入-->
<p>Hello {{insert name "default=Customer"}}! Thank you for contacting us about {{insert businessName "your business"}}.</p>

//すべての値が設定されているテストデータ
{
   "name": "Ben",
   "businessName": "Twilio SendGrid"
}

// 値がないテストデータ
{
  "name": "Ben"
}

<!--すべての値を含む結果のHTML-->
<p>Hello Ben! Thank you for contacting us about Twilio SendGrid.</p>

<!-- 値がなく、デフォルト値が設定された結果のHTML-->
<p>Hello Ben! Thank you for contacting us about your business.</p>

条件文

Twilio SendGridテンプレートでは、以下の条件文をサポートします。

基本的なif、else、else if
rootを使用したif
unless
greaterThan(~より大きい)
lessThan(~より小さい)
equals(等しい)
notEquals(等しくない)
and(かつ)
or(または)
length(長さ)

基本的なif、else、else if

<!--テンプレート -->
{{#if user.profile.male}}
   <p>Dear Sir</p>
{{else if user.profile.female}}
   <p>Dear Madame</p>
{{else}}
   <p>Dear Customer</p>
{{/if}}

//テストデータ1
{
   "user":{
      "profile":{
         "male":true
      }
   }
}

// テストデータ2
{
   "user":{
      "profile":{
         "female":true
      }
   }
}

// テストデータ3
{
   "user":{
      "profile":{

      }
   }
}

<!--テストデータ1による結果のHTML-->
<p>Dear Sir</p>

<!-- テストデータ2による結果のHTML-->
<p>Dear Madame</p>

<!-- テストデータ3による結果のHTML-->
<p>Dear Customer</p>

rootを使用したif

<!--テンプレート -->
{{#if user.suspended}}
   <p>Warning! Your account is suspended, please call: {{@root.supportPhone}}</p>
{{/if}}

//テストデータ
{
  "user": {
    "suspended": true
  },
  "supportPhone": "1-800-555-5555"
}

<!--結果のHTML-->
<p>Warning! Your account is suspended, please call: 1-800-555-5555</p>

Unless

<!--テンプレート -->
{{#unless user.active}}
   <p>Warning! Your account is suspended, please call: {{@root.supportPhone}}</p>
{{/unless}}

//テストデータ
{
  "user": {
    "active": false
  },
  "supportPhone": "1-800-555-5555"
}

<!--結果のHTML-->
<p>Warning! Your account is suspended, please call: 1800-555-5555</p>

greaterThan(~より大きい)

基本的な使い方

<!--テンプレート-->
<p>
Hello Ben!
{{#greaterThan scoreOne scoreTwo}}
    Congratulations, you have the high score today!
{{/greaterThan}}
 Thanks for playing.
</p>

//テストデータ1
{
  "scoreOne": 100,
  "scoreTwo": 78
}

// テストデータ2
{
  "scoreOne": 55,
  "scoreTwo": 78
}

<!--テストデータ1による結果のHTML-->
<p>
  Hello Ben! Congratulations, you have the high score today! Thanks for playing.
</p>

<!-- テストデータ2による結果のHTML-->
<p>Hello Ben! Thanks for playing.</p>

elseを伴うgreaterThan(~より大きい)

<!--テンプレート-->
<p>
Hello Ben!
{{#greaterThan scoreOne scoreTwo}}
    Congratulations, you have the high score today!
{{else}}
    You were close, but you didn't get the high score today.
{{/greaterThan}}
Thanks for playing.
</p>

//テストデータ1
{
  "scoreOne": 100,
  "scoreTwo": 78
}

// テストデータ2
{
  "scoreOne": 55,
  "scoreTwo": 78
}

<!--テストデータ1による結果のHTML-->
<p>
  Hello Ben! Congratulations, you have the high score today! Thanks for playing.
</p>

<!-- テストデータ2による結果のHTML-->
<p>
  Hello Ben! You were close, but you didn't get the high score today.Thanks for
  playing.
</p>

lessThan(~より小さい)

基本的な使い方

<!--テンプレート-->
<p>
Hello Ben!
{{#lessThan scoreOne scoreTwo}}
    You were close, but you didn't get the high score today.
{{/lessThan}}
Thanks for playing.
</p>

//テストデータ1
{
  "scoreOne": 55,
  "scoreTwo": 78
}

// テストデータ2
{
  "scoreOne": 100,
  "scoreTwo": 78
}

<!--テストデータ1による結果のHTML-->
<p>
  Hello Ben! You were close, but you didn't get the high score today.Thanks for
  playing.
</p>

<!-- テストデータ2による結果のHTML-->
<p>Hello Ben! Thanks for playing.</p>

elseを伴うlessThan(~より小さい)

<!--テンプレート-->
<p>
Hello Ben!
{{#lessThan scoreOne scoreTwo}}
    You were close, but you didn't get the high score today.
{{else}}
    Congratulations, you have the high score today!
{{/lessThan}}
 Thanks for playing.
</p>

//テストデータ1
{
  "scoreOne": 55,
  "scoreTwo": 78
}

// テストデータ2
{
  "scoreOne": 100,
  "scoreTwo": 78
}

<!--テストデータ1による結果のHTML-->
<p>
  Hello Ben! You were close, but you didn't get the high score today.Thanks for
  playing.
</p>

<!-- テストデータ2による結果のHTML-->
<p>
  Hello Ben! Congratulations, you have the high score today! Thanks for playing.
</p>

equals(等しい)

「equals」では、同じデータ型の2つの値が等しいかどうかを確認できます。「equals」ヘルパーでは、値のデータ型が異なる場合でも、比較するためにデータ型の自動変換も試行されます。たとえば、「{{#equals 3 "3"}}」は「true」と評価されます。

エディタのプレビューページでは、データ型が自動的に変換された値の比較結果は正しくレンダリングされないので注意してください。データ型が自動的に変換された値の比較結果は、配信されたメッセージでのみ確認できます。

真偽の判定では、空の文字列、整数のゼロ、浮動小数点数のゼロは「false」と評価されます。空ではない文字列、ゼロでない整数、負の数値を含むゼロでない浮動小数点数は、「true」と評価されます。

基本的な使い方

<!--テンプレート-->
<p>
Hello Ben!
{{#equals customerCode winningCode}}
    You have a winning code.
{{/equals}}
Thanks for playing.
</p>

//テストデータ1
{
  "customerCode": 289199,
  "winningCode": 289199
}

// テストデータ2
{
  "customerCode": 167320,
  "winningCode": 289199
}

<!--テストデータ1による結果のHTML-->
<p>Hello Ben! You have a winning code.Thanks for playing.</p>

<!-- テストデータ2による結果のHTML-->
<p>Hello Ben! Thanks for playing.</p>

elseを使用したequals(等しい)

<!--テンプレート-->
<p>
Hello Ben!
{{#equals customerCode winningCode}}
    You have a winning code.
{{else}}
    You do not have a winning code.
{{/equals}}
Thanks for playing.
</p>

//テストデータ1
{
  "customerCode": 289199,
  "winningCode": 289199
}

// テストデータ2
{
  "customerCode": 167320,
  "winningCode": 289199
}

<!--テストデータ1による結果のHTML-->
<p>Hello Ben! You have a winning code.Thanks for playing.</p>

<!-- テストデータ2による結果のHTML-->
<p>Hello Ben! You do not have a winning code.Thanks for playing.</p>

notEquals(等しくない)

「notEquals」では、同じデータ型の2つの値が等しいかどうかを確認できます。「notEquals」ヘルパーでは、値のデータ型が異なる場合でも、比較するためにデータ型の自動変換も試行されます。たとえば、{{#equals 3 "3"}}は「false」を返します。

基本的な使い方

<!--テンプレート-->
<p>
Hello Ben!
{{#notEquals customerCode winningCode}}
    You have a winning code.
{{/notEquals}}
Thanks for playing.
</p>

//テストデータ1
{
  "customerCode": 289199,
  "winningCode": 289199
}

// テストデータ2
{
  "customerCode": 167320,
  "winningCode": 289199
}

<!--テストデータ1による結果のHTML-->
<p>Hello Ben! You have a winning code.Thanks for playing.</p>

<!-- テストデータ2による結果のHTML-->
<p>Hello Ben! Thanks for playing.</p>

elseを伴うnotEquals(等しくない)

<!--テンプレート-->
<p>
Hello Ben!
{{#notEquals customerCode winningCode}}
    You have a winning code.
{{else}}
    You do not have a winning code.
{{/notEquals}}
Thanks for playing.
</p>

//テストデータ1
{
  "customerCode": 289199,
  "winningCode": 289199
}

// テストデータ2
{
  "customerCode": 167320,
  "winningCode": 289199
}

<!--テストデータ1による結果のHTML-->
<p>Hello Ben! You have a winning code.Thanks for playing.</p>

<!-- テストデータ2による結果のHTML-->
<p>Hello Ben! You do not have a winning code.Thanks for playing.</p>

and(かつ)

elseを使用しないand(かつ)

<!--テンプレート-->
<p>
Hello Ben!
{{#and favoriteFood favoriteDrink}}
   Thank you for letting us know your dining preferences.
{{/and}}.
We look forward to sending you more delicious recipes.</p>

//テストデータ1
{
  "favoriteFood": "Pasta",
  "favoriteDrink": ""
}

// テストデータ2
{
  "favoriteFood": "Pasta",
  "favoriteDrink": "Coffee"
}

<!--テストデータ1による結果のHTML-->
<p>Hi Ben! We look forward to sending you more delicious recipes.</p>

<!-- テストデータ2による結果のHTML -->
<p>
  Hi Ben! Thank you for letting us know your dining preferences.We look forward
  to sending you more delicious recipes.
</p>

elseを使用したand(かつ)

<!--テンプレート-->
<p>
Hello Ben!
{{#and favoriteFood favoriteDrink}}
   Thank you for letting us know your dining preferences.
{{else}}
   If you finish filling out your dining preferences survey, we can deliver you recipes we think you'll be most interested in.
{{/and}}.
We look forward to sending you more delicious recipes.</p>

//テストデータ1
{
  "favoriteFood": "Pasta",
  "favoriteDrink": ""
}

// テストデータ2
{
  "favoriteFood": "Pasta",
  "favoriteDrink": "Coffee"
}

<!--テストデータ1による結果のHTML -->
<p>
  Hi Ben! If you finish filling out your dining preferences survey, we can
  deliver you recipes we think you'll be most interested in. We look forward to
  sending you more delicious recipes.
</p>

<!-- テストデータ2による結果のHTML -->
<p>
  Hi Ben! Thank you for letting us know your dining preferences.We look forward
  to sending you more delicious recipes.
</p>

or(または)

基本的な使い方

<!--テンプレート-->
<p>
Hello Ben!
{{#or isRunner isCyclist}}
   We think you might enjoy a map of trails in your area.
{{/or}}.
Have a great day.
</p>

//テストデータ1
{
  "isRunner": true,
  "isCyclist": false
}

// テストデータ2
{
  "isRunner": false,
  "isCyclist": false
}
//テストデータ3
{
  "isRunner": false,
  "isCyclist": true
}

<!--テストデータ1による結果のHTML -->
<p>
  Hi Ben! We think you might enjoy a map of trails in your area.You can find
  the map attached to this email.Have a great day.
</p>

<!-- テストデータ2による結果のHTML-->
<p>Hi Ben! Have a great day.</p>

<!-- テストデータ3による結果のHTML -->
<p>
  Hi Ben! We think you might enjoy a map of trails in your area.You can find
  the map attached to this email.Have a great day.
</p>

elseを使用したor(または)

<!--テンプレート-->
<p>
Hello Ben!
{{#or isRunner isCyclist}}
   We think you might enjoy a map of trails in your area.You can find the map attached to this email.
{{else}}
   We'd love to know more about the outdoor activities you enjoy.The survey linked below will take only a minute to fill out.
{{/or}}.
Have a great day.
</p>

//テストデータ1
{
  "isRunner": true,
  "isCyclist": false
}

// テストデータ2
{
  "isRunner": false,
  "isCyclist": false
}
//テストデータ3
{
  "isRunner": false,
  "isCyclist": true
}

<!--テストデータ1による結果のHTML -->
<p>
  Hi Ben! We think you might enjoy a map of trails in your area.You can find
  the map attached to this email.Have a great day.
</p>

<!-- テストデータ2による結果のHTML -->
<p>
  Hi Ben! We'd love to know more about the outdoor activities you enjoy.The
  survey linked below will take only a minute to fill out.Have a great day.
</p>

<!-- テストデータ3による結果のHTML -->
<p>
  Hi Ben! We think you might enjoy a map of trails in your area.You can find
  the map attached to this email.Have a great day.
</p>

length(長さ)

lengthヘルパーは、与えられた文字列か配列の文字数を返します。文字列でも配列でもない値では、lengthは0を返します。lengthは、以下の例に示すようにgreaterThanなどの他のヘルパーと組み合わせると便利です。

<!--テンプレート-->
<p>
Hello Ben!
{{#greaterThan (length cartItems) 0}}
 It looks like you still have some items in your shopping cart.Sign back in to continue checking out at any time.
{{else}}
Thanks for browsing our site.We hope you'll come back soon.
{{/greaterThan}}
</p>

//テストデータ1
{
  "cartItems": ["raft", "water bottle", "sleeping bag"]
}

// テストデータ2
{
  "cartItems": []
}

<!--テストデータ1による結果のHTML-->
<p>
  Hello Ben! It looks like you still have some items in your shopping cart.Sign
  back in to continue checking out at any time.
</p>

<!-- テストデータ2による結果のHTML-->
<p>Hello Ben! Thanks for browsing our site.We hope you'll come back soon.</p>

反復

{{#each }}ヘルパー関数によりデータをループ、つまり反復処理し、リストの作成やその他有用なテンプレートアクションを実行できます。

eachを使用した基本的な反復子

<!--テンプレート -->
<ol>
  {{#each user.orderHistory}}
   <li>You ordered: {{this.item}} on: {{this.date}}</li>
  {{/each}}
</ol>

//テストデータ
{
  "user": {
    "orderHistory": [
      {
        "date": "2/1/2018",
        "item": "shoes"
      },
      {
        "date": "1/4/2017",
        "item": "hat"
      }
    ]
  }
}

<!--結果のHTML -->
<ol>
  <li>You ordered: shoes on: 2/1/2018</li>
  <li>You ordered: hat on: 1/42017</li>
</ol>

組み合わせた例

以下の例では、複数のHandlebars関数を組み合わせ、高度な動的テンプレートを作成しています。

動的なコンテンツ作成
動的な要素を含む動的なコンテンツ作成1
動的な要素を含む動的なコンテンツ作成2

動的なコンテンツ作成

<!--テンプレート -->
{{#each user.story}}
   {{#if this.male}}
      <p>{{this.date}}</p>
   {{else if this.female}}
      <p>{{this.item}}</p>
   {{/if}}
{{/each}}

//テストデータ
{
  "user": {
    "story": [
      {
        "male": true,
        "date": "2/1/2018",
        "item": "shoes"
      },
      {
        "male": true,
        "date": "1/4/2017",
        "item": "hat"
      },
      {
        "female": true,
        "date": "1/1/2016",
        "item": "shirt"
      }
    ]
  }
}

<!--結果のHTML-->
<p>2/1/2018</p>
<p>1/4/2017</p>
<p>shirt</p>

動的な要素を含む動的なコンテンツ作成1

<!--テンプレート -->
{{#each user.story}}
   {{#if this.male}}
      {{#if this.date}}
         <p>{{this.date}}</p>
      {{/if}}
      {{#if this.item}}
         <p>{{this.item}}</p>
      {{/if}}
   {{else if this.female}}
      {{#if this.date}}
         <p>{{this.date}}</p>
      {{/if}}
      {{#if this.item}}
         <p>{{this.item}}</p>
      {{/if}}
   {{/if}}
{{/each}}

//テストデータ
{
  "user": {
    "story": [
      {
        "male": true,
        "date": "2/1/2018",
        "item": "shoes"
      },
      {
        "male": true,
        "date": "1/4/2017"
      },
      {
        "female": true,
        "item": "shirt"
      }
    ]
  }
}

<!--結果のHTML-->
<p>2/1/2018</p>
<p>shoes</p>
<p>1/4/2017</p>
<p>shirt</p>

動的な要素を含む動的なコンテンツ作成2

<!--テンプレート -->
{{#if people}}
   <p>People:</p>
   {{#each people}}
      <p>{{this.name}}</p>
   {{/each}}
{{/if}}

//テストデータ
{
  "people": [{ "name": "Bob" }, { "name": "Sally" }]
}

<!--結果のHTML-->
<p>People: </p>
<p>Bob</p>
<p>Sally</p>

その他のリソース

サポートが必要ですか？

誰にでもそういうことはあります。今すぐTwilio SendGridサポートチームにヘルプしてもらいましょう。

コーディングで行き詰っていませんか？Stack OverflowのSendGridタグの質問一覧を参照するか、Stack OverflowのTwilio Collectiveにアクセスして、皆さんの知恵を借りましょう。

サポートが必要ですか？

フィードバックいただき、ありがとうございました。

フィードバックいただき、ありがとうございました。