Truncating text with Twig macros in Craft CMS

This article describes two Twig macros that can be used to truncate text. The first macro truncates text by number of words and second by number of characters. Both ensure that truncated text does not end with split words.

Truncating text by a number of characters #

This macro truncates text to desired number of characters. Here's a summary of macro functionality:

• HTML is stripped from the text before truncating to avoid getting wrong characters count.
• Any split words are removed from the end of truncated string. Therefore, length argument passed to macro is actually the upper limit of truncated string length.
• Suffix is appended to truncated text. If text is short enough that it does not need to be truncated, suffix won't be added.
• suffix length is also used when calculating truncated text length - so sum of suffix length and truncated text length won't exceed limit.

Tip: if you want to have greater control of physical (pixel) width of your truncated text, you can use monospaced font. Each character in such font has the exact same length.

Macro code #

Here are parameters that can be passed to macro:

• text - string to truncate.
• length - desired length of truncated text - in a number of characters.
• suffix - appended at end of the truncated string - it's an optional parameter. Macro uses ellipsis - "…" by default.

{% macro truncateChars(text, length, suffix) %}
{% spaceless %}
{% autoescape false %}
{# settings #}
{% set defaultSuffix = '…' %}
{# logic #}
{% if text and length %}
{% set text = text|striptags %}
{% set suffix = suffix|default(defaultSuffix) %}
{% set stringy = create(
    "Stringy\\Stringy",
    [text]
) %}
{{ stringy.safeTruncate(length, suffix) }}
{% endif %}
{% endautoescape %}
{% endspaceless %}
{% endmacro %}

Technical details #

This macro uses internal Craft function safeTruncate to truncate text. It is part of Stringy library. Not every internal function of Craft if directly available in Twig templates - therefore we need to use create() to access it. You can read more about it on nystudio blog.

Whole macro is wrapped in {% autoescape false %} tag to ensure that potential HTML entities in text get properly displayed.

Truncating text by a number of words #

This macro truncates text to desired number of words. It can be less precise that truncating text by number of characters - because words can have varying length.

Here's summary of macro functionality:

• HTML is stripped from text before truncating to avoid getting wrong characters count.
• Suffix is appended to truncated text. If text is short enough that it does not need to be truncated, suffix won't be added.

Macro code #

Here are parameters that can be passed to macro:

• text - string to truncate.
• length - desired length of truncated text - in a number of words.
• suffix - appended at end of truncated string - it's an optional parameter. Macro uses ellipsis - "…" by default.

{% macro truncateWords(text, length, suffix) %}
{% spaceless %}
{% autoescape false %}
{# settings #}
{% set defaultSuffix = '…' %}
{# logic #}
{% if text and length %}
{% set suffix = suffix|default(defaultSuffix) %}
{% set text = text|striptags %}
{% set text = text|replace('/\\n/', '\n ') %}
{% set array = text|split(' ') %}
{% set arrayTruncated = array|slice(0, length) %}
{% set string = arrayTruncated|join(' ') %}
{% if array|length > length %}
    {% set string = string ~ suffix %}
{% endif %}
{% set string = string|replace('/\\n\\s/', '\n') %}
{{ string }}
{% endif %}
{% endautoescape %}
{% endspaceless %}
{% endmacro %}

Technical details #

In order to get the word count, text is split into an array of words using space as a delimiter. Since while using newline there is no space between two words, each newline has space appended to it by using replace filter and simple regular expression. Thanks to that, words can be split properly.

Now that we have an array of words, we can just shorten it using slice filter and put it back into a string using join. In the end, we remove all additional spaces appended to newlines.

Truncating text with plugins #

There are a couple of plugins that feature text truncating functionality.

Wordsmith #

Wordsmith is a powerful plugin, providing a vast array of string manipulation techniques. It can truncate text using its chop filter - by a number of characters, words or even number of paragraphs.

This filter has some interesting additional functionality compared to macros described in this article. It allows us to decide which HTML tags should be stripped from the text and which should stay - for example, we can decide to keep <strong> tag to keep parts of text bolded. If text is truncated in such a way that only opening HTML tag is left, plugin will automatically append closing tag to truncated text so HTML is valid.

Typogrify #

Typogrify is another powerful typography oriented plugin, but as far as truncating goes, it offers pretty much same functionality as macros described in this article.

It's truncateOnWord filter allows us to truncate by characters without slicing words and wordLimit truncates text by words.

Seomatic #

Seomatic - wait, what is SEO plugin doing there? Well, I thought i should mention this - Seomatic has internal truncateOnWord function that can be used in Twig templates. This function works exactly the same as in Typogrify.

Article update history #

• 7 june 2019 - added {% autoescape false %} to ensure that HTML entities in text get properly displayed. Changed default suffix from three dots to proper ellipsis - ….