本記事の概要
Hugoのショートコードの入門となる初心者向けの記事です。
本記事はその2になります。
前提
Hugo+Blowfishテーマ適用済みの環境です。
なお、Windowsでの操作を想定しています。
(本記事が属するアドベントカレンダーについてもご確認ください)
また、下記その1の内容が前提となります。
Hugoの引数の指定方法
前回のShortCodeは下記のように、引数として取り得る値をただ書く形でした。
※説明の為、以下「名前付きパラメーターを使用しない方法」と呼ぶことにします。
{{< ruby "本気" "マジ" >}}
今回のShortCodeでは無くても問題は起きませんが、
モノによっては「○○というパラメーターにAという値を入れる」というニーズもあると思います。
という訳で、Hugoには「名前付きパラメーターを使用した方法」でのShortCode呼び出しも実現できます。
先の例で言えば、このように指定することも可能です。
{{< ruby rb="本気" rt="マジ" >}}
引数の指定方法の注意点
名前付きパラメーターを「使用する」方法と「使用しない」方法があると説明しましたが、重要な注意点が2つあります。
- どちらが使えるかはShortCodeの実装に依存する
- 呼び出す際に、2つの方法を混在させることが出来ない
という点です。
注意点1.に関して言えば、前回までの実装では名前付きパラメーターを使用しない方法でしか使えません。
そのため、どちらの記法で使えるかはShortCodeの説明などを確認する必要があります。
Hugoやテーマに組み込まれたShortCodeの場合、何かしらのドキュメントなどに説明が書いてあることが一般的です。
個人が管理する環境において、自分用のShortCodeを追加する分においては、どちらの方法で呼び出すか把握していると思うのであまり問題にはならないと思いますが、今回の記事では、理解を深める意味も込めて、両方に対応できるショートコードとして作成します。
注意点2.について言えば、下記のようなパターンでは呼び出せないという意味です。
{{< ruby rb="本気" "マジ" >}}
理由としては簡単です。
名前付きパラメーターを使用した方法においては、パラメーターの名前さえあっていれば、どの順番で書いても問題ないからです。
例えば、下記の2つは同じ結果になります。
{{< ruby rb="本気" rt="マジ" >}}
{{< ruby rt="マジ" rb="本気" >}}
そのため、混在させようとすると、名前付きでないパラメーターがどのパラメーターに対して指定しているのかが不明になるからです。
したがって、引数のあるShortCodeにおいては下記の3パターンしかありえないことになります。
- 名前付きパラメーターを使用しない方法のみに対応(パラメーターが1個の場合に多い)
- 名前付きパラメーターを使用する方法のみに対応(パラメーターが多い場合はこちらが多い)
- 上記1.と2.のどちらも対応
ShortCode側での判別方法
ここまでくると、ShortCodeの実装側で、どちらの方法で呼び出されたかを判別する必要があります。
判別には、「.IsNamedParams」という関数を使います。
下記のように実装します。
{{- $rb := cond .IsNamedParams (.Get "rb") (.Get 0) -}}
{{- $rt := cond .IsNamedParams (.Get "rt") (.Get 1) -}}
<ruby>{{- $rb -}}<rp>(</rp><rt>{{- $rt -}}</rt><rp>)</rp></ruby>
ShortCodeの解説
先程のShortCodeを見ると、3行目は前回とほぼ同じですが、1行目と2行目が新たに追加されています。
その意味合いを解説していきます。
{{- $rb := cond .IsNamedParams (.Get "rb") (.Get 0) -}}
まず、1行目は前回にも登場した「{{-」と「-}}」で囲われています。
この中では、HugoのShortCodeの処理を記述することになります。
左辺側の「＄rb」は変数です。変数には何かしらの値を入れておき、後でその値を使うことが出来ます。
ただ、変数が存在することをHugoに教える必要があります。それが:=です。
つまり、「$rb :=」というのは「rbという名前の変数が存在する」ということです。
そして、その初期値を右辺側に置きます。
ここでは、「cond .IsNamedParams (.Get "rb") (.Get 0)」と書かれています。
Hugoに組み込まれたcond関数を利用し、その結果を初期値とするという意味です。
condは3つの引数を取る関数であり、下記のような意味合いです。
cond 条件 条件を満たす(Trueの)場合の値 条件を満たさない(Falseの)場合の値
つまり、.IsNamedParams関数の結果に応じて、condが返す値が変わります。
そして、.IsNamedParams関数は、
- 名前付きパラメーターを使用する方法で呼び出された場合はTrue
- 名前付きパラメーターを使用しない方法で呼び出された場合はFalse
となります。
これにより、名前付きパラメーターを使用するか否かでパラメーターの取得方法が変わります。
したがって、
- 名前付きパラメーターを使用する場合は(.Get "rb")、つまりrbという名前を指定したパラメーターの値を取ってくる
- 名前付きパラメーターを使用しない場合は、前回のように(.Get 0)ですので、0番目の引数を取ってくる
という意味合いになります。
1行目が読めれば、2行目も同じ要領で読めます。
3行目ですが、変数を使う際は、「$」付きで変数名を指定すればその値を使えます。
確かめてみる
表示結果は前回と同じなので省略しますが、下記のどちらの方法で書いても、同じ結果になります。
{{< ruby "本気" "マジ" >}}
{{< ruby rb="本気" rt="マジ" >}}