hugo/docs/content/extras/scratch.md

64 lines
2.4 KiB
Markdown
Raw Normal View History

2015-01-31 20:33:34 +00:00
---
aliases:
- /doc/scratch/
lastmod: 2015-08-02
2015-01-31 20:33:34 +00:00
date: 2015-01-22
menu:
main:
parent: extras
2015-02-09 15:52:52 +00:00
next: /extras/datafiles
2015-01-31 20:33:34 +00:00
prev: /extras/pagination
title: Scratch
weight: 80
---
`Scratch` -- a "scratchpad" for your node- or page-scoped variables. In most cases you can do well without `Scratch`, but there are some use cases that aren't solvable with Go's templates without `Scratch`'s help, due to scoping issues.
2016-03-21 10:10:57 +00:00
`Scratch` is added to both `Node` and `Page` and `Shortcode` -- with following methods:
2015-08-02 05:00:43 +00:00
* `Set` and `Add` takes a `key` and the `value` to add.
* `Get` returns the `value` for the `key` given.
* `SetInMap` takes a `key`, `mapKey` and `value`
* `GetSortedMapValues` returns array of values from `key` sorted by `mapKey`
2015-01-31 20:33:34 +00:00
2016-03-06 14:44:17 +00:00
`Set` and `SetInMap` can store values of any type.
For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the follwing adds will be appended to that list.
2015-01-31 20:33:34 +00:00
2016-03-21 10:10:57 +00:00
The scope of the backing data is global for the given `Node`, `Page` or `Shortcode`, and spans partial and shortcode includes.
Note that `.Scratch` from a shortcode will return the shortcode's `Scratch`, which in most casses is what you want. If you want to store it in the page scroped Scratch, then use `.Page.Scratch`.
2015-01-31 20:33:34 +00:00
## Sample usage
The usage is best illustrated with some samples:
```
{{ $.Scratch.Add "a1" 12 }}
{{ $.Scratch.Get "a1" }} {{/* => 12 */}}
{{ $.Scratch.Add "a1" 1 }}
{{ $.Scratch.Get "a1" }} // {{/* => 13 */}}
{{ $.Scratch.Add "a2" "AB" }}
{{ $.Scratch.Get "a2" }} {{/* => AB */}}
{{ $.Scratch.Add "a2" "CD" }}
{{ $.Scratch.Get "a2" }} {{/* => ABCD */}}
2016-03-06 15:36:46 +00:00
{{ $.Scratch.Add "l1" (slice "A" "B") }}
{{ $.Scratch.Get "l1" }} {{/* => [A B] */}}
{{ $.Scratch.Add "l1" (slice "C" "D") }}
2016-03-06 15:38:17 +00:00
{{ $.Scratch.Get "l1" }} {{/* => [A B C D] */}}
2016-03-06 15:36:46 +00:00
{{ $.Scratch.Set "v1" 123 }}
{{ $.Scratch.Get "v1" }} {{/* => 123 */}}
2015-08-02 05:00:43 +00:00
{{ $.Scratch.SetInMap "a3" "b" "XX" }}
{{ $.Scratch.SetInMap "a3" "a" "AA" }}
{{ $.Scratch.SetInMap "a3" "c" "CC" }}
{{ $.Scratch.SetInMap "a3" "b" "BB" }}
{{ $.Scratch.GetSortedMapValues "a3" }} {{/* => []interface {}{"AA", "BB", "CC"} */}}
2015-01-31 20:33:34 +00:00
```
**Note:** The examples above uses the special `$` variable, which refers to the top-level node. This is the behavior you most likely want, and will help remove some confusion when using `Scratch` inside page range loops -- and you start inadvertently calling the wrong `Scratch`. But there may be use cases for `{{ .Scratch.Add "key" "some value" }}`.
2015-01-31 20:33:34 +00:00