In website content operation, the display length of article abstracts or content introductions often needs careful control.Excessive content can affect the page layout and user experience, while a concise summary accompanied by an ellipsis can effectively guide users to click and read more details.AnQiCMS provides flexible template tags and filters, allowing us to easily implement this feature.

We often use in AnQiCMS templates,archiveListTags are used to cyclically display article lists, or througharchiveDetailTags to obtain the detailed information of a single article. In either case, the summary of the article is usually stored inDescriptionField. For example, in the article list, we use{{item.Description}}to obtain the summary of each article; on the article detail page, it is{{archive.Description}}[en] Now, our goal is to truncate these long strings and add an ellipsis at the end.

AnQiCMS's template system provides a very convenient filter to achieve this requirement. The most core tool istruncatecharsFilter.

UsetruncatecharsFilter extracts plain text strings

truncatecharsThe filter can truncate a string to the specified length and automatically add an ellipsis “…” at the end. This length includes the total number of characters, with the ellipsis counted.

The usage is very intuitive:

{{ 变量 | truncatechars:长度 }}

For example, if you want to truncate the article summary to 50 characters:

<p>{{ item.Description | truncatechars:50 }}</p>

So, ifitem.DescriptionThe content exceeds 50 characters and will be truncated. An ellipsis (...) will be added after the 47th character, with a total length of 50. If the content is less than 50 characters, truncatecharsNo operation will be performed, and the output will be the same.

Handle long strings containing HTML:truncatechars_html

Many times, the summary of an article may not be plain text, but may include<strong>/<em>/<a>Rich text content of HTML tags. If you directly use strings containing HTMLtruncatecharsThe content may cause the HTML tag to be truncated, thereby damaging the page structure or style.

To handle this situation elegantly, AnQiCMS providestruncatechars_htmlFilter.This filter will intelligently identify and retain the integrity of HTML tags, ensuring that the final output HTML is still valid while truncating the string.

Its usage method is similar totruncatecharssimilar:

{{ 变量 | truncatechars_html:长度 }}

For example:

<p>{{ item.Description | truncatechars_html:100 | safe }}</p>

Here,| safeThe filter is also crucial.truncatechars_htmlwill produce a string containing HTML tags, and| safeTell AnQiCMS template engine that this is a safe HTML snippet that can be rendered directly without HTML entity escaping.So that you can ensure that the HTML content extracted is displayed correctly.

practical application and **practice

Apply the above filter to your template to flexibly control content display.

1. Extract summary of articles on the list page

On the homepage or category list page of the website, it is often necessary to display a brief summary of multiple articles.

{% archiveList archives with type="list" limit="10" %}
    {% for item in archives %}
    <div class="article-card">
        <h3><a href="{{ item.Link }}">{{ item.Title }}</a></h3>
        {# 假设 item.Description 包含 HTML，并截取为 120 个字符 #}
        <p class="article-summary">{{ item.Description | truncatechars_html:120 | safe }}</p>
        <a href="{{ item.Link }}" class="read-more">阅读更多</a>
    </div>
    {% endfor %}
{% endarchiveList %}

2. The excerpt from the top description on the detail page.

In some article detail pages, you may want to display a brief summary before the main content of the article.

{% archiveDetail archive with name="Description" %}
<div class="post-intro">
    {# 假设 archive.Description 可能包含简单HTML，并截取为 150 个字符 #}
    <p>{{ archive | truncatechars_html:150 | safe }}</p>
</div>
{% endarchiveDetail %}

{# 文章主体内容 #}
<div class="post-content">
    {% archiveDetail articleContent with name="Content" %}
    {{ articleContent | safe }}
    {% endarchiveDetail %}
</div>

3. Smart judgment to avoid unnecessary ellipses

Sometimes, the abstract of the article itself is very short and does not need to be truncated. To avoid adding an ellipsis even if the content is short, we can combinelengthfilters andiftags for conditional judgment.

{% set raw_summary = item.Description %}
{% if raw_summary|length > 80 %} {# 判断原始字符串长度是否超过 80 #}
    <p>{{ raw_summary | truncatechars_html:80 | safe }}</p>
{% else %}
    <p>{{ raw_summary | safe }}</p> {# 如果不长，则原样输出 #}
{% endif %}

This handling method is more user-friendly and can enhance the reading experience of users.

Summary

Passtruncatecharsandtruncatechars_htmlThese powerful filters, the AnQiCMS template performs very flexible and efficient in handling long string truncation and ellipsis display. Depending on the nature of your content (plain text or rich text), choose the appropriate filter and combine| safeWith conditional judgment, you can easily meet diverse content display needs, making your website interface more tidy and professional.

Common Questions (FAQ)

  1. Q:truncatecharsandtruncatechars_htmlWhat is the essential difference between filters? Answer: truncatecharsThe filter is mainly used to truncate plain text strings, it simply truncates based on the number of characters without considering any HTML tags that may be present. If your content contains HTML, usetruncatecharsMay lead to label breakage, destroying the page structure.truncatechars_htmlIt is specifically designed to handle strings containing HTML tags, which intelligently recognizes and tries to maintain the integrity of HTML tags during extraction, ensuring that the output HTML is still valid and avoiding display anomalies on the page.

  2. What about the ellipsis “…” when truncating the length? Answer:Yes, you are intruncatecharsortruncatechars_htmlThe length set in the filter (for example)truncatechars:50of50The total number of characters, including the automatically added ellipsis “…”.This means that if you set the length to 50, the actual number of characters displayed will be 47, plus 3 ellipses.

  3. What about the English content of a multilingual website I am running?truncatecharsWhen extracting, words are often cut off. Is there a better method? Answer:For content in languages like English that use words as the basic unit, AnQiCMS providestruncatewordsandtruncatewords_htmlFilter. They work in the way thattruncatecharsandtruncatechars_htmlSimilar, but not truncated by character count, but by word count, which can avoid cutting a word in half and make the reading experience more natural. Chinese content, due to the lack of clear word delimiters, usually usestruncatecharsThe series filter is more suitable.