2017-08-10 11:18:22 -04:00
---
title: .Scratch
description: Acts as a "scratchpad" to allow for writable page- or shortcode-scoped variables.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
2017-09-21 13:03:00 -04:00
keywords: [iteration]
2017-08-10 11:18:22 -04:00
categories: [functions]
menu:
docs:
parent: "functions"
toc:
signature: []
workson: []
hugoversion:
relatedfuncs: []
deprecated: false
draft: false
aliases: [/extras/scratch/,/doc/scratch/]
---
2018-04-21 17:01:55 -04:00
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.
2017-08-10 11:18:22 -04:00
2018-08-01 04:01:05 -04:00
`.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` .
2017-08-10 11:18:22 -04:00
{{% note %}}
See [this Go issue ](https://github.com/golang/go/issues/10608 ) for the main motivation behind Scratch.
{{% /note %}}
2018-04-21 17:01:55 -04:00
{{% note %}}
For a detailed analysis of `.Scratch` and in context use cases, see this [post ](https://regisphilibert.com/blog/2017/04/hugo-scratch-explained-variable/ ).
{{% /note %}}
2018-07-18 05:04:57 -04:00
## Get a Scratch
2018-04-21 17:01:55 -04:00
2018-07-18 05:04:57 -04:00
From Hugo `0.43` you can also create a locally scoped `Scratch` by calling `newScratch` :
```go-html-template
$scratch := newScratch
$scratch.Set "greeting" "Hello"
```
2018-08-01 04:01:05 -04:00
A `Scratch` is also added to both `Page` and `Shortcode` . `Scratch` has the following methods:
2017-08-10 11:18:22 -04:00
2018-04-21 17:01:55 -04:00
#### .Set
2018-07-18 05:04:57 -04:00
2018-04-21 17:01:55 -04:00
Set the given value to a given key
```go-html-template
{{ .Scratch.Set "greeting" "Hello" }}
```
#### .Get
Get the value of a given key
```go-html-template
{{ .Scratch.Set "greeting" "Hello" }}
----
{{ .Scratch.Get "greeting" }} > Hello
```
2017-08-10 11:18:22 -04:00
2018-04-21 17:01:55 -04:00
#### .Add
Will add a given value to existing value of the given key.
2017-08-10 11:18:22 -04:00
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.
2018-04-21 17:01:55 -04:00
```go-html-template
{{ .Scratch.Add "greetings" "Hello" }}
{{ .Scratch.Add "greetings" "Welcome" }}
----
{{ .Scratch.Get "greetings" }} > HelloWelcome
```
2017-08-10 11:18:22 -04:00
2018-04-21 17:01:55 -04:00
```go-html-template
{{ .Scratch.Add "total" 3 }}
{{ .Scratch.Add "total" 7 }}
----
{{ .Scratch.Get "total" }} > 10
```
2017-08-10 11:18:22 -04:00
2018-04-21 17:01:55 -04:00
```go-html-template
{{ .Scratch.Add "greetings" (slice "Hello") }}
{{ .Scratch.Add "greetings" (slice "Welcome" "Cheers") }}
----
{{ .Scratch.Get "greetings" }} > []interface {}{"Hello", "Welcome", "Cheers"}
```
2017-08-10 11:18:22 -04:00
2018-04-21 17:01:55 -04:00
#### .SetInMap
Takes a `key` , `mapKey` and `value` and add a map of `mapKey` and `value` to the given `key` .
```go-html-template
{{ .Scratch.SetInMap "greetings" "english" "Hello" }}
{{ .Scratch.SetInMap "greetings" "french" "Bonjour" }}
----
{{ .Scratch.Get "greetings" }} > map[french:Bonjour english:Hello]
2017-08-10 11:18:22 -04:00
```
2018-04-21 17:01:55 -04:00
#### .GetSortedMapValues
Returns array of values from `key` sorted by `mapKey`
```go-html-template
{{ .Scratch.SetInMap "greetings" "english" "Hello" }}
{{ .Scratch.SetInMap "greetings" "french" "Bonjour" }}
----
{{ .Scratch.GetSortedMapValues "greetings" }} > [Hello Bonjour]
2017-08-10 11:18:22 -04:00
```
2018-04-21 17:01:55 -04:00
#### .Delete
Removes the given key
```go-html-template
{{ .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` .
2017-08-10 11:18:22 -04:00
[pagevars]: /variables/page/