From 20555b1630765d68c4b6d6c90406483195935faf Mon Sep 17 00:00:00 2001 From: Cathal Garvey Date: Mon, 18 Jul 2016 23:14:05 +0100 Subject: [PATCH] Add `htmlEscape` and `htmlUnescape` template functions These functions allow trivial escaping and unescaping of HTML entities, and make it far easier to compose other functions for the creation of parameterised URLs. --- docs/content/templates/functions.md | 21 +++++++++++++++++++++ tpl/template_funcs.go | 18 ++++++++++++++++++ tpl/template_funcs_test.go | 14 ++++++++++++++ 3 files changed, 53 insertions(+) diff --git a/docs/content/templates/functions.md b/docs/content/templates/functions.md index 6ba0a896..9f449938 100644 --- a/docs/content/templates/functions.md +++ b/docs/content/templates/functions.md @@ -448,6 +448,27 @@ e.g. `{{ "I :heart: Hugo" | emojify }}` Takes a string of code and a language, uses Pygments to return the syntax highlighted code in HTML. Used in the [highlight shortcode](/extras/highlighting/). +### htmlEscape +HtmlEscape returns the given string with the critical reserved HTML codes escaped, +such that `&` becomes `&` and so on. It escapes only: `<`, `>`, `&`, `'` and `"`. + +Bear in mind that, unless content is passed to `safeHTML`, output strings are escaped +usually by the processor anyway. + +e.g. +`{{ htmlEscape "Hugo & Caddy > Wordpress & Apache" }} → "Hugo & Caddy > Wordpress & Apache"` + +### htmlUnescape +HtmlUnescape returns the given string with html escape codes un-escaped. This +un-escapes more codes than `htmlEscape` escapes, including `#` codes and pre-UTF8 +escapes for accented characters. It defers completely to the Go `html.UnescapeString` +function, so functionality is consistent with that codebase. + +Remember to pass the output of this to `safeHTML` if fully unescaped characters +are desired, or the output will be escaped again as normal. + +e.g. +`{{ htmlUnescape "Hugo & Caddy > Wordpress & Apache" }} → "Hugo & Caddy > Wordpress & Apache"` ### humanize Humanize returns the humanized version of an argument with the first letter capitalized. diff --git a/tpl/template_funcs.go b/tpl/template_funcs.go index c1221846..b04b3681 100644 --- a/tpl/template_funcs.go +++ b/tpl/template_funcs.go @@ -1775,6 +1775,22 @@ func querify(params ...interface{}) (string, error) { return qs.Encode(), nil } +func htmlEscape(in interface{}) (string, error) { + conv, err := cast.ToStringE(in) + if err != nil { + return "", err + } + return html.EscapeString(conv), nil +} + +func htmlUnescape(in interface{}) (string, error) { + conv, err := cast.ToStringE(in) + if err != nil { + return "", err + } + return html.UnescapeString(conv), nil +} + func init() { funcMap = template.FuncMap{ "absURL": func(a string) template.HTML { return template.HTML(helpers.AbsURL(a)) }, @@ -1803,6 +1819,8 @@ func init() { "gt": gt, "hasPrefix": func(a, b string) bool { return strings.HasPrefix(a, b) }, "highlight": highlight, + "htmlEscape": htmlEscape, + "htmlUnescape": htmlUnescape, "humanize": humanize, "in": in, "index": index, diff --git a/tpl/template_funcs_test.go b/tpl/template_funcs_test.go index eeffd46b..2d8f753b 100644 --- a/tpl/template_funcs_test.go +++ b/tpl/template_funcs_test.go @@ -93,6 +93,13 @@ eq: {{ if eq .Section "blog" }}current{{ end }} findRE: {{ findRE "[G|g]o" "Hugo is a static side generator written in Go." 1 }} hasPrefix 1: {{ hasPrefix "Hugo" "Hu" }} hasPrefix 2: {{ hasPrefix "Hugo" "Fu" }} +htmlEscape 1: {{ htmlEscape "Cathal Garvey & The Sunshine Band " | safeHTML}} +htmlEscape 2: {{ htmlEscape "Cathal Garvey & The Sunshine Band "}} +htmlUnescape 1: {{htmlUnescape "Cathal Garvey & The Sunshine Band <cathal@foo.bar>" | safeHTML}} +htmlUnescape 2: {{"Cathal Garvey &amp; The Sunshine Band &lt;cathal@foo.bar&gt;" | htmlUnescape | htmlUnescape | safeHTML}} +htmlUnescape 3: {{"Cathal Garvey &amp; The Sunshine Band &lt;cathal@foo.bar&gt;" | htmlUnescape | htmlUnescape }} +htmlUnescape 4: {{ htmlEscape "Cathal Garvey & The Sunshine Band " | htmlUnescape | safeHTML }} +htmlUnescape 5: {{ htmlUnescape "Cathal Garvey & The Sunshine Band <cathal@foo.bar>" | htmlEscape | safeHTML }} humanize 1: {{ humanize "my-first-post" }} humanize 2: {{ humanize "myCamelPost" }} humanize 3: {{ humanize "52" }} @@ -149,6 +156,13 @@ eq: current findRE: [go] hasPrefix 1: true hasPrefix 2: false +htmlEscape 1: Cathal Garvey & The Sunshine Band <cathal@foo.bar> +htmlEscape 2: Cathal Garvey &amp; The Sunshine Band &lt;cathal@foo.bar&gt; +htmlUnescape 1: Cathal Garvey & The Sunshine Band +htmlUnescape 2: Cathal Garvey & The Sunshine Band +htmlUnescape 3: Cathal Garvey & The Sunshine Band <cathal@foo.bar> +htmlUnescape 4: Cathal Garvey & The Sunshine Band +htmlUnescape 5: Cathal Garvey & The Sunshine Band <cathal@foo.bar> humanize 1: My first post humanize 2: My camel post humanize 3: 52nd -- 2.30.2