In website content operation, we often need to display part of the content of articles, products, or single pages on list pages, summary areas, or specific sections.This content is often rich text containing HTML tags. If it is simply truncated by character count, it may lead to the truncation of HTML tags, thus damaging the layout and display effect of the page.<p>这是一个段落<strong id="test">中的加粗</str...</p>This content, if abruptly cut off, may cause the page to appear with unclosed tags<strong>which may affect the rendering of subsequent content.

To solve this difficult problem, AnQiCMS's template engine provides a feature namedtruncatechars_htmlThe powerful filter that can safely extract rich text content containing HTML tags and intelligently close all incomplete tags to ensure the integrity of the page structure.

HTML content source in AnQi CMS

Rich text content in AnQi CMS mainly comes from the following core fields:

  • Document content (Archive.Content): ThrougharchiveDetailTag retrieval, this is the main content of the article or product detail page.
  • Category.Content: ThroughcategoryDetailGet tags, used to display the detailed introduction of the category.
  • Page.Content: ThroughpageDetailLabel acquisition, such as "About Us

These fields are usually generated by the backend rich text editor and contain various HTML tags (such as<p>,<strong>,<a>,<img>In this case, it is necessary to be especially careful when extracting.

Knowtruncatechars_htmlFilter

truncatechars_htmlThe filter is specifically designed to handle strings containing HTML tags. Its core advantage lies in the fact that when you truncate text within a specified length,Automatic detection and closure of all truncated HTML tagsThis means you don't have to worry about the page element being disordered due to the slicing operation, or about browser parsing errors caused by unclosed tags.

such as simple string slicing filters (liketruncatechars）different,truncatechars_htmlThe filter can "understand" HTML structure. For example, a string containing<b>Bold text</b>is truncated in<b>Label within, it ensures that the final output HTML is still valid, for example<b>Bold...</b>Instead of leaving an open one,<b>Label. The end of the truncated content is usually appended with an ellipsis (…) to indicate that the content has been truncated.

how to use safelytruncatechars_html

Usetruncatechars_htmlThe filter is very intuitive, but it is important to pay attention to one important cooperative operation: 

{{ 你的HTML内容变量|truncatechars_html:截取长度|safe }}

Let us take an actual scenario as an example, assuming you need to display a brief summary of each article on the article list page, this summary is extracted from the full content (archive.Content) of the article:

{% archiveList articles with type="page" limit="10" %}
    {% for article in articles %}
    <div class="article-item">
        <h3><a href="{{ article.Link }}">{{ article.Title }}</a></h3>
        <div class="article-summary">
            {# 假设 article.Content 包含 HTML 标签 #}
            {%- archiveDetail articleContent with name="Content" id=article.Id %}
            {{ articleContent|truncatechars_html:120|safe }}
            {%- endarchiveDetail %}
            <a href="{{ article.Link }}" class="read-more">阅读更多 &gt;</a>
        </div>
    </div>
    {% endfor %}
{% endarchiveList %}

In the above code:

  1. articleContentThe variable stores the complete HTML rich text content of the article.
  2. truncatechars_html:120It willarticleContentExtract approximately 120 characters (including HTML tags and ellipses), and automatically close any truncated tags.
  3. |safeThe filter is a crucial step.The template engine of AnQi CMS defaults to escaping all output content for security reasons.|safe, eventruncatechars_htmlGenerated correct HTML, these HTML tags will also be escaped.&lt;p&gt;/&lt;strong&gt;displayed directly on the page, rather than rendered into the corresponding styles by the browser. Therefore,truncatechars_html.|safeIt is indispensable, it tells the template engine that this part of the content is safe HTML and can be output directly.

Practical scenarios and advanced considerations

  • List page summary:This is the most common application, for example, showing an overview of content in blog post lists, product catalogs, and other pages. By controlling截取长度, it can well adapt to different page layout and design requirements.
  • Word count optimization:The length of the excerpt should be determined according to the actual needs and design. Too long may lose the meaning of the abstract, and too short may make the content seem too fragmented.
  • truncatewords_htmlFilter:If you prefer to truncate by word count instead of character count, and also maintain the integrity of the HTML structure, you can usetruncatewords_htmla filter. For example{{ articleContent|truncatewords_html:30|safe }}Will extract approximately 30 words. The choice depends on your specific content and language habits.
  • Debugging and Checking:If the extracted content does not meet expectations, you can try usingdumpa filter to viewtruncatechars_htmlthe content and type of variables before and after filtering, which helps you locate the problem. For example{{ articleContent|dump }}Can print the original content to help check for format issues.
  • Default ellipsis:By default, it will be added after truncation...As an ellipsis.If customization is desired, although it is not explicitly stated in the documents of Anqi CMS, it is usually a fixed behavior in most Django-like template engines.

By巧妙运用truncatechars_htmlFilter, you can easily implement secure text clipping of rich text content in the Anqi CMS template, which can ensure the beauty of the page and maintain the integrity of the HTML structure, thereby providing users with a better browsing experience.

Common Questions (FAQ)

1. Why did I usetruncatechars_htmlFiltering applied, the text displayed on the page is<p>内容...</p>Is this HTML tag text, rather than the formatted content?

Because you may have forgotten totruncatechars_htmladd after the filter|safeFilter. The template engine of Anqi CMS defaults to escaping all HTML tags in the output content to prevent potential security risks (such as XSS attacks).|safeFilter explicitly tells the template engine that this part of the content is safely processed HTML, which can be rendered as HTML directly without escaping.

2.truncatechars_htmlandtruncatewords_htmlWhat are the differences between filters? Which one should I choose?

The main difference lies in the unit of truncation:

  • truncatechars_html: PressCharacterTruncate the number. It will count the specified number of characters from the beginning of the text and truncate when the limit is reached.
  • truncatewords_html: PresswordsIt extracts the number of words. It recognizes words in the text and truncates to the specified number of words.

Choose which one depends on your content type and display requirements. If your content is Chinese, it is usually cut by characters (truncatechars_html) is more commonly used; if it is English content, it is cut by words (truncatewords_html）It may be easier to maintain the integrity of meaning, as there are natural spaces between English words.

3. The content after truncation always ends with “…”, can I change this ellipsis?

Based on the current documents of Anqi CMS,truncatechars_htmlandtruncatewords_htmlThe ellipsis used by the filter by default is fixed “…”, and there is no parameter to directly modify this symbol.If you need different ellipses, you may need to process it by replacing other strings after truncation, but this will increase the complexity of the operation and may affect the safety of HTML tag closure, which is generally not recommended.In most cases, the default ellipsis is already able to well convey the information that content has been truncated.