Jinja Truncate: filter function to shorten text

n

Using Jinja’s truncate Filter

nThe Jinja truncate filter is an indispensable tool for managing how text is displayed in templates. It allows you to shorten a long string to a specified length, preventing text from overflowing its container and ensuring a clean, consistent user interface. This is particularly useful for generating previews of articles, displaying brief descriptions, or sanitizing user-submitted content for display. By giving you control over the length and the truncation method, the truncate filter helps you create more polished and user-friendly web pages.nn

---

nn

How the Filter Works

nAt its core, the truncate filter takes a string and cuts it down to a specified length. The filter’s behavior is defined by its parameters, allowing for flexibility in how and where the text is shortened. It’s a non-destructive operation, meaning the original string remains unchanged, and the filter returns a new, truncated string.nnThe basic syntax is as follows:n

{{ my_text | truncate(length) }}

nBy default, if the string is longer than the specified length, the filter will append an ellipsis (...) to indicate that the text has been shortened.nn

---

nn

Understanding the Parameters

nThe truncate filter’s true power lies in its optional parameters, which allow for fine-grained control over the truncation process.n

n
• length (integer, default 255): This is the maximum number of characters allowed for the string. If the string is shorter than this length, it is returned unchanged.

n

• killwords (boolean, default False): This parameter is a crucial modifier for the truncation behavior.n
  n
  • When False (the default), the filter is “word-aware.” It will find the last full word that fits within the length limit and truncate the text there, ensuring that no words are cut in half.

  n

  • When True, the filter becomes “character-aware.” It will cut the text at the exact character limit, regardless of whether it splits a word. This is useful for fixed-width displays where every character space counts.

  n

  n

n

• end (string, default '...'): This allows you to customize the string that is appended to truncated text. You can replace the default ellipsis with any other string, such as a different symbol (…) or a link to “Read more.”

n

• leeway (integer, default 5): This is a tolerance margin that prevents a string from being truncated if it only slightly exceeds the specified length. For instance, if length is 20 and leeway is 5, a string of 23 characters will be returned in full, but a string of 26 characters will be truncated. This prevents unnecessary truncation of text that is “just over” the limit, which can improve readability.

n

nn

---

nn

Practical Examples in Action

nLet’s illustrate how these parameters work with a few practical scenarios.n

Example 1: Default Word-Aware Truncation

nThis is the most common use case for creating text previews.n

n
• Jinja2 Template:n

  <p>{{ "The quick brown fox jumps over the lazy dog." | truncate(20) }}</p>

  n

n

• Rendered HTML:n

  <p>The quick brown...</p>

  n

n

nThe filter correctly identified “brown” as the last word that fit within the 20-character limit and truncated the text before the word “fox.”n

Example 2: Character-Aware Truncation with killwords

nHere, we’ll force the filter to cut at the exact character count.n

n
• Jinja2 Template:n

  <p>{{ "The quick brown fox jumps over the lazy dog." | truncate(20, killwords=True) }}</p>

  n

n

• Rendered HTML:n

  <p>The quick brown fo...</p>

  n

n

nNotice how the word “fox” is cut in half to meet the precise character limit.n

Example 3: Customizing the Ellipsis and Leeway

nIn this example, we’ll use a different ending and prevent truncation for a slightly longer string.n

n
• Jinja2 Template:n

  <p>{{ "The quick brown fox" | truncate(20, end=' [read more]') }}</p>n<p>{{ "The quick brown fox" | truncate(20, leeway=10) }}</p>

  n

n

• Rendered HTML:n

  <p>The quick brown fox [read more]</p>n<p>The quick brown fox</p>

  n

n

nIn the first case, the ellipsis is replaced with a “read more” link. In the second, because the string’s length (20) is within the leeway of a 20-character limit, no truncation occurs.nn

---

nn

Summary of Key Benefits

nJinja’s truncate filter is a flexible and powerful tool for controlling text presentation. By providing options for word-aware or character-aware truncation, customizable endings, and a tolerance margin, it allows you to create highly responsive and visually appealing templates. Whether you’re generating content summaries or ensuring that a dynamic string fits within a fixed-width container, mastering the truncate filter will help you deliver a cleaner and more professional user experience.nn