diff --git a/docs/content/templates/functions.md b/docs/content/templates/functions.md index 10be0f7de..7dc5f32fe 100644 --- a/docs/content/templates/functions.md +++ b/docs/content/templates/functions.md @@ -662,6 +662,16 @@ e.g. * `{{slicestr "BatMan" 3}}` → "Man" * `{{slicestr "BatMan" 0 3}}` → "Bat" +### truncate + +Truncate a text to a max length without cutting words or leaving unclosed HTML tags. Since Go templates are HTML-aware, truncate will handle normal strings vs HTML strings intelligently. It's important to note that if you have a raw string that contains HTML tags that you want treated as HTML, you will need to convert the string to HTML using the safeHTML template function before sending the value to truncate; otherwise, the HTML tags will be escaped by truncate. + +e.g. + +* `{{ "this is a text" | truncate 10 " ..." }}` → `this is a ...` +* `{{ "Keep my HTML" | safeHTML | truncate 10 }}` → `Keep my …` +* `{{ "With [Markdown](#markdown) inside." | markdownify | truncate 10 }}` → `With Markdown …` + ### split Split a string into substrings separated by a delimiter. diff --git a/tpl/template_func_truncate.go b/tpl/template_func_truncate.go new file mode 100644 index 000000000..b5886edae --- /dev/null +++ b/tpl/template_func_truncate.go @@ -0,0 +1,156 @@ +// Copyright 2016 The Hugo Authors. All rights reserved. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package tpl + +import ( + "errors" + "html" + "html/template" + "regexp" + "unicode" + "unicode/utf8" + + "github.com/spf13/cast" +) + +var ( + tagRE = regexp.MustCompile(`^<(/)?([^ ]+?)(?:(\s*/)| .*?)?>`) + htmlSinglets = map[string]bool{ + "br": true, "col": true, "link": true, + "base": true, "img": true, "param": true, + "area": true, "hr": true, "input": true, + } +) + +type htmlTag struct { + name string + pos int + openTag bool +} + +func truncate(a interface{}, options ...interface{}) (template.HTML, error) { + length, err := cast.ToIntE(a) + if err != nil { + return "", err + } + var textParam interface{} + var ellipsis string + + switch len(options) { + case 0: + return "", errors.New("truncate requires a length and a string") + case 1: + textParam = options[0] + ellipsis = " …" + case 2: + textParam = options[1] + ellipsis, err = cast.ToStringE(options[0]) + if err != nil { + return "", errors.New("ellipsis must be a string") + } + if _, ok := options[0].(template.HTML); !ok { + ellipsis = html.EscapeString(ellipsis) + } + default: + return "", errors.New("too many arguments passed to truncate") + } + if err != nil { + return "", errors.New("text to truncate must be a string") + } + text, err := cast.ToStringE(textParam) + if err != nil { + return "", errors.New("text must be a string") + } + + _, isHTML := textParam.(template.HTML) + + if utf8.RuneCountInString(text) <= length { + if isHTML { + return template.HTML(text), nil + } + return template.HTML(html.EscapeString(text)), nil + } + + tags := []htmlTag{} + var lastWordIndex, lastNonSpace, currentLen, endTextPos, nextTag int + + for i, r := range text { + if i < nextTag { + continue + } + + if isHTML { + // Make sure we keep tag of HTML tags + slice := text[i:] + m := tagRE.FindStringSubmatchIndex(slice) + if len(m) > 0 && m[0] == 0 { + nextTag = i + m[1] + tagname := slice[m[4]:m[5]] + lastWordIndex = lastNonSpace + _, singlet := htmlSinglets[tagname] + if !singlet && m[6] == -1 { + tags = append(tags, htmlTag{name: tagname, pos: i, openTag: m[2] == -1}) + } + + continue + } + } + + currentLen++ + if unicode.IsSpace(r) { + lastWordIndex = lastNonSpace + } else if unicode.In(r, unicode.Han, unicode.Hangul, unicode.Hiragana, unicode.Katakana) { + lastWordIndex = i + } else { + lastNonSpace = i + utf8.RuneLen(r) + } + + if currentLen > length { + if lastWordIndex == 0 { + endTextPos = i + } else { + endTextPos = lastWordIndex + } + out := text[0:endTextPos] + if isHTML { + out += ellipsis + // Close out any open HTML tags + var currentTag *htmlTag + for i := len(tags) - 1; i >= 0; i-- { + tag := tags[i] + if tag.pos >= endTextPos || currentTag != nil { + if currentTag != nil && currentTag.name == tag.name { + currentTag = nil + } + continue + } + + if tag.openTag { + out += ("" + tag.name + ">") + } else { + currentTag = &tag + } + } + + return template.HTML(out), nil + } + return template.HTML(html.EscapeString(out) + ellipsis), nil + } + } + + if isHTML { + return template.HTML(text), nil + } + return template.HTML(html.EscapeString(text)), nil +} diff --git a/tpl/template_func_truncate_test.go b/tpl/template_func_truncate_test.go new file mode 100644 index 000000000..95368f83e --- /dev/null +++ b/tpl/template_func_truncate_test.go @@ -0,0 +1,82 @@ +// Copyright 2016 The Hugo Authors. All rights reserved. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package tpl + +import ( + "html/template" + "reflect" + "strings" + "testing" +) + +func TestTruncate(t *testing.T) { + var err error + cases := []struct { + v1 interface{} + v2 interface{} + v3 interface{} + want interface{} + isErr bool + }{ + {10, "I am a test sentence", nil, template.HTML("I am a …"), false}, + {10, "", "I am a test sentence", template.HTML("I am a"), false}, + {10, "", "a b c d e f g h i j k", template.HTML("a b c d e"), false}, + {12, "", "Should be escaped", template.HTML("<b>Should be"), false}, + {10, template.HTML(" Read more"), "I am a test sentence", template.HTML("I am a Read more"), false}, + {20, template.HTML("I have a Markdown link inside."), nil, template.HTML("I have a Markdown …"), false}, + {10, "IamanextremelylongwordthatjustgoesonandonandonjusttoannoyyoualmostasifIwaswritteninGermanActuallyIbettheresagermanwordforthis", nil, template.HTML("Iamanextre …"), false}, + {10, template.HTML("
IamanextremelylongwordthatjustgoesonandonandonjusttoannoyyoualmostasifIwaswritteninGermanActuallyIbettheresagermanwordforthis
"), nil, template.HTML("Iamanextre …
"), false}, + {13, template.HTML("With Markdown inside."), nil, template.HTML("With Markdown …"), false}, + {14, "Hello中国 Good 好的", nil, template.HTML("Hello中国 Good 好 …"), false}, + {15, "", template.HTML("AHello中国 Good 好的
"), nil, template.HTML("Hello中国 Good 好 …
"), false}, + {2, template.HTML("P1
P2
"), nil, template.HTML("P1 …
"), false}, + {3, template.HTML(strings.Repeat("P
", 20)), nil, template.HTML("P
P
P …
"), false}, + {18, template.HTML("test hello test something
"), nil, template.HTML("test hello test …
"), false}, + {4, template.HTML("abc d e
"), nil, template.HTML("abc …
"), false}, + {10, nil, nil, template.HTML(""), true}, + {nil, nil, nil, template.HTML(""), true}, + } + for i, c := range cases { + var result template.HTML + if c.v2 == nil { + result, err = truncate(c.v1) + } else if c.v3 == nil { + result, err = truncate(c.v1, c.v2) + } else { + result, err = truncate(c.v1, c.v2, c.v3) + } + + if c.isErr { + if err == nil { + t.Errorf("[%d] Slice didn't return an expected error", i) + } + } else { + if err != nil { + t.Errorf("[%d] failed: %s", i, err) + continue + } + if !reflect.DeepEqual(result, c.want) { + t.Errorf("[%d] got '%s' but expected '%s'", i, result, c.want) + } + } + } + + // Too many arguments + _, err = truncate(10, " ...", "I am a test sentence", "wrong") + if err == nil { + t.Errorf("Should have errored") + } + +} diff --git a/tpl/template_funcs.go b/tpl/template_funcs.go index fd3337454..596902fcd 100644 --- a/tpl/template_funcs.go +++ b/tpl/template_funcs.go @@ -2188,6 +2188,7 @@ func initFuncMap() { "title": title, "time": asTime, "trim": trim, + "truncate": truncate, "upper": upper, "urlize": helpers.CurrentPathSpec().URLize, "where": where, diff --git a/tpl/template_funcs_test.go b/tpl/template_funcs_test.go index 37f075a99..fd51e3a1a 100644 --- a/tpl/template_funcs_test.go +++ b/tpl/template_funcs_test.go @@ -157,6 +157,8 @@ substr: {{substr "BatMan" 3 3}} title: {{title "Bat man"}} time: {{ (time "2015-01-21").Year }} trim: {{ trim "++Batman--" "+-" }} +truncate: {{ "this is a very long text" | truncate 10 " ..." }} +truncate: {{ "With [Markdown](/markdown) inside." | markdownify | truncate 14 }} upper: {{upper "BatMan"}} urlize: {{ "Bat Man" | urlize }} ` @@ -228,6 +230,8 @@ substr: Man title: Bat Man time: 2015 trim: Batman +truncate: this is a ... +truncate: With Markdown … upper: BATMAN urlize: bat-man `