HubLの変数とマクロ構文
HubLでは、値の保存やテンプレートへの出力に変数を使用します。変数はテンプレートのロジックで使用することも、forループで繰り返し使用することもできます。テンプレートで繰り返し使用されるコードの動的な部分を出力するには、変数のほかに、マクロを使用することもできます。
変数は}}
で囲まれた式です。変数の基本的な構文を次に示します。
変数は、式の中の単一の語、またはディクショナリー(辞書型)の属性のいずれかです。HubLでは、ディクショナリー(dicts)と呼ばれるPythonベースのデータ構造を使用して、さまざまな変数のセットを保存します。例えば、HubSpotではディクショナリー「content」を使用して、そのテンプレートで作成されたコンテンツに関する多くの属性を格納しています。content.absolute_url
と指定した場合、特定のコンテンツのURLが出力されます。
HubSpotには、ページやブログ、Eメールのテンプレートに使用できる多数の定義済み変数が用意されています。変数のリファレンスリストがあります。アカウントからページを閲覧するときに開発者情報を表示することもでき、そのページ内で利用可能な変数が表示されます。
変数の値やディクショナリーの属性をテンプレートに出力するほかに、ユーザー独自の変数を定義することもできます。1つの変数内に文字列、ブール値、整数、シーケンスを格納したり、ディクショナリーを作成したりできます。変数は、文の区切り文字の内側で、「set」を使って定義します。格納された変数を出力するには、変数名を式として記述します。以下では、さまざまなタイプの情報を変数に格納し、出力しています。
変数は1つの単語にするか、スペースの代わりに下線を使用する(my_variableなど)必要があります。HubLでは、ハイフンで連結した変数名はサポートされません。
上記の例はそれぞれに異なる型の変数を格納しています。最後の例では2つの別々の変数を1つのシーケンスとして格納しています。
変数は、値を出力するほかにも、if文内、filterパラメーターやfunctionパラメーターとして使用したり、forループで反復処理(シーケンス変数のみ)に使用したりできます。
一般的な使用例の1つに、スタイルシートでよく使われるCSSの値を変数を使用して定義する方法があります。例えば、ある色をCSSファイル全体で繰り返し使用しているとします。この色を変数を使用して定義しておけば、変数の値を変更するだけで、色を変更できます。次にファイルを公開したときに、その変数に対する参照が全て更新されます。
HubLマクロでは、動的な値を使用して複数の文を出力できます。例えば、同じコードブロックを何度も記述するような場合は、マクロを使用すると便利です。マクロに渡す引数を切り替えることで、そのコードブロックを出力できます。
マクロは、HubL文の中で定義し、名前を付け、引数を指定します。このマクロを別の文で呼び出して動的な値を渡すと、動的な引数を持つ最終的なコードブロックが出力されます。マクロの基本的な構文を次に示します。
マクロから空白文字が改行として返される場合は、テンプレート内の空白文字を手動で取り除くことができます。ブロック、コメント、変数の式の先頭または末尾にマイナス記号(-
)を追加すると、そのブロックの前または後の空白文字が削除されます。
以下の実用例では、さまざまなベンダープレフィックスを含むCSS3プロパティーを動的な値と合わせて出力するために、マクロを使用しています。この例では、1つのmacroタグで5行のコードを出力できます。
マクロにおいて、再帰コードを利用できるようになります。信頼性とパフォーマンスの問題を防ぐため、マクロのネスト可能な階層は最大20になっています。この上限を超えると、max recursion limit of 20 reached for macro <your macro name>
というエラーが返されます。
場合によっては、動的な追加情報をマクロブロックに渡す必要があるかもしれません。例えば、引数のほかに、長いコードをマクロに挿入する場合です。これを行うには、callブロックとcaller()を使用します。callブロックは基本的にマクロと同じように機能しますが、callブロックに名前は指定しません。caller()式で、callブロックの内容をどこに表示するかを指定します。
以下の例では、2つの引数に加えて、1つの<p>
がマクロに追加されています。
マクロには、あるテンプレートファイルから別のテンプレートファイルにインポートして使用できる便利な機能もあります。これには、importタグを使用する必要があります。importタグでは、マクロが含まれているテンプレートへのDesign Manager(デザインマネージャー)ファイルパスを指定し、インポート先テンプレート内でのマクロ名を指定することができます。その後に、それらのマクロに値を渡すことができます。マクロを再定義する必要はありません。
例えば、次の2つのマクロが含まれている.htmlテンプレートファイルがあるとします。1つのマクロはheaderタグを設定するために定義し、もう1つはfooterタグを生成するために定義しています。このファイルはデザインマネージャーにmy_macros.html
という名前で保存されています。
これらのマクロを使用するテンプレートでは、my_macros.html
ファイルへのファイルパスを指定したimportタグを使用します。また、マクロのグループには名前を付けます(この例ではheader_footer
)。そして、そのインポートしたテンプレートに付けた名前にマクロ名を追加することでマクロを実行できます。以下の例を参照してください。
別の.htmlファイルに含まれている全てのマクロではなく、特定のマクロのみをインポートする場合は、fromタグを使用します。fromタグでは、インポートするマクロのみを指定します。通常、importを使用する方が柔軟性は向上しますが、この代替手段もサポートされます。
次の例では、この記事の前のセクションと同じmy_macros.html
ファイルを利用します。ただし、今回は、全てのマクロをインポートするのではなく、footerマクロのみを利用します。
ループ内で定義した変数は、そのループの範囲内に制限され、ループの外側から呼び出すことはできません。
ループ外で定義した変数をループ内から呼び出すことはできますが、その逆はできません。
また、dictに値を設定する場合やリスト操作を実行する場合にオブジェクトを変化させるために、関数を使用できます。以下の例では.update
リスト操作を使用しています。
貴重なご意見をありがとうございました。