{{craftSnippets}}
Home Articles Plugins Starter theme Components on Github Gists About
  • Home
  • Articles
  • Truncating text with Twig macros in Craft CMS
Posted on Jul 11, 2019 by Piotr Pogorzelski

Truncating text with Twig macros in Craft CMS

Macro truncating text by words on github gists
Macro truncating text by characters on github gists

Notification

With Craft 3.5.10 update, truncate Twig filter was added.
This filter truncates text by number of characters without splitting worlds, and it is recommended to use it instead of macro truncating text by number of characters described in this article.
Macro truncating text by number of words is hovewer still relevant.

These Twig macros will allow you to truncate text - by a number of words or number of characters, without splitting words.
Table of contents:
  • Truncating text by a number of characters
    • Macro code
    • Technical details
  • Truncating text by a number of words
    • Macro code
    • Technical details
  • Truncating text with plugins
    • Wordsmith
    • Typogrify
    • Seomatic
  • Article update history

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 - ….

TAGS:
#macro
If you want to get latest updates on Craft CMS tutorials and components, follow me on Twitter or subscribe to RSS feed.
Quick links for this article:
Macro truncating text by words on github gists
Macro truncating text by characters on github gists
Articles on blog:
  • Frontend testing for Craft CMS websites with Codeception and Cypress
  • Building reactive Craft Commerce product page with Sprig plugin
  • Dynamically generated PDF attachments for Freeform submissions
  • Using template hooks in Craft CMS
  • Alpine JS modal component for Craft CMS
  • Using template UI elements to extend Craft CMS control panel
  • Matrix within a Matrix - possible solutions for Craft CMS
  • Universal email template for Craft CMS
  • Creating attributes table from entry fields in Craft CMS
  • Namespacing forms in Craft CMS
  • Creating map-based navigation for Craft CMS
  • Placeholder image macro for Craft CMS
  • Building AJAX contact form with Craft CMS
  • Using incognito field plugin for Craft CMS
  • Email footer creator made with Craft CMS
  • Infinite scrolling and lazy loading with Craft CMS
  • Using Javascript in Twig templates with Craft CMS
  • Twig templating tips and tricks for Craft CMS
  • Basic SEO functionality for Craft CMS
  • Working with dates in Craft CMS templates
  • Working with SVG images in Craft CMS templates
  • Responsive and lazy-loaded youtube videos with Craft CMS
  • Debugging and inspecting Twig templates in Craft CMS
  • Creating article excerpts with Twig component in Craft CMS
  • Adding favicons to Craft CMS website
  • Truncating text with Twig macros in Craft CMS
  • Universal language switcher for Craft CMS
  • Read time macro for Craft CMS
  • Using attr() function to render HTML attributes in Craft CMS
  • Building dynamic, AJAX based pagination for Craft CMS
  • How to add Disqus comments to Craft CMS website
  • Ellipsis pagination component for Craft CMS
  • Converting email addresses into links using Twig macro
  • Breadcrumb created from URL for Craft CMS
  • Best developer-oriented Craft CMS plugins
  • Search autocomplete component for Craft CMS
  • RSS feed - template component for Craft CMS
  • Testing emails sent by Craft CMS using Mailtrap
  • Quick edit link - Twig component for Craft CMS
  • Filtering entries in control panel using Searchit plugin
  • Fetching routes into Twig templates in Craft CMS


Frontend testing for Craft CMS websites with Codeception and Cypress

Building reactive Craft Commerce product page with Sprig plugin

Dynamically generated PDF attachments for Freeform submissions

Using template hooks in Craft CMS

Alpine JS modal component for Craft CMS

Using template UI elements to extend Craft CMS control panel

Matrix within a Matrix - possible solutions for Craft CMS

Universal email template for Craft CMS

Copyright ©2023 Piotr Pogorzelski