In website content operation, we often need to truncate long articles displayed on list pages, summaries, or card views to maintain the page's cleanliness and consistency. However, when these contents contain HTML tags (such as paragraphs, ...<p>English<a>and bolding<strong>、Image<img>When a string is truncated simply, it often leads to problems: it may truncate the tag in the middle, causing the page to display incorrectly, or even destroy the entire page's HTML structure.

幸运的是，English CMS（EnglishCMS）深知这一痛点，在其强大的模板引擎中提供了truncatechars_htmlFilter, specifically designed to intelligently truncate text containing HTML content, while ensuring that all tags are properly closed, thereby avoiding common layout and structural errors.

Whytruncatechars_htmlIs it the key to truncating HTML content?

Imagine you have a rich text content with images and links, and you need to display only the first 100 characters on the homepage. If you simply use the string truncation feature, the result might be something like this:

<p>这是一段包含<b>重要信息<a href="...">的文...

This truncated HTML is invalid:<b>and<a>The tag is not closed.This can not only cause rendering errors in the browser, affect user experience, but may also have a negative impact on search engine optimization (SEO), because search engines tend to prefer to crawl well-structured and semantically clear pages.

truncatechars_htmlThe design intention of the filter is to solve this challenge. When truncating content, it does not simply cut off physically by the number of characters, butAutomatically parse HTML structure.It will act like a careful editor, truncating text when reaching the specified character limit, and also tracing back all opened but unclosed HTML tags in front, adding the correct closing tags for them.This way, regardless of how the content is truncated, the output HTML fragment is always complete and valid.

truncatechars_htmlWorking principle (simplify complexity)

Its core lies in an embedded HTML parser. When content flows throughtruncatechars_htmlThe parser will track all open HTML tags in real-time when filtering.Once the character count reaches the preset truncation length, it will immediately stop outputting the text content.<div>a tag, a<p>tag, and a<strong>The label is still in the "open" state), then close them one by one in the correct order.Finally, a truncated but structurally complete HTML fragment will appear before you.

For example, if you have the following HTML content:<div><p>你好，<b>世界</b>！这是一段很长的文本。</p><a href="#">点击这里</a></div>If set to truncate to 15 characters,truncatechars_htmlit might output something like:<div><p>你好，<b>世界</b>！这是...</p></div>Note,<a>The label is omitted directly because it is not within the truncation range and is not unclosed.<div>/<p>and<b>All tags are properly closed.

The actual application in the AnQi CMS template

In the template files of Anqi CMS, usetruncatechars_htmlThe filter is very intuitive. Usually, we would combinesafefilters to use becausetruncatechars_htmlThe output result is still an HTML string, needsafea filter to indicate that the template engine should render it as safe HTML, rather than escaping it.

Assuming you need to display the summary of an article and limit it to 100 characters:

{# 假设 item.Content 包含了 HTML 格式的文章内容 #}
<div class="article-summary">
    {{ item.Content|truncatechars_html:100|safe }}
    <a href="{{ item.Link }}" class="read-more">阅读更多</a>
</div>

In this example:

  • item.ContentIt is the complete HTML content of your article.
  • truncatechars_html:100Truncate content to 100 characters (including an ellipsis).
  • |safeEnsure that the truncated HTML content is correctly parsed and rendered by the browser.

Comparison with other truncation filters

The Auto CMS also provides other truncation filters, understanding their differences can help you choose better:

  • truncatechars：适用于纯文本内容。它简单地按字符数截断，不会考虑 HTML 标签，如果用于 HTML 会导致标签破损。
  • truncatewordsAlso applies to plain text content. It truncates by word count, not character count.
  • truncatewords_html: withtruncatechars_htmlIt is similar, but it truncates by word count and also ensures proper closure of HTML tags.If your requirement is to truncate HTML content by 'word' rather than 'character', it would be a better choice.

Brings significant advantages

Usetruncatechars_htmlThe benefits of the filter are multifaceted:

  1. Integrity of page layout：Always output valid HTML, avoid page confusion caused by unclosed tags.
  2. Enhance user experience：The summary content seen by the user is neat and professional, without any乱码 or broken layout.
  3. Beneficial for Search Engine Optimization (SEO)：Keep the page HTML structure valid, which helps search engines better crawl and index content.
  4. Enhance development efficiencyAutomatically handles the complexity of HTML truncation, reducing the workload of manual checking and repairing invalid HTML.

Summary

truncatechars_htmlThe filter is a very practical feature provided by AnQi CMS in content presentation.It not only simplifies the display of abstracts with HTML content, but more importantly, it fundamentally solves the structural problems caused by truncating HTML content through an intelligent tag closing mechanism, ensuring that the website content is always presented to visitors in a professional, beautiful, and effective manner.In content operation and template development, proficiently using this filter will greatly enhance the quality and maintenance efficiency of the website.

Common Questions (FAQ)

1. If my original HTML content already has unclosed tags or structural errors,truncatechars_htmlcan it still work normally and fix these errors?

truncatechars_htmlThe main function of the filter is to ensure that it *itself* does not destroy the original HTML structure during truncation and will close all unclosed tags before the truncation point. If the original HTML content itself has serious structural errors (such as incorrect tag nesting, illegal attribute values, etc.),truncatechars_htmlUnable to fix these pre-existing errors.It will try to process it, but its validity will depend on the quality of the original input.To**effect, it is recommended to ensure the validity of HTML before publishing content.

2.truncatechars_htmlCan the default ellipsis “…” be modified after truncation?

According to the document description of Anqi CMS and the practice of common template engines,truncatechars_htmlThe ellipsis used by the filter by default is “…”, and this character is usually not directly modifiable through the filter parameters.If indeed you need to customize the ellipsis, you may need to perform additional string replacement operations in the template, which will increase complexity and may affect performance.It is generally recommended to follow the default ellipsis to maintain consistency.

3.truncatechars_htmlWhen truncating, will the character length of the HTML tag itself be calculated? For example,<p>How many characters?

truncatechars_htmlThe filter will only calculate the character length ofvisible text contentThe character length, but will not include the HTML tags (such as<p>/<a>) themselves and their attributes. This means that you set100An auto character limit refers to the actual text characters that a user can see, not the length of the string that includes all tag codes. This makes the truncation length more in line with human reading expectations.