github.com/lyeb/hugo@v0.47.1/docs/content/en/functions/scratch.md (about)

     1  ---
     2  title: .Scratch
     3  description: Acts as a "scratchpad" to allow for writable page- or shortcode-scoped variables.
     4  godocref:
     5  date: 2017-02-01
     6  publishdate: 2017-02-01
     7  lastmod: 2017-02-01
     8  keywords: [iteration]
     9  categories: [functions]
    10  menu:
    11    docs:
    12      parent: "functions"
    13  toc:
    14  signature: []
    15  workson: []
    16  hugoversion:
    17  relatedfuncs: []
    18  deprecated: false
    19  draft: false
    20  aliases: [/extras/scratch/,/doc/scratch/]
    21  ---
    22  
    23  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.
    24  
    25  `.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`.
    26  
    27  
    28  {{% note %}}
    29  See [this Go issue](https://github.com/golang/go/issues/10608) for the main motivation behind Scratch.
    30  {{% /note %}}
    31  
    32  {{% note %}}
    33  For a detailed analysis of `.Scratch` and in context use cases, see this [post](https://regisphilibert.com/blog/2017/04/hugo-scratch-explained-variable/).
    34  {{% /note %}}
    35  
    36  ## Get a Scratch
    37  
    38  From Hugo `0.43` you can also create a locally scoped `Scratch` by calling `newScratch`:
    39  
    40  ```go-html-template
    41  $scratch := newScratch
    42  $scratch.Set "greeting" "Hello"
    43  ```
    44  
    45  A `Scratch` is also added to both `Page` and `Shortcode`. `Scratch` has the following methods:
    46  
    47  #### .Set
    48  
    49  Set the given value to a given key
    50  
    51  ```go-html-template
    52  {{ .Scratch.Set "greeting" "Hello" }}
    53  ```
    54  #### .Get
    55  Get the value of a given key
    56  
    57  ```go-html-template
    58  {{ .Scratch.Set "greeting" "Hello" }}
    59  ----
    60  {{ .Scratch.Get "greeting" }} > Hello
    61  ```
    62  
    63  #### .Add
    64  Will add a given value to existing value of the given key. 
    65  
    66  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.
    67  
    68  ```go-html-template
    69  {{ .Scratch.Add "greetings" "Hello" }}
    70  {{ .Scratch.Add "greetings" "Welcome" }}
    71  ----
    72  {{ .Scratch.Get "greetings" }} > HelloWelcome
    73  ```
    74  
    75  ```go-html-template
    76  {{ .Scratch.Add "total" 3 }}
    77  {{ .Scratch.Add "total" 7 }}
    78  ----
    79  {{ .Scratch.Get "total" }} > 10
    80  ```
    81  
    82  
    83  ```go-html-template
    84  {{ .Scratch.Add "greetings" (slice "Hello") }}
    85  {{ .Scratch.Add "greetings" (slice "Welcome" "Cheers") }}
    86  ----
    87  {{ .Scratch.Get "greetings" }} > []interface {}{"Hello", "Welcome", "Cheers"}
    88  ```
    89  
    90  #### .SetInMap
    91  Takes a `key`, `mapKey` and `value` and add a map of `mapKey` and `value` to the given `key`.
    92  
    93  ```go-html-template
    94  {{ .Scratch.SetInMap "greetings" "english" "Hello" }}
    95  {{ .Scratch.SetInMap "greetings" "french" "Bonjour" }}
    96  ----
    97  {{ .Scratch.Get "greetings" }} > map[french:Bonjour english:Hello]
    98  ```
    99  
   100  #### .GetSortedMapValues
   101  Returns array of values from `key` sorted by `mapKey`
   102  
   103  ```go-html-template
   104  {{ .Scratch.SetInMap "greetings" "english" "Hello" }}
   105  {{ .Scratch.SetInMap "greetings" "french" "Bonjour" }}
   106  ----
   107  {{ .Scratch.GetSortedMapValues "greetings" }} > [Hello Bonjour]
   108  ```
   109  #### .Delete
   110  Removes the given key
   111  
   112  ```go-html-template
   113  {{ .Scratch.Delete "greetings" }}
   114  ```
   115  
   116  ## Scope
   117  The scope of the backing data is global for the given `Page` or `Shortcode`, and spans partial and shortcode includes.
   118  
   119  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`.
   120  
   121  
   122  
   123  
   124  [pagevars]: /variables/page/