What is the essential difference between the `truncatechars` and `truncatewords` filters, and how should one choose?

In Anqi CMS template development, in order to better display content summaries or control page layouts, we often need to truncate text. At this point,truncatecharsandtruncatewordsThese two filters come into play. They can both help shorten long text and add an ellipsis at the end, but there is a fundamental difference in their truncation logic. Understanding these differences is crucial for selecting and using them correctly.

truncatechars: truncate to the character level

truncatecharsA filter, as the name implies, truncates according to the number of characters. When you set a numeric parameter for it, it counts from the beginning of the text until it reaches the specified number of characters, then truncates the text at that position and adds an ellipsis at the end (...Please note that this number parameter isincludeThe number of characters in the ellipsis.

Core characteristics:

1. Character counting is accurate:It does not care about the integrity of the word, every letter, number, symbol, and even a space is regarded as a character. For Chinese characters, it also counts them as a character unit.
2. The word may be truncated:Since it is truncated strictly according to the number of characters,truncatecharsIt may be truncated in the middle of a word, resulting in a slightly rigid display effect that does not conform to the natural reading habit.
3. HTML processing:When processing rich text content containing HTML tags, use directlytruncatecharsIt will destroy the HTML structure, causing the page to display abnormally. At this time, it should use its HTML-friendly versiontruncatechars_html.truncatechars_htmlIt will intelligently close unclosed HTML tags at truncation to ensure the integrity of the page structure.

Example:

Suppose there is a string"AnQiCMS是一个功能强大的CMS系统。" {{ "AnQiCMS是一个功能强大的CMS系统。"|truncatechars:10 }}It may outputAnQiCMS是....

And{{ "AnQiCMS是一个功能强大的CMS系统。"|truncatechars:15 }}Possible outputAnQiCMS是一个功....

If the content is HTML code, for example<p><strong>AnQiCMS</strong> 是一个内容管理系统。</p>, using{{ value|truncatechars_html:20 }}It will intelligently truncate and properly close tags, such as<p><strong>AnQiCMS</strong> 是一个内容...</p>.

truncatewordsTruncation by word units:

withtruncatecharsdifferent,truncatewordsThe filter is based on word truncation. It will break down the text content into individual words (usually separated by spaces), and then truncate according to the specified number of words and add an ellipsis at the end.

Core characteristics:

1. Keep the word intact: truncatewordsIt ensures that each word is complete without any omissions. It does not truncate words in the middle, thus ensuring the readability and naturalness of the text.
2. Not suitable for languages without spaces:This istruncatewordsThe most significant limitation when handling Chinese, Japanese, Korean (CJK) languages in Anqi CMS (or other template engines based on Western language logic). Since CJK languages do not have natural word spacing between words,truncatewordsIt often treats a continuous paragraph of Chinese text as a single "super long" word.This means that if you specify truncating 10 words, and your Chinese paragraph does not have spaces, it is very likely to return the entire paragraph because "10 words" to it is just one "super long word".
3. HTML processing:Similarly, when dealing with rich text content containing HTML tags, it should usetruncatewords_htmlversion. It can balance between maintaining word integrity and HTML structure integrity.

Example:

Suppose there is a string"AnQiCMS is a powerful Content Management System." {{ "AnQiCMS is a powerful Content Management System."|truncatewords:5 }}It will output.AnQiCMS is a powerful Content....

But if the string is Chinese"安企CMS是一个功能强大的内容管理系统。",{{ "安企CMS是一个功能强大的内容管理系统。"|truncatewords:5 }}It is likely to output安企CMS是一个功能强大的内容管理系统。(i.e., not truncated), because it treats the whole sentence as a single word.

If the content is HTML code, for example<p><strong>AnQiCMS</strong> is a Content Management System.</p>, using{{ value|truncatewords_html:5 }}It will intelligently truncate and properly close tags, such as<p><strong>AnQiCMS</strong> is a Content Management...</p>.

Essential difference and selection suggestions

How to choose?

• When you need to strictly control the total length of displayed characters (for example, in table cells, or to ensure SEO meta descriptions are precise to the character count, and you do not mind words being truncated), and your content may contain Chinese, Japanese, Korean, and other languages without space separation, please prioritize choosingtruncatechars.For Chinese string,truncatecharsit can provide a more intuitive and predictable truncation effect.
• When you are more concerned with the readability and semantic integrity of text, and do not want words to be truncated, and your content is mainly English or other languages separated by spaces, please prioritize the choicetruncatewords.It can provide users with a smoother reading experience, for example, in the summary of the article list.
• If you choose any truncation method, if your content is rich text (including HTML tags), please make sure to use the corresponding_htmlversion (i.e.truncatechars_htmlortruncatewords_html)This will prevent the page HTML structure from being damaged due to truncation.

In summary, understanding the underlying logic and the advantages and disadvantages of these two filters, especially their performance in handling different languages, can help you make wise choices in the content operation of Anqi CMS, thereby improving the display quality and user experience of the website content.

Frequently Asked Questions (FAQ)

1. Does the numeric parameter in the filter contain the length of the ellipsis (…)?Yes,truncatecharsandtruncatewordsAll numeric parameters set by the filterincludeThe ellipsis (}...The character length of. For example, if you settruncatechars:10, then the final text (including the ellipsis) will be at most 10 characters long.

2. If my content is in HTML format, use it directlytruncatecharsortruncatewordsWhat problems might there be?directlytruncatecharsortruncatewordsProcessing HTML content may destroy the structure of HTML tags. For example, a<strong>The tag may be truncated, but its closing tag</strong>was omitted, causing the page to display chaos. Therefore, when processing HTML content, be sure to use its corresponding HTML-friendly version:truncatechars_htmlandtruncatewords_htmlThey will intelligently close incomplete HTML tags.

3. The content of my website is mainly Chinese, which filter should be prioritized to truncate the article summary?For websites mainly containing Chinese content, it is usually recommended to usetruncatecharsortruncatechars_html. This is because Chinese words are not separated by spaces.truncatewordsThe filter treats a continuous block of Chinese text as a single 'big word', which may cause it not to truncate or unpredictable truncation behavior even if you set a smaller word count. AndtruncatecharsIt will truncate according to the actual character count (each Chinese character counts as one character), resulting in a more expected outcome.