From f264076f669ccb696e052d1707e87ea7917017ca Mon Sep 17 00:00:00 2001 From: bep Date: Sat, 31 Jan 2015 21:33:34 +0100 Subject: [PATCH] Add doc for Scratch --- docs/content/extras/pagination.md | 2 +- docs/content/extras/scratch.md | 42 +++++++++++++++++++++++++++++ docs/content/meta/release-notes.md | 1 + docs/content/templates/variables.md | 4 +++ 4 files changed, 48 insertions(+), 1 deletion(-) create mode 100644 docs/content/extras/scratch.md diff --git a/docs/content/extras/pagination.md b/docs/content/extras/pagination.md index 2b121b2ee..95c915b58 100644 --- a/docs/content/extras/pagination.md +++ b/docs/content/extras/pagination.md @@ -5,7 +5,7 @@ date: 2014-01-01 menu: main: parent: extras -next: /extras/highlighting +next: /extras/scratch prev: /extras/shortcodes title: Pagination weight: 80 diff --git a/docs/content/extras/scratch.md b/docs/content/extras/scratch.md new file mode 100644 index 000000000..9adef3a5a --- /dev/null +++ b/docs/content/extras/scratch.md @@ -0,0 +1,42 @@ +--- +aliases: +- /doc/scratch/ +date: 2015-01-22 +menu: + main: + parent: extras +next: /extras/highlighting +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. + + +`Scratch` is added to both `Node` and `Page` -- with the three methods `Set`, `Get` and `Add`. `Set` and `Add` takes a `key` and the `value` to add. Get returns the `value` for the `key` given. + +`Set` can store values of any type. `Add` accepts values that support Go's `+` operator. + +The scope of the backing data is global for the given `Node` or `Page`, and spans partial and shortcode includes. + +## 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.Set "v1" 123 }} +{{ .Scratch.Get "v1" }} {{/* => 123 */}} +``` + + diff --git a/docs/content/meta/release-notes.md b/docs/content/meta/release-notes.md index 69a22e296..17ef93c8f 100644 --- a/docs/content/meta/release-notes.md +++ b/docs/content/meta/release-notes.md @@ -41,6 +41,7 @@ A lot has happened since Hugo v0.12.0 was released. * `GroupByParamDate(key, format, order)` * The [shortcode](/extras/shortcodes/) handling is rewritten for speed and better error messages. Noticeable functional change is the distinction between `{{}}` (typically raw HTML) and `{{%/* */%}}` (Markdown) * Support for [cross-references](/extras/crossreferences/) +* `Scratch` -- [a "scratchpad"](/extras/scratch) for your node- and page-scoped variables * A new, generic Next/Prev functionality is added to all lists of pages (sections, taxonomies, etc.) * Add in-section [Next/Prev](/templates/variables/) content pointers * Several [configurable improvements related to Markdown rendering](/overview/configuration/#configure-blackfriday-rendering:a66b35d20295cb764719ac8bd35837ec): diff --git a/docs/content/templates/variables.md b/docs/content/templates/variables.md index db6268c3e..75764e80b 100644 --- a/docs/content/templates/variables.md +++ b/docs/content/templates/variables.md @@ -22,6 +22,8 @@ The following is a list of most of the accessible variables which can be defined for a piece of content. Many of these will be defined in the front matter, content or derived from file location. +**See also:** [Scratch](/extras/scratch) for page-scoped writable variables. + **.Title** The title for the content.
**.Content** The content itself, defined below the front matter.
**.Summary** A generated summary of the content for easily showing a snippet in a summary view. Note that the breakpoint can be set manually by inserting <!--more--> at the appropriate place in the content page. See [Summaries](/content/summaries/) for more details.
@@ -65,6 +67,8 @@ Take for example I'm using *tags* and *categories* as my taxonomies. The followi In Hugo, a node is any page not rendered directly by a content file. This includes taxonomies, lists and the homepage. +**See also:** [Scratch](/extras/scratch) for global node variables. + **.Title** The title for the content.
**.Date** The date the content is published on.
**.Permalink** The Permanent link for this node