パーシャル
パーシャルは、リストやページのテンプレートに含まれる、文脈を考慮した小さなコンポーネントで、テンプレートを DRY に保つために経済的に使用できます。
パーシャル テンプレートの検索順序
シングルページ テンプレート および リストページ テンプレート のような パーシャル テンプレート には、特定の 検索順序 があります。 ただし、パーシャルは、Hugo が 2 つの場所でのみチェックするという点で単純です。
layouts/partials/*<PARTIALNAME>.htmlthemes/<THEME>/layouts/partials/*<PARTIALNAME>.html
これにより、テーマのエンドユーザーは、さらなるカスタマイズ のために、パーシャルのコンテンツを同じ名前のファイルにコピーできます。
テンプレートにパーシャルを使用する
Hugo プロジェクトのすべてのパーシャルは、単一の layouts/partials ディレクトリに格納されます。 より良い構成のために、以下のように、partials 内に複数のサブディレクトリを作成することもできます。
layouts/
└── partials/
├── footer/
│ ├── scripts.html
│ └── site-footer.html
├── head/
│ ├── favicons.html
│ ├── metadata.html
│ ├── prerender.html
│ └── twitter.html
└── header/
├── site-header.html
└── site-nav.html
すべてのパーシャルは、テンプレート内で以下のパターンを使用して呼び出されます。
{{ partial "<PATH>/<PARTIAL>.html" . }}
.) が必要であることに注意してください。 「ドット」の詳細については、「Hugo テンプレート入門」
を参照してください。
baseof を含む <PARTIAL> は予約されています。(#5373
)
上記のディレクトリ構造の例で示したように、 ディレクトリを partials 内にネストさせることで、より良いソース構成を実現できます。ネストされたパーシャルのパスは、以下のように、 partials ディレクトリからの相対パスとして呼び出すだけです。
{{ partial "header/site-header.html" . }}
{{ partial "footer/scripts.html" . }}
変数のスコープ
部分呼び出しの 2 番目の引数は、渡される変数です。 上記の例では . を渡していますが、これはパーシャルを受け取るテンプレートに現在の コンテキスト
を適用するように指示します。
これは、パーシャルがこれらの変数に 唯一 アクセスできることを意味します。パーシャルは分離され、外部スコープにはアクセスできません。 パーシャル内では、$.Var は .Var と同等です。
パーシャルから値を返す
マークアップの出力に加えて、パーシャルを使用して任意の型の値を返すことができます。 値を返すために、パーシャルは パーシャルの末尾に、単一の return 文を含める必要があります。
GetFeatured の例
{{/* layouts/partials/GetFeatured.html */}}
{{ return first . (where site.RegularPages "Params.featured" true) }}
{{/* layouts/index.html */}}
{{ range partial "GetFeatured.html" 5 }}
[...]
{{ end }}
GetImage の例
{{/* layouts/partials/GetImage.html */}}
{{ $image := false }}
{{ with .Params.gallery }}
{{ $image = index . 0 }}
{{ end }}
{{ with .Params.image }}
{{ $image = . }}
{{ end }}
{{ return $image }}
{{/* layouts/_default/single.html */}}
{{ with partial "GetImage.html" . }}
[...]
{{ end }}
return 文は 1 つだけ許可されます。
インライン パーシャル
テンプレートでパーシャルをインラインで定義することもできます。 ただし、テンプレートの名前空間はグローバルであるため、競合を避けるために名前が一意であることを確認する必要があります。
Value: {{ partial "my-inline-partial.html" . }}
{{ define "partials/my-inline-partial.html" }}
{{ $value := 32 }}
{{ return $value }}
{{ end }}
キャッシュされたパーシャル
partialCached テンプレート関数
は、呼び出しごとに再レンダリングする必要のない複雑なテンプレートのパフォーマンスを大幅に向上させることができます。 最も単純な使用方法は、以下のとおりです。
{{ partialCached "footer.html" . }}
また、 partialCached に追加のパラメータを渡すことで、キャッシュされたパーシャルの バリアント を作成することができます。
たとえば、以下のコードで、セクションごとに 1 回だけ部分的な footer.html をレンダリングするように Hugo に指示できます。
{{ partialCached "footer.html" . .Section }}
一意のバリアントを作成するために追加のパラメータを渡す必要がある場合は、以下のように、必要な数のバリアント パラメータを渡すことができます。
{{ partialCached "footer.html" . .Params.country .Params.province }}
バリアント パラメータは基本的なパーシャルでは利用できないことに注意してください。これらは、一意のキャッシュキーを作成するためにのみ使用されます。
header.html の例
以下の header.html パーシャルは、 spf13.com
のために使用されています。
<!DOCTYPE html>
<html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
<head>
<meta charset="utf-8">
{{ partial "meta.html" . }}
<base href="{{ .Site.BaseURL }}">
<title> {{ .Title }} : spf13.com </title>
<link rel="canonical" href="{{ .Permalink }}">
{{ if .RSSLink }}<link href="{{ .RSSLink }}" rel="alternate" type="application/rss+xml" title="{{ .Title }}" />{{ end }}
{{ partial "head_includes.html" . }}
</head>header.html のサンプルのパーシャルは、ブロックテンプレートが Hugo に導入される前に作成されました。 マスターテンプレートの外側のクロムまたはシェル (つまり、サイトのヘッド、ヘッダー、およびフッター) を定義するために、ベーステンプレートとブロック
の詳細を参照してください。 柔軟性を高めるために、ブロックとパーシャルを組み合わせることもできます。
footer.html の例
以下の footer.html パーシャルは、 spf13.com
のために使用されています。