hugo/docs/content/en/functions/scratch.md
2018-05-04 09:44:59 +02:00

2.9 KiB

title description godocref date publishdate lastmod keywords categories menu toc signature workson hugoversion relatedfuncs deprecated draft aliases
.Scratch Acts as a "scratchpad" to allow for writable page- or shortcode-scoped variables. 2017-02-01 2017-02-01 2017-02-01
iteration
functions
docs
parent
functions
false false
/extras/scratch/
/doc/scratch/

In most cases you can do okay without Scratch, but due to scoping issues, there are many use cases that aren't solvable in Go Templates without Scratch's help.

{{% note %}} See this Go issue for the main motivation behind Scratch. {{% /note %}}

{{% note %}} For a detailed analysis of .Scratch and in context use cases, see this post. {{% /note %}}

Methods

Scratch is added to both Page and Shortcode -- with following methods:

.Set

Set the given value to a given key

{{ .Scratch.Set "greeting" "Hello" }}

.Get

Get the value of a given key

{{ .Scratch.Set "greeting" "Hello" }}
----
{{ .Scratch.Get "greeting" }} > Hello

.Add

Will add a given value to existing value of the given key.

For single values, Add accepts values that support Go's + operator. If the first Add for a key is an array or slice, the following adds will be appended to that list.

{{ .Scratch.Add "greetings" "Hello" }}
{{ .Scratch.Add "greetings" "Welcome" }}
----
{{ .Scratch.Get "greetings" }} > HelloWelcome
{{ .Scratch.Add "total" 3 }}
{{ .Scratch.Add "total" 7 }}
----
{{ .Scratch.Get "total" }} > 10
{{ .Scratch.Add "greetings" (slice "Hello") }}
{{ .Scratch.Add "greetings" (slice "Welcome" "Cheers") }}
----
{{ .Scratch.Get "greetings" }} > []interface {}{"Hello", "Welcome", "Cheers"}

.SetInMap

Takes a key, mapKey and value and add a map of mapKey and value to the given key.

{{ .Scratch.SetInMap "greetings" "english" "Hello" }}
{{ .Scratch.SetInMap "greetings" "french" "Bonjour" }}
----
{{ .Scratch.Get "greetings" }} > map[french:Bonjour english:Hello]

.GetSortedMapValues

Returns array of values from key sorted by mapKey

{{ .Scratch.SetInMap "greetings" "english" "Hello" }}
{{ .Scratch.SetInMap "greetings" "french" "Bonjour" }}
----
{{ .Scratch.GetSortedMapValues "greetings" }} > [Hello Bonjour]

.Delete

Removes the given key

{{ .Scratch.Delete "greetings" }}

Scope

The scope of the backing data is global for the given Page or Shortcode, and spans partial and shortcode includes.

Note that .Scratch from a shortcode will return the shortcode's Scratch, which in most cases is what you want. If you want to store it in the page scoped Scratch, then use .Page.Scratch.