diff --git a/_vendor/modules.txt b/_vendor/modules.txt index 026f7b129e..5ff5b9db18 100644 --- a/_vendor/modules.txt +++ b/_vendor/modules.txt @@ -1 +1,2 @@ # github.com/gohugoio/gohugoioTheme v0.0.0-20241119115653-b92d27ede3e1 + diff --git a/content/en/functions/hugo/Store.md b/content/en/functions/hugo/Store.md new file mode 100644 index 0000000000..0441af1639 --- /dev/null +++ b/content/en/functions/hugo/Store.md @@ -0,0 +1,124 @@ +--- +title: Store +linktitle: hugo.Store +description: Returns a global, persistent "scratch pad" to store and manipulate data. +categories: [] +keywords: [] +action: + related: + - methods/page/store + - methods/site/store + - functions/collections/NewScratch + returnType: maps.Scratch + signatures: [site.Store] +toc: true +--- + +The global `hugo.Store` function creates a persistent [scratch pad] to store and manipulate data. To create a locally scoped, use the [`newScratch`] function. + +[`Scratch`]: /functions/hugo/scratch/ +[`newScratch`]: /functions/collections/newscratch/ +[scratch pad]: /getting-started/glossary/#scratch-pad + +## Methods + +###### Set + +Sets the value of a given key. + +```go-html-template +{{ hugo.Store.Set "greeting" "Hello" }} +``` + +###### Get + +Gets the value of a given key. + +```go-html-template +{{ hugo.Store.Set "greeting" "Hello" }} +{{ hugo.Store.Get "greeting" }} → Hello +``` + +###### Add + +Adds a given value to existing value(s) 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. + +```go-html-template +{{ hugo.Store.Set "greeting" "Hello" }} +{{ hugo.Store.Add "greeting" "Welcome" }} +{{ hugo.Store.Get "greeting" }} → HelloWelcome +``` + +```go-html-template +{{ hugo.Store.Set "total" 3 }} +{{ hugo.Store.Add "total" 7 }} +{{ hugo.Store.Get "total" }} → 10 +``` + +```go-html-template +{{ hugo.Store.Set "greetings" (slice "Hello") }} +{{ hugo.Store.Add "greetings" (slice "Welcome" "Cheers") }} +{{ hugo.Store.Get "greetings" }} → [Hello Welcome Cheers] +``` + +###### SetInMap + +Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`. + +```go-html-template +{{ hugo.Store.SetInMap "greetings" "english" "Hello" }} +{{ hugo.Store.SetInMap "greetings" "french" "Bonjour" }} +{{ hugo.Store.Get "greetings" }} → map[english:Hello french:Bonjour] +``` + +###### DeleteInMap + +Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`. + +```go-html-template +{{ hugo.Store.SetInMap "greetings" "english" "Hello" }} +{{ hugo.Store.SetInMap "greetings" "french" "Bonjour" }} +{{ hugo.Store.DeleteInMap "greetings" "english" }} +{{ hugo.Store.Get "greetings" }} → map[french:Bonjour] +``` + +###### GetSortedMapValues + +Returns an array of values from `key` sorted by `mapKey`. + +```go-html-template +{{ hugo.Store.SetInMap "greetings" "english" "Hello" }} +{{ hugo.Store.SetInMap "greetings" "french" "Bonjour" }} +{{ hugo.Store.GetSortedMapValues "greetings" }} → [Hello Bonjour] +``` + +###### Delete + +Removes the given key. + +```go-html-template +{{ hugo.Store.Set "greeting" "Hello" }} +{{ hugo.Store.Delete "greeting" }} +``` + +## Determinate values + +The `Store` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content. + +If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop] variable: + +[noop]: /getting-started/glossary/#noop + +```go-html-template +{{ $noop := .Content }} +{{ hugo.Store.Get "mykey" }} +``` + +You can also trigger content rendering with the `ContentWithoutSummary`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example: + +```go-html-template +{{ $noop := .WordCount }} +{{ hugo.Store.Get "mykey" }} +``` diff --git a/content/en/methods/page/Store.md b/content/en/methods/page/Store.md index a81fa71a38..484c27fd5c 100644 --- a/content/en/methods/page/Store.md +++ b/content/en/methods/page/Store.md @@ -1,11 +1,14 @@ --- title: Store +linktitle: PAGE.Store description: Returns a persistent "scratch pad" on the given page to store and manipulate data. categories: [] keywords: [] action: related: - methods/page/scratch + - methods/site/store + - functions/hugo/store - functions/collections/NewScratch returnType: maps.Scratch signatures: [PAGE.Store] diff --git a/content/en/methods/shortcode/Scratch.md b/content/en/methods/shortcode/Scratch.md index fcfc99d538..811d9f9eeb 100644 --- a/content/en/methods/shortcode/Scratch.md +++ b/content/en/methods/shortcode/Scratch.md @@ -10,7 +10,17 @@ action: signatures: [SHORTCODE.Scratch] --- -The `Scratch` method within a shortcode creates a [scratch pad] to store and manipulate data. The scratch pad is scoped to the shortcode, and is reset on server rebuilds. +{{% deprecated-in 0.139.0 %}} +Use the [`SHORTCODE.Store`] method instead. + +This is a soft deprecation. This method will be removed in a future release, but the removal date has not been established. Although Hugo will not emit a warning if you continue to use this method, you should begin using `SHORTCODE.Store` as soon as possible. + +Beginning with v0.139.0 the `SHORTCODE.Scratch` method is aliased to `SHORTCODE.Store`. + +[`SHORTCODE.Store`]: /methods/shortcode/store/ +{{% /deprecated-in %}} + +The `Scratch` method within a shortcode creates a [scratch pad] to store and manipulate data. The scratch pad is scoped to the shortcode. {{% note %}} With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Scratch` method within a shortcode is obsolete. diff --git a/content/en/methods/shortcode/Store.md b/content/en/methods/shortcode/Store.md new file mode 100644 index 0000000000..f7be8c8d0a --- /dev/null +++ b/content/en/methods/shortcode/Store.md @@ -0,0 +1,29 @@ +--- +title: Store +description: Returns a "Store pad" scoped to the shortcode to store and manipulate data. +categories: [] +keywords: [] +action: + related: + - functions/collections/NewScratch + - methods/page/Store + - methods/site/Store + - functions/hugo/Store + returnType: maps.Store + signatures: [SHORTCODE.Store] +--- + +{{< new-in 0.139.0 >}} + +The `Store` method within a shortcode creates a [scratch pad] to store and manipulate data. The scratch pad is scoped to the shortcode. + +{{% note %}} +With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Store` method within a shortcode is mostly obsolete. + +[assign values to template variables]: https://go.dev/doc/go1.11#text/template +[`newScratch`]: /functions/collections/newScratch/ +{{% /note %}} + +[Store pad]: /getting-started/glossary/#scratch-pad + +{{% include "methods/page/_common/scratch-methods.md" %}} diff --git a/content/en/methods/site/Store.md b/content/en/methods/site/Store.md new file mode 100644 index 0000000000..b52d9a381c --- /dev/null +++ b/content/en/methods/site/Store.md @@ -0,0 +1,124 @@ +--- +title: Store +linktitle: site.Store +description: Returns a persistent "scratch pad" on the given site to store and manipulate data. +categories: [] +keywords: [] +action: + related: + - methods/page/store + - functions/hugo/store + - functions/collections/NewScratch + returnType: maps.Scratch + signatures: [site.Store] +toc: true +--- + +The `Store` method on a `Site` object creates a persistent [scratch pad] to store and manipulate data. To create a locally scoped scratch pad that is not attached to a `Site` object, use the [`newScratch`] function. + +[`Scratch`]: /methods/site/scratch/ +[`newScratch`]: /functions/collections/newscratch/ +[scratch pad]: /getting-started/glossary/#scratch-pad + +## Methods + +###### Set + +Sets the value of a given key. + +```go-html-template +{{ site.Store.Set "greeting" "Hello" }} +``` + +###### Get + +Gets the value of a given key. + +```go-html-template +{{ site.Store.Set "greeting" "Hello" }} +{{ site.Store.Get "greeting" }} → Hello +``` + +###### Add + +Adds a given value to existing value(s) 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. + +```go-html-template +{{ site.Store.Set "greeting" "Hello" }} +{{ site.Store.Add "greeting" "Welcome" }} +{{ site.Store.Get "greeting" }} → HelloWelcome +``` + +```go-html-template +{{ site.Store.Set "total" 3 }} +{{ site.Store.Add "total" 7 }} +{{ site.Store.Get "total" }} → 10 +``` + +```go-html-template +{{ site.Store.Set "greetings" (slice "Hello") }} +{{ site.Store.Add "greetings" (slice "Welcome" "Cheers") }} +{{ site.Store.Get "greetings" }} → [Hello Welcome Cheers] +``` + +###### SetInMap + +Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`. + +```go-html-template +{{ site.Store.SetInMap "greetings" "english" "Hello" }} +{{ site.Store.SetInMap "greetings" "french" "Bonjour" }} +{{ site.Store.Get "greetings" }} → map[english:Hello french:Bonjour] +``` + +###### DeleteInMap + +Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`. + +```go-html-template +{{ site.Store.SetInMap "greetings" "english" "Hello" }} +{{ site.Store.SetInMap "greetings" "french" "Bonjour" }} +{{ site.Store.DeleteInMap "greetings" "english" }} +{{ site.Store.Get "greetings" }} → map[french:Bonjour] +``` + +###### GetSortedMapValues + +Returns an array of values from `key` sorted by `mapKey`. + +```go-html-template +{{ site.Store.SetInMap "greetings" "english" "Hello" }} +{{ site.Store.SetInMap "greetings" "french" "Bonjour" }} +{{ site.Store.GetSortedMapValues "greetings" }} → [Hello Bonjour] +``` + +###### Delete + +Removes the given key. + +```go-html-template +{{ site.Store.Set "greeting" "Hello" }} +{{ site.Store.Delete "greeting" }} +``` + +## Determinate values + +The `Store` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content. + +If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop] variable: + +[noop]: /getting-started/glossary/#noop + +```go-html-template +{{ $noop := .Content }} +{{ site.Store.Get "mykey" }} +``` + +You can also trigger content rendering with the `ContentWithoutSummary`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example: + +```go-html-template +{{ $noop := .WordCount }} +{{ site.Store.Get "mykey" }} +``` diff --git a/go.mod b/go.mod index bbb1661275..ec4a1c3d0c 100644 --- a/go.mod +++ b/go.mod @@ -3,3 +3,4 @@ module github.com/gohugoio/hugoDocs go 1.23.3 require github.com/gohugoio/gohugoioTheme v0.0.0-20241119115653-b92d27ede3e1 // indirect +