hugo/docs/content/en/functions/scratch.md

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.

.Scratch is available as methods on Page and Shortcode. Since Hugo 0.43 you can also create a locally scoped Scratch using the template func newScratch.

{{% 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 %}}

Get a Scratch

From Hugo 0.43 you can also create a locally scoped Scratch by calling newScratch:

$scratch := newScratch
$scratch.Set "greeting" "Hello"

A Scratch is also added to both Page and Shortcode. Scratch has the 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" }}

.Values

Values returns the raw backing map. Note that you should just use this method on the locally scoped Scratch instances you obtain via newScratch, not .Page.Scratch etc., as that will lead to concurrency issues.

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.