In website operation, maintaining the neatness and consistency of page content layout is crucial.Especially when we need to display article summaries, product descriptions, or news titles, the length of the original content is often inconsistent, which can easily lead to page layout errors and affect the user's reading experience.AnQiCMS provides very practical template filters that can help us easily truncate overly long text or HTML content, and automatically add ellipses, keeping the page always elegant.

Understanding the importance of text truncation

Imagine, in a list of articles, some summaries are very short, while others are up to several hundred words.If these summaries are not processed uniformly, short summary areas may appear hollow, and long summaries may burst the layout, even causing content overflow.This not only makes the page look unprofessional, but also makes it difficult for users to quickly browse information.Therefore, whether the content is plain text or contains various style tags of HTML, we need an intelligent way to control its display length and indicate to the user that the content has not ended with an ellipsis.

Text truncation tool in AnQiCMS

AnQiCMS's template system (similar to Django template engine) includes a variety of filters that can help us complete this task. ForPlain text contentThe truncation, we usually usetruncatecharsandtruncatewordsThese two filters.

  • truncatechars: This filter will be sorted according toCharacterTruncate text by number. For example, if you want to display only the first 50 characters of a text and add an ellipsis at the end, you can use it like this:

    {{ item.Title|truncatechars:50 }}

    It will truncate the original content to the specified number of characters, including the ellipsis. If the length of the original content is less than or equal to the specified number of characters, no ellipsis will be added and it will not be truncated.

  • truncatewordsIf you prefer to truncate text bywordsthe number of characters (which is more common in English content),truncatewordsThe filter would be a better choice. It would try to truncate at the word boundaries to avoid splitting words harshly.

    {{ item.Description|truncatewords:15 }}

    This code will truncate the description to the first 15 words and handle the ellipsis in the same way.

Handle content that includes HTML.

When we need to truncate content that itself contains HTML tags (such as bold, italic, links, etc.), we can directly usetruncatecharsortruncatewords可能会破坏 HTML 结构，导致页面显示异常，例如出现未闭合的标签。AnQiCMS 充分考虑了这一点，提供了专门用于处理 HTML 内容的过滤器：truncatechars_htmlandtruncatewords_html.

  • truncatechars_htmlThis filter is set totruncatecharsSimilar, but it will intelligently identify and retain the integrity of HTML tags.Even if truncation occurs within the tag, it will attempt to properly close the tag to ensure the output HTML is valid.

    {{ archive.Content|truncatechars_html:100|safe }}

    We set it herearchive.Contentto be appliedtruncatechars_htmlFilter, truncate content to 100 characters (including ellipsis), while maintaining the integrity of the HTML structure. Please note that after truncating the HTML content, in order to ensure that the browser correctly parses the HTML rather than displaying it as plain text, we also need to use it immediately following.|safeFilter.|safeTell the template engine that this content is safe and does not require HTML escaping.

  • truncatewords_htmlThe same applies if you need to truncate HTML content by word and want to maintain the integrity of the HTML structure, you should usetruncatewords_html.

    {{ product.RichDescription|truncatewords_html:30|safe }}

    This will truncate the rich text description of the product to 30 words and safely handle HTML tags.

Actual application scenarios and operation suggestions.

in AnQiCMS template files, these filters are usually associated witharchiveListorpageList等内容列表标签结合使用。例如，在一个文章列表页面，你可能需要展示每篇文章的标题和一小段摘要：

{% archiveList articles with type="page" limit="10" %}
    {% for item in articles %}
    <div class="article-item">
        <h3><a href="{{ item.Link }}">{{ item.Title|truncatechars:40 }}</a></h3>
        <div class="summary">
            {{ item.Description|truncatechars_html:80|safe }}
        </div>
        <a href="{{ item.Link }}" class="read-more">阅读更多</a>
    </div>
    {% empty %}
    <p>暂时没有文章发布。</p>
    {% endfor %}
{% endarchiveList %}

In this code block:

  • item.Title通常是纯文本，我们使用truncatechars:40Cutoff the title.
  • item.DescriptionIt may be rich text, and to avoid destroying the internal HTML format, we have chosentruncatechars_html:80and add|safeEnsure that the HTML tags can be rendered correctly.

By flexibly using these filters, we can precisely control the display length based on the specific design and content type of the page, effectively enhancing the visual tidiness and user experience of the website.

Common Questions (FAQ)

  1. 问：截断后的省略号可以自定义吗？例如改成“… [继续阅读]”？

    • 答：AnQiCMS 内置的truncate系列过滤器目前默认使用“…”作为省略号，并且无法直接通过参数修改。如果需要更复杂的提示文字，你可能需要结合 EnglishifDetermine the length of the content, then manually cut the string and concatenate custom prompt text.

  2. Q: If my content is relatively short and does not reach the truncation length, will an ellipsis still be displayed?

    • Answer: No.truncateSeries of filters (including)_htmlThe version is designed not to truncate nor to add an ellipsis when the length of the original content is less than or equal to the specified truncation length.They are only added when the content is actually truncated.

  3. 问：当我使用English后，HTML 标签内的属性（例如图片的truncatechars_html后，HTML 标签内的属性（例如图片的alt属性）会被影响吗？

    • Answer:truncatechars_htmlandtruncatewords_htmlThe filter design will try to retain the integrity of HTML tags and their attributes.It mainly focuses on content truncation and the correct closing of tags, usually does not actively modify the attribute values inside the tags.If the truncation point happens to be in the middle of an attribute value, the attribute value may be truncated, so it is necessary to weigh the truncation length when setting it.