How to safely truncate text to a specified length for articles containing HTML tags using `truncatechars_html`?

When using AnQiCMS to manage website content, we often encounter the following scenarios: In order to make the article content more aesthetically pleasing, various HTML tags are used to enrich the visual effects, such as paragraphs (<p>), and images (<img>), link (<a>）bold（<strong>However, on the article list page or in the related recommendation module, we often need to display the abstract or part of the content of these articles, but we cannot directly display the whole long article.

At this time, a common practice is to cut off the fixed length text at the beginning of the article.If directly simply to string truncation containing HTML tags, such as truncating the first 100 characters, the result is often not satisfactory.Because this rough cutting method may truncate HTML tags, causing rendering errors on the page, resulting in unclosed tags, chaotic styles, and even destroying the entire page layout.This not only affects the user experience, but may also cause compatibility issues with browsers.

To handle the need for elegantly and safely extracting article content with HTML tags, Anqi CMS provides a very practical template filter——truncatechars_html.

Why choosetruncatechars_html?

truncatechars_htmlThe core value of the filter lies in its ability to intelligently process HTML structures. It does not simply count characters like ordinary string truncation, but instead willparse HTML tagsIt will truncate the visible text to a specified length (excluding the characters of the HTML tags themselves) andautomatically close all unclosed HTML tagsThus ensuring that the output HTML code remains complete and valid.This means that you do not have to worry that truncated HTML content will destroy the layout or style of the page, it will try to maintain the semantic and visual integrity of the content.

How to use it in Anqi CMS templatetruncatechars_html?

In the AnQi CMS template system, usetruncatechars_htmlVery intuitive. You just need to apply it as a filter to the content variable you want to extract and specify the desired character length.

Its basic syntax is:{{ 变量名|truncatechars_html:长度|safe }}.

For example, on the article list page, you may need to display the abstract of each article. Suppose your article content is stored inarchive.Contenta variable, and you want to extract the first 120 visible characters as the abstract:

{# 假设我们正在遍历一个文章列表 archives #}
{% archiveList archives with type="page" limit="10" %}
    {% for item in archives %}
    <div class="article-item">
        <h2><a href="{{ item.Link }}">{{ item.Title }}</a></h2>
        <div class="article-summary">
            {# 安全地截取文章内容的前120个可见字符，并保持HTML结构完整 #}
            {{ item.Content|truncatechars_html:120|safe }}
        </div>
        <a href="{{ item.Link }}" class="read-more">阅读更多</a>
    </div>
    {% endfor %}
{% endarchiveList %}

Here, item.ContentIs the detailed content of the article, which may contain such as<p>这是文章的<strong>第一段</strong>内容。</p><img src="/image.jpg" alt="图片描述">this HTML.

1. truncatechars_html:120Will tell the system to截取前120个visible characters(HTML tags themselves are not counted in length), and intelligently close any tags that are opened at the cut-off point.
2. |safeThe filter isindispensablebecause of.truncatechars_htmlThe output is actually processed HTML code. The Anqi CMS template engine, for safety, defaults to escaping all output content (such as replacing<Convert<）。如果不加|safeThe HTML tags after truncation will be displayed as plain text, rather than being parsed by the browser, thereby losing the original style.

truncatechars_htmlexample of the working principle

Assuming you have the following HTML content:

<p>这是一段很长的文本，其中包含<strong>加粗</strong>和<a href="#">链接</a>，我们希望截取它的部分内容，同时保持格式。</p>
<p>第二段内容，可能也会被截取到。</p>

If you use{{ original_html_content|truncatechars_html:50|safe }}to cuttruncatechars_htmlit will calculate the visible characters, and then it may output something like this:

<p>这是一段很长的文本，其中包含<strong>加粗</strong>和<a href="#">链接</a>，我们希望截取它的部分内容，同时保持格式...</p>

It can be seen that although it is truncated after the link, but<a>and<strong>/<p>the tags are closed correctly, and an ellipsis is added at the end, (...It ensures the validity of HTML and the neatness of the page.

Application scenarios in practice

• List of articles/New summary:In the list of articles on blogs and news websites, display a brief summary of each article to guide users to click and read the full text.
• Product list/Introduction:On e-commerce product list pages, display the beginning part of the product detailed description while maintaining the style and link availability.
• Search results page:Search engine internal search results, providing a preview of relevant content fragments.
• Related recommendation module:At the bottom or sidebar of the article, other related articles are recommended, and their summaries are displayed.

By flexible applicationtruncatechars_htmlA filter that can greatly enhance the display effect and user experience of the Anqi CMS website, ensuring that even abstract content is presented in a professional and beautiful manner.

Frequently Asked Questions (FAQ)

1.truncatechars_htmlandtruncatecharsWhat is the difference? truncatecharsIs used for extracting plain text content, it simply truncates by character count without considering HTML tags.If used for content containing HTML, it is easy to truncate tags, causing the page to display incorrectly andtruncatechars_htmlIt will intelligently recognize HTML tags, ensuring that all opened tags are properly closed while extracting visible characters, thus outputting a valid HTML snippet.

2. Why do you need to addtruncatechars_htmlafter|safeFilter?The template engine of AnQi CMS defaults to escaping all output content for security reasons to prevent cross-site scripting attacks (XSS).truncatechars_htmlAlthough it will output a valid HTML fragment, but if it is not added|safefilter, the template engine will escape it again, for example, by converting<p>displayed as<p>.|safeIt explicitly tells the template engine: This content is safe, please parse and display it directly as HTML.

3. If my content is plain text, I can usetruncatechars_html?Can.truncatechars_htmlIt is also effective for plain text content, it treats it as HTML without tags and truncates it to the specified length. However, for plain text, it is more recommended to usetruncatecharsThe filter, as it is lighter and does not require HTML parsing, is more efficient. It is usually only needed when the content may contain HTML tags.truncatechars_html.