{{ . }} is even
+{{ else }} +{{ . }} is odd
+{{ end }} +{{< /code >}} + +When called, the partial renders HTML: + +```go-html-template +{{ partial "odd-or-even.html" 42 }} →42 is even
+``` + +Instead of rendering HTML, let's create a partial that _returns_ a boolean value, reporting whether the given number is even: + +{{< code file="layouts/partials/is-even.html" >}} +{{ return math.ModBool . 2 }} +{{< /code >}} + +With this template: + +```go-html-template +{{ $number := 42 }} +{{ if partial "is-even.html" $number }} +{{ $number }} is even
+{{ else }} +{{ $number }} is odd
+{{ end }} +``` + +Hugo renders: + +```html +42 is even
+``` + +See additional examples in the [partial templates] section. + +[partial templates]: /templates/partials/#returning-a-value-from-a-partial + +## Usage + +{{% note %}} +Unlike `return` statements in other languages, Hugo executes the first occurence of the `return` statement regardless of its position within logical blocks +{{% /note %}} + +A partial that returns a value must contain only one `return` statement, placed at the end of the template. + +For example: + +{{< code file="layouts/partials/is-even.html" >}} +{{ $result := false }} +{{ if math.ModBool . 2 }} + {{ $result = "even" }} +{{ else }} + {{ $result = "odd" }} +{{ end }} +{{ return $result }} +{{< /code >}} + +{{% note %}} +The construct below is incorrect; it contains more than one `return` statement. +{{% /note %}} + +{{< code file="layouts/partials/do-not-do-this.html" >}} +{{ if math.ModBool . 2 }} + {{ return "even" }} +{{ else }} + {{ return "odd" }} +{{ end }} +{{< /code >}} diff --git a/content/en/functions/partials/Include.md b/content/en/functions/partials/Include.md index e9ed093d89..859f6665ba 100644 --- a/content/en/functions/partials/Include.md +++ b/content/en/functions/partials/Include.md @@ -1,19 +1,24 @@ --- title: partials.Include -description: Executes the given partial template, optionally passing context. If the partial contains a return statement, returns that value, else returns the rendered output. +description: Executes the given partial template, optionally passing context. If the partial template contains a return statement, returns the given value, else returns the rendered output. categories: [] keywords: [] action: aliases: [partial] related: - - functions/go-template/template + - functions/go-template/return - functions/partials/IncludeCached + - functions/go-template/template - methods/page/Render returnType: any signatures: ['partials.Include NAME [CONTEXT]'] aliases: [/functions/partial] --- +Without a [`return`] statement, the `partial` function returns a string of type `template.HTML`. With a `return` statement, the `partial` function can return any data type. + +[`return`]: /functions/go-template/return + In this example we have three partial templates: ```text @@ -60,4 +65,21 @@ Then, within the partial template:{{ .name }} is majoring in {{ .major }}. Their grade point average is {{ .gpa }}.
``` +To return a value from a partial template, it must contain only one `return` statement, placed at the end of the template: + +```go-html-template +{{ $result := false }} +{{ if math.ModBool . 2 }} + {{ $result = "even" }} +{{ else }} + {{ $result = "odd" }} +{{ end }} +{{ return $result }} +``` + +See [details][`return`]. + +[`return`]: /functions/go-template/return + [breadcrumb navigation]: /content-management/sections/#ancestors-and-descendants +[details]: /functions/go-template/return diff --git a/content/en/functions/partials/IncludeCached.md b/content/en/functions/partials/IncludeCached.md index 8c9d915c73..a65409a385 100644 --- a/content/en/functions/partials/IncludeCached.md +++ b/content/en/functions/partials/IncludeCached.md @@ -1,13 +1,14 @@ --- title: partials.IncludeCached -description: Executes the given template and caches the result, optionally passing context. If the partial contains a return statement, returns that value, else returns the rendered output. +description: Executes the given template and caches the result, optionally passing context. If the partial template contains a return statement, returns teh given value, else returns the rendered output. categories: [] keywords: [] action: aliases: [partialCached] related: - - functions/go-template/template + - functions/go-template/return - functions/partials/Include + - functions/go-template/template - methods/page/Render returnType: any signatures: ['partials.IncludeCached LAYOUT CONTEXT [VARIANT...]'] @@ -17,7 +18,11 @@ signatures: aliases: [/functions/partialcached] --- -The `partialCached` template function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. +Without a [`return`] statement, the `partialCached` function returns a string of type `template.HTML`. With a `return` statement, the `partialCached` function can return any data type. + + + +The `partialCached` function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. {{% note %}} Each Site (or language) has its own `partialCached` cache, so each site will execute a partial once. @@ -31,18 +36,32 @@ Here is the simplest usage: {{ partialCached "footer.html" . }} ``` -You can also pass additional arguments to `partialCached` to create *variants* of the cached partial. For example, if you have a complex partial that should be identical when rendered for pages within the same section, you could use a variant based upon section so that the partial is only rendered once per section: +Pass additional arguments to `partialCached` to create variants of the cached partial. For example, if you have a complex partial that should be identical when rendered for pages within the same section, use a variant based on section so that the partial is only rendered once per section: {{< code file=partial-cached-example.html >}} {{ partialCached "footer.html" . .Section }} {{< /code >}} -If you need to pass additional arguments to create unique variants, you can pass as many variant arguments as you need: +Pass additional arguments, of any data type, as needed to create unique variants: ```go-html-template {{ partialCached "footer.html" . .Params.country .Params.province }} ``` -Note that the variant arguments are not made available to the underlying partial template. They are only use to create a unique cache key. Since Hugo `0.61.0` you can use any object as cache key(s), not just strings. +The variant arguments are not available to the underlying partial template; they are only used to create unique cache keys. + +To return a value from a partial template, it must contain only one `return` statement, placed at the end of the template: + +```go-html-template +{{ $result := false }} +{{ if math.ModBool . 2 }} + {{ $result = "even" }} +{{ else }} + {{ $result = "odd" }} +{{ end }} +{{ return $result }} +``` + +See [details][`return`]. -See also [The Full Partial Series Part 1: Caching!](https://regisphilibert.com/blog/2019/12/hugo-partial-series-part-1-caching-with-partialcached/). +[`return`]: /functions/go-template/return