mirrors/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-04-29 07:00:31 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions 2
hugo/docs/content/functions/scratch.md
Bjørn Erik Pedersen 0373e43102 Squashed 'docs/' changes from 35abbc86..f887bd7b 
f887bd7b Add script to pull theme changes
e89bbb2f Update README
78155dec Merge commit '9301947b25099dd402065104b340b1a480906a74' as 'themes/gohugoioTheme'
9301947b Squashed 'themes/gohugoioTheme/' content from commit 7dd8a302
e7557a34 Remove gohugoioTheme submodule
a78bbe22 Add link to Go issue
31d1ef40 Add example for taxonomy terms with metadata
da978cc7 Fix links in Blackfriday extension documentation
950ad115 Fix reference to Blackfriday Extensions section
12d1d026 Add documentation for Blackfriday Extensions
8c2b8fb5 Fix explaination for uglyURLs config option
378aded7 Use community repository for Arch Linux installation guide
56455e7e Improve 0.26 release notes
be7db03a netlify: Build with the new 0.26
d430b2d3 Bump version to 0.26
61adaca0 releaser: Prepare repository for 0.27-DEV
abef29a6 releaser: Add release notes to /docs for release of 0.26
5937fe41 releaser: Bump versions for release of 0.26
033752f1 Merge commit 'e81208265b'
bec2bd12 Make the title case style guide configurable
f1739a44 Merge commit '50ec65fbe1'
a1aac0e5 helpers: Add support for French Guillemets
b8dc1592 doc: Merge commit '2c0d1ccdcd'
7b3e31b8 Merge commit '6dbde8d731'
a37e7201 Bump versions to 0.26-DEV

git-subtree-dir: docs
git-subtree-split: f887bd7b4e3e7c7e76cd63951e5b0d37d8fe0ac7
2017-08-10 14:58:09 +02:00

2.7 KiB
Raw Blame History

title description godocref date publishdate lastmod 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
functions
docs
parent
functions
false false
/extras/scratch/
/doc/scratch/

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.

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

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

  • 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

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 following adds will be appended to that list.

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 scroped Scratch, then use .Page.Scratch.

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 */}}

{{ $.Scratch.Add "l1" (slice "A" "B") }}
{{ $.Scratch.Get "l1" }} {{/* => [A B]  */}}
{{ $.Scratch.Add "l1" (slice "C" "D") }}
{{ $.Scratch.Get "l1" }} {{/* => [A B C D] */}}

{{ $.Scratch.Set "v1" 123 }}
{{ $.Scratch.Get "v1" }}  {{/* => 123 */}}

{{ $.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"} */}}

{{% 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" }}. {{% /note %}}