In the template development of AnQi CMS, in order to better display content summaries or control page layouts, we often need to truncate text. At this time,truncatecharsandtruncatewordsThese two filters come into play.They can all help us shorten long texts and add an ellipsis at the end, but there are essential differences in their truncation logic. Understanding these differences is crucial for correct selection and application.

truncatechars: Truncation to the character level.

truncatecharsFilter, as the name implies, is a truncation based on 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 this position and adds an ellipsis (…) at the end....）。It should be noted that this numeric parameter isincludingthe number of characters of the ellipsis.

Core features:

  1. Character count is accurate:It does not care about the integrity of words, every letter, number, symbol, and even a space is considered a character. For Chinese characters, it also counts by character units.
  2. May truncate words:Truncated strictly by the number of characters,truncatecharsMay truncate in the middle of a word, resulting in a somewhat stiff display that does not conform to natural reading habits.
  3. HTML processing:When processing rich text content that includes HTML tags, use directlytruncatecharsIt will destroy the HTML structure, causing the page to display abnormally. At this time, it should be used with its HTML-friendly versiontruncatechars_html.truncatechars_htmlWill 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是....

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

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

truncatewordsTruncated by word units

Withtruncatecharsdifferent,truncatewordsThe filter truncates based on words.It will split the text content into individual words (usually separated by spaces), then truncate it to the specified number of words and add an ellipsis at the end.

Core features:

  1. Keep the word intact: truncatewordsIt will ensure that each word is complete without any missing parts. It will not truncate words in the middle, thus ensuring the readability and naturalness of the text.
  2. Not suitable for non-space languages:This istruncatewordsIn AnQi CMS (or other template engines based on Western language logic) when dealing with Chinese, Japanese, Korean (CJK) and other languages, the most significant limitation is. Due to the lack of natural space separation between words in CJK languages,truncatewords往往会把一整段连续的中文文本视为一个“超级长”的单词。This means that if you specify truncating 10 words, and your Chinese paragraph does not contain 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 handling rich text content containing HTML tags, it should usetruncatewords_htmlversion. It can achieve a 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 outputAnQiCMS is a powerful Content....

If the string is Chinese"安企CMS是一个功能强大的内容管理系统。",{{ "安企CMS是一个功能强大的内容管理系统。"|truncatewords:5 }}it is very likely to be 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>Use{{ 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 suggestions for selection

Features/Filter truncatechars/truncatechars_html truncatewords/truncatewords_html
截断单位 字符（包含空格、标点、中文字符） 单词（以空格分隔）
单词完整性 不保证，可能在单词中间截断 Ensure, always keep the word complete
Length accuracy High, precise control of the total number of characters (including ellipses) Low, depends on word length, actual number of characters is not accurate
Chinese support Good, character count, truncation is expected Poor, may treat a whole Chinese segment as a word, causing no truncation
HTML supported truncatechars_htmlGuarantee structure truncatewords_htmlGuarantee structure

How to choose?

  • When you need to strictly control the total length of displayed characters (such as in table cells, or to ensure precise character count for SEO meta descriptions, and 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 characters,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 in English or other languages separated by spaces, please prioritize choosingtruncatewords.It can provide users with a more smooth reading experience, such as in the summary of the article list.
  • No matter which truncation method you choose, if your content is rich text (including HTML tags), please make sure to use the corresponding_htmlversion (that is,truncatechars_htmlortruncatewords_html).This will avoid damaging the page HTML structure due to truncation.

In summary, understanding the underlying logic and respective 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 quality of website content presentation and user experience.

Common Questions and Answers (FAQ)

  1. Does the number parameter in the filter contain an ellipsis (…) and its length?Yes,truncatecharsandtruncatewordsAll number parameters set in the filterincludingthe trailing ellipsis (...The length of the character. For example, if you settruncatechars:10, then the final output text (including the ellipsis) will be a maximum of 10 characters long.

  2. If my content is in HTML format, it can be used directlytruncatecharsortruncatewordsWhat problems might arise?Directly use:truncatecharsortruncatewordsProcessing content in HTML format may disrupt the structure of HTML tags. For example, a<strong>The label may be truncated, but its closing tag</strong>is missed, causing the page to display in a chaotic manner. Therefore, when processing HTML content, please make sure to use the corresponding HTML-friendly version:truncatechars_htmlandtruncatewords_htmlThey will intelligently close incomplete HTML tags.

  3. The content of my website is mainly in Chinese, which filter should I prioritize to truncate the article summary?For websites mainly containing Chinese content, it is usually recommended to usetruncatecharsortruncatechars_html. This is because there are no spaces between Chinese words,truncatewordsThe filter will treat a continuous segment of Chinese text as a single "word", which may result in it not truncating, or truncating unpredictably, even if you set a smaller word count.truncatecharsIt will be truncated according to the actual character count (each Chinese character counts as one character), resulting in a more expected outcome.