How to control the number of characters displayed for the article abstract (Description) in the list and automatically add an ellipsis in AnQiCMS?

When operating website content, the display length of the article summary (Description) on the list page is crucial for the neatness of the page and the user experience.A long summary can make the page look bulky and difficult to browse quickly, while a short one may not attract readers to click.AnQiCMS as a rich-featured content management system, provides flexible template tags and filters, allowing us to easily achieve fine-grained control over the number of characters displayed in article summaries and automatically add elegant ellipses.

Understand the source of the article summary (Description)

In the AnQiCMS backend, when we publish or edit articles, we will usually see a 'Document Summary' or 'Document Description' field.This content is what we commonly call the article summary (Description).According to the document hints, it is recommended to keep the summary within 150 characters, even if it is not manually filled in, the system will automatically extract the first 150 characters of the article content as the summary.

However, this backend word limit mainly affects data storage and search engine optimization (SEO), and it will not directly affect the actual display length of the summary on the front-end list page.When displayed on the front end, the template will default to outputting the complete Description content, therefore, we need to further control it at the template level.

AnQiCMS template tag: article summary in the list

In AnQiCMS, we usually usearchiveListTag to get the list of article data and throughforLoop through these article items. Each article objectitemContainsDescriptionField, we can directly call to display the summary.

A basic article list template snippet might look something like this:

{% archiveList archives with type="page" limit="10" %}
    {% for item in archives %}
    <li>
        <h5><a href="{{item.Link}}">{{item.Title}}</a></h5>
        <p>{{item.Description}}</p> {# 此时显示的是完整的摘要内容 #}
        <span>{{stampToDate(item.CreatedTime, "2006-01-02")}}</span>
    </li>
    {% endfor %}
{% endarchiveList %}

As you can see,{{item.Description}}The full summary of the article will be output directly. In order to make the list page more beautiful and unified, we need to truncate the summary content here.

Introduce an efficient filter: accurately control the length of the summary.

The AnQiCMS template engine is built-in with powerful filter functions, which can handle various processing of output variables, including string truncation we need. Among them,truncatecharsandtruncatechars_htmlIs a powerful assistant for controlling the length of abstracts and automatically adding ellipses.

1. truncatechars: Suitable for plain text abstracts

   When the content of the article abstract is plain text and does not contain any HTML tags,truncatecharsThe filter is your ideal choice. It will truncate the string according to the number of characters you specify and automatically add an ellipsis at the end....)

   The usage method is very intuitive:{{ obj|truncatechars:number }}of whichobjIt is the variable you are processing.numberIs the number of characters you want to retain (including the ellipsis).

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

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

2. truncatechars_html: Handling rich text summary

   Considering that many article abstracts may contain bold, links, paragraphs and other HTML tags, it can be directly usedtruncatecharsThe HTML tag may be truncated, causing the page to display incorrectly. AnQiCMS providestruncatechars_htmlfilter.

   truncatechars_htmlThe intelligence lies in its ability to recognize and preserve the integrity of HTML tags, ensuring that the extracted content is still a valid HTML structure, thus avoiding page layout chaos.At the same time, it will also automatically add an ellipsis after being truncated.

   However, when usingtruncatechars_htmlWhen, there is a very important detail to note: you must combine|safeto use the filters together.|safeThe filter tells the template engine that this content is safe HTML, it does not need to be escaped, and can be rendered directly.Otherwise, the HTML tags after the cut will be displayed as plain text.

   Usage:{{ obj|truncatechars_html:number|safe }}.

   For example, the summary containing HTML should be truncated to 120 characters:

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

3. Other options:truncatewordsandtruncatewords_html

   If you prefer to truncate the summary by word count rather than character count (which is more common on foreign websites), AnQiCMS also providestruncatewordsandtruncatewords_htmlThese two filters. They have the same function astruncatecharsandtruncatechars_htmljust that the unit of truncation has become "word".

   For example:

   <p>{{item.Description|truncatewords:20}}</p>
   <p>{{item.Description|truncatewords_html:25|safe}}</p>
   

Practice in the template: code example

Let us apply these filters to the actual article list template.

{% archiveList archives with type="page" limit="10" %}
    {% for item in archives %}
    <div class="article-item">
        <h5><a href="{{item.Link}}">{{item.Title}}</a></h5>
        {# 假设文章摘要是纯文本，截取80个字符 #}
        <p class="article-description-text">{{item.Description|truncatechars:80}}</p>

        {# 假设文章摘要可能包含HTML标签，截取120个字符并安全渲染 #}
        {# 如果你的Description字段可能含有HTML，强烈推荐使用truncatechars_html和safe #}
        <div class="article-description-html">
            {{item.Description|truncatechars_html:120|safe}}
        </div>

        <span class="article-date">{{stampToDate(item.CreatedTime, "2006-01-02")}}</span>
        <a href="{{item.Link}}" class="read-more">阅读更多</a>
    </div>
    {% endfor %}
{% endarchiveList %}

Through the above examples, you can flexibly select the appropriate filters according to the actual content type and design requirements, and adjust the number of characters to be extracted.

Tips for optimizing summary display

• Maintain consistency:In the list page of the entire website, try to maintain consistency in the number of characters displayed in the article summary, which helps to enhance the overall beauty and professionalism of the page.
• Medium word count: It is not advisable to truncate text too short so that readers cannot understand the meaning of the abstract; nor should it be too long, as it loses the conciseness of the list page. Generally, it is recommended to be between 80-150 characters.
• Consider SEO:Although front-end truncation does not directly affect SEO, a reasonable summary length and quality is still an important factor in attracting user clicks.Ensure that the extracted summary accurately conveys the core content of the article.
• Multi-device testing:Test your list page on different devices (PC, mobile, tablet) to ensure that the summary displays well on various screen sizes and avoids unexpected formatting issues.

AnQiCMS provides powerful tools through its flexible template tags and filters to control the display of content on the front end for content operators.Master these skills to make your website content list more attractive and enhance the overall user experience.

Frequently Asked Questions (FAQ)

Q1: Why did I set a summary word limit (such as 150 words) in the background, but the full long content is still displayed in the article summary on the front page list?

A1: The summary word limit set in the background is mainly a suggestive constraint on the "document description" field stored in the database, as well as a reference when the search engine may crawl it in certain SEO scenarios.It does not directly control the display way of the content in the front-end template. The actual display length of the front-end list page needs to be changed by modifying the template file (for example, usingarchiveListLoop the tag output article and combinetruncatecharsortruncatechars_htmlManually control with filters such as

Q2: I usedtruncatechars_htmlFilters to extract the abstract, but the HTML tags on the page (such as<p>/<strong>How is it displayed directly instead of being rendered in style?

A2: This is usually because you forgot totruncatechars_htmlAdd after the filter|safeFilter. The AnQiCMS template engine, for security reasons, defaults to escaping all output HTML content to avoid potential XSS attacks.truncatechars_htmlAlthough it can intelligently extract HTML and maintain its structure, it still outputs it in string form. You need to explicitly use|safeThe filter tells the template engine that this HTML content is safe and can be directly parsed and rendered by the browser. The correct syntax is{{item.Description|truncatechars_html:120|safe}}.

Q3: In addition to character or word truncation, does AnQiCMS support controlling the length of the abstract based on the number of images in the abstract content or the number of specific HTML tags?

A3: AnQiCMS built-intruncatechars/truncatewordsIts HTML version filter mainly targets character and word count truncation.Currently, the default template tags and filters do not provide a direct way to control the summary length based on the number of images or the number of specific HTML tags.If your requirements are complex, you may need to handle it in the backend controller logic.DescriptionField for more complex processing, or through custom template functions or filters