How to extract an article abstract and add an ellipsis in AnQiCMS templates?

How to make the article list page both beautiful and informative is a common concern.通常，我们不会在列表页展示文章的完整内容，而是通过一小段“摘要”来吸引读者点击。To maintain the cleanliness and professionalism of the page, these summaries often need to be automatically truncated when exceeding a certain length and appended with an elegant ellipsis.

AnQiCMS as a powerful content management system, provides flexible tools in the template to help us meet this need.Below, let's discuss in detail how to extract the article abstract and display an ellipsis in AnQiCMS templates.

Source of abstract content:DescriptionField priority,ContentField secondary

In AnQiCMS, every article has two important content fields that can be used as the source of the abstract:

  1. Description(Document Summary)This is the most ideal source of summary.When publishing articles in the background, there is usually an 'Document Summary' input box, where you can manually fill in a concise text as a summary of the article.AnQiCMS official documentation also recommends keeping the document summary within 150 words.ContentExtract the first 150 characters as the default introduction from the field. This field is typically plain text or contains a small number of simple HTML tags.

  2. Content(Document content)：This is the full content of the article, which may include rich text, images, videos, and various HTML structures.DescriptionWhen the field is empty, we can fromContentExtracting a part of the field as a summary. ButContentThe field is rich text, and direct extraction may destroy the HTML structure, causing abnormal display of the page, so special handling is required.

Understood after understanding these sources, our strategy is to prioritize usingDescriptionfield when it is empty, then fromContentfield to intelligently extract.

Extract pure text summary:truncatecharsFilter

When you are sureDescriptionThe field is plain text, you can usetruncatecharsa filter to truncate content by character count and automatically add an ellipsis.

Usage:in article loop (usually)archiveListTags withinforloop), you can call it like this:

{{ item.Description|truncatechars:长度 }}

Among them,长度This is the total number of characters you want to display in the summary, which includes the characters occupied by the ellipsis (“…”).

Example:If you want the summary to display a maximum of 100 characters:

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

Ifitem.DescriptionThe content is 'This is an article about AnQiCMS template creation, which is very detailed and I hope it can help everyone.'This is just a test summary, to see how the excerpting effect is.This article is about AnQiCMS template creation, and the content is very detailed. It is hoped that it can help everyone.This is just a test summary, see the effect of the cut...

Process abstracts containing HTML:truncatechars_htmlFilter

When your abstract content comes fromContentfield (it is rich text), orDescriptionfield may contain HTML tags, use directlytruncatecharsMay truncate unclosed HTML tags, resulting in a chaotic page layout. At this time,truncatechars_htmlThe filter comes into play. It can intelligently extract HTML content while ensuring that all tags are properly closed, thus maintaining the integrity of the page structure.

Usage:

{{ item.Content|truncatechars_html:长度|safe }}

Here are two points to note:

  1. truncatechars_html:长度: This filter will truncate HTML content to the specified character length and intelligently close all open HTML tags.
  2. |safeThis is a crucial step!AnQiCMS's template engine defaults to HTML-escaping all output content to prevent XSS attacks.|safe，截取后的 HTML 标签（如<p>,<strong>）将作为纯文本显示，而不是被浏览器解析。加上|safeAfter that, the template engine will consider this content as safe, and render it in HTML format normally.

Example:If you want to extractContentto get the most 150 characters as a summary:

<div>{{ item.Content|truncatechars_html:150|safe }}</div>

even ifitem.Contentis a complex HTML fragment,truncatechars_htmlwill also be cautious when cutting, to ensure that such as<p>...</p>/<strong>...</strong>etc. tags are complete, and ellipses are added correctly.

Cut by words:truncatewordsandtruncatewords_htmlfilter (optional)

AnQiCMS also provides a filter for extracting summaries by word, which is particularly useful for English or other languages separated by spaces, to avoid cutting off the middle of a word, making the summary reading more natural.

  • truncatewordsEnglish for auto content,截取 according to word count.{{ item.Description|truncatewords:20 }}(截取 20 个单词)
  • truncatewords_html：for including HTML content, truncating by word count while maintaining HTML structure.{{ item.Content|truncatewords_html:25|safe }}(Truncating 25 words and safely rendering HTML)

实战应用：构建一个智能摘要显示逻辑

为了达到**效果，我们通常会结合使用上述方法，构建一个智能的摘要显示逻辑：优先显示DescriptionField, ifDescriptionis empty, thenContent截取并安全渲染字段，最后再加入一个默认文本作为最终的备选。

Below is a complete template code snippet showing how toarchiveListImplement this logic in the loop:

{% archiveList archives with type="list" limit="10" %}
    {% for item in archives %}
    <article class="article-item">
        <a href="{{ item.Link }}" class="article-thumb">
            {# 优先显示文章缩略图，如果没有则显示默认图 #}
            {% if item.Thumb %}
                <img src="{{ item.Thumb }}" alt="{{ item.Title }}">
            {% else %}
                <img src="/public/static/images/default-thumb.png" alt="默认图片">
            {% endif %}
        </a>
        <div class="article-info">
            <h3><a href="{{ item.Link }}">{{ item.Title }}</a></h3>
            <div class="article-meta">
                <span>发布日期：{{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
                <span>阅读量：{{ item.Views }}</span>
            </div>
            <p class="article-summary">
                {% if item.Description %}
                    {# 优先使用 Description 字段，并截取为 120 字符 #}
                    {{ item.Description|truncatechars:120 }}
                {% else %}
                    {# 如果 Description 为空，则从 Content 截取 150 字符并确保 HTML 安全 #}
                    {{ item.Content|truncatechars_html:150|safe|default:"暂无内容" }}
                {% endif %}
            </p>
            <a href="{{ item.Link }}" class="read-more">阅读更多 &raquo;</a>
        </div>
    </article>
    {% empty %}
    <p>抱歉，目前没有可供展示的文章。</p>
    {% endfor %}
{% endarchiveList %}

In this code block:

  • We first check:item.DescriptionIf there is content. If there is, use:truncatecharsTo cut it out.
  • Ifitem.DescriptionEmpty, we then use:item.ContentThroughtruncatechars_htmlPerform HTML safe truncation and add.|safeThe filter ensures that the content is correctly parsed.
  • Finally,|default:"暂无内容"As a safety net, ensure that evenContentIt can still display a friendly prompt if the content is cut off (for example, if the article content is too short or there is no content at all).

By using the above method, you can flexibly extract article abstracts in AnQiCMS templates and display them beautifully and securely on the list page, greatly enhancing the user browsing experience.

Common Questions (FAQ)

Q1：截取长度是否包含省略号的字符数？A1：是的，当您使用truncatecharsortruncatechars_htmlThe length you set for the filter will include the characters occupied by the ellipsis ("...") automatically added.For example, if you set the truncation length to 100, the total number of characters displayed in the summary (including ellipsis) will be 100.

Q2：为什么截取 HTML 内容时需要|safeFilter?A2