In Anqi CMS template development, flexible handling of text and HTML content is a daily operation. When we need to process plain text content input by users, throughlinebreaksWhen converting a filter into an HTML structure with paragraphs and line breaks while also limiting its display length, a common problem often arises: afterlinebreaksCan the processed HTML content be used safely?truncatechars_htmlWhat if the filter truncates it?

The answer is yes, not only can it, but it is exactly thistruncatechars_htmlThe strength of filter design. Next, let's take a detailed look at the working mechanisms of these two filters, as well as how they elegantly complement each other.

linebreaksFilter: Converts plain text to HTML structure

first, linebreaksThe filter plays a very practical role in Anqi CMS templates. Its main function is to convert the newline characters in plain text into\n)<p>) and line break tags (<br/>)

Imagine if the backend editor entered multiple lines of text in the content field, separated by two newline characters between paragraphs, and simply used a single newline character within paragraphs.If not processed directly, the front-end page may only display a long string of unformatted text.linebreaksAfter the filter intervenes, it will convert such plain text content, by convention, into an easily readable HTML paragraph structure. Specifically:

  • Two consecutive newline characters will be parsed as a new HTML paragraph, wrapped by<p>...</p>.
  • A single newline character will be converted to the HTML<br/>tag to implement line breaks within the paragraph.

For example, an input like this:

这是第一段内容。
这里有段内换行。

这是第二段内容。

afterlinebreaksAfter processing, it will output something like the following HTML:

<p>这是第一段内容。<br/>这里有段内换行。</p>
<p>这是第二段内容。</p>

This conversion makes the plain text content have basic formatting and readability when displayed on the front end.

truncatechars_htmlFilter: Smartly truncate HTML

Let's take a look attruncatechars_htmlThis filter. Its core function is to truncate text based on the specified character count, but it is different from the ordinary text truncation. It can recognize and correctly handle HTML tags.This means it will not simply truncate at the character limit, causing HTML tags to not close or the structure to be destroyed.On the contrary, it will:

  • Calculate the number of visible characters, ignoring the characters occupied by the HTML tags themselves.
  • Intelligently close all open HTML tags at the truncation position, ensuring that the generated HTML is still valid and complete.
  • Automatically add an ellipsis at the end of truncated text (...Incomplete content indicated.

For example, if there is a piece of HTML content that is.<strong>安企CMS</strong>是一个<em>强大的</em>系统。We use.truncatechars_htmlTruncate it to 10 characters:.<strong>安企CMS</strong>是一个...It will close correctly.<strong>Tags, leaving no unclosed tags.

combining them:linebreakswithtruncatechars_htmlThe perfect match

Now let's return to our core issue: whenlinebreaksThe filter converts plain text to HTML,truncatechars_htmlCan it be truncated? The answer is yes, and this chained call is highly recommended.

Working principle:

  1. You provide the original plain text content, such as fromarchive.Descriptionthe field.
  2. linebreaksThe filter first processes this plain text, converting the line breaks to<p>and<br/>tags, generating anew, well-structured HTML fragment.
  3. This newly generated HTML fragment is passed totruncatechars_htmlfilter.
  4. truncatechars_htmlAfter the filter receives this HTML, it will intelligently identify and process these by its design principle,linebreaksGenerated HTML tags, while calculating the number of visible characters, ensure that all opened tags are properly closed at the truncation point (even if<p>The tag also ensures that it is properly closed). The final output is a text with a limited length but a complete HTML structure, accompanied by an ellipsis.

Here is an example:Assumearchive.DescriptionContains the following content:

安企CMS致力于提供高效解决方案。
它部署简单。
功能强大且易于扩展。

In the template, we can call it like this:

{{ archive.Description|linebreaks|truncatechars_html:30|safe }}

The output might be like this:

<p>安企CMS致力于提供高效解决方案。<br/>它部署简单。功能...</p>

You can see that even if the text contains bylinebreaksGenerated<p>and<br/>tag, truncatechars_htmlCan also handle properly, ensure that the output HTML is valid and meets the length requirements. It should be noted that due tolinebreaksandtruncatechars_htmlAll generate or process HTML, so it is necessary to add it to the output on the page|safeA filter to prevent HTML content from being escaped twice, resulting in tags being displayed directly instead of rendering their effects.

In this way, you can flexibly handle the original text entered by users in the Anqi CMS, first perform basic formatting, then elegantly truncate, so as to display standardized and beautiful content segments in scenarios such as list pages, summaries, etc.

Frequently Asked Questions (FAQ)

1. Why not use directly?truncatecharsThe filter is used to truncate text insteadtruncatechars_html? truncatecharsThe filter is designed to truncate plain text and does not recognize HTML tags. If you have gone throughlinebreaksUse the text directly on the processed (already generated HTML) texttruncatecharsIt may be cut off within HTML tags, causing the tag to be incomplete and thus damaging the HTML structure of the page, resulting in a chaotic display. Andtruncatechars_htmlIt exists just to avoid this kind of situation, it can intelligently handle HTML, ensuring that the truncated structure is complete.

2. If I want to truncate by word instead of character count and the content contains HTML, which filter should I use?AnQi CMS providestruncatewords_htmlA filter that performstruncatechars_htmlSimilar, but it is truncated by word count. Similarly, it will also intelligently identify and retain HTML structure.So, if your requirement is to truncate content containing HTML based on the number of words,truncatewords_htmlWill be your ideal choice. The method of use is the same astruncatechars_htmlfor example:{{ archive.Description|linebreaks|truncatewords_html:10|safe }}.

3. I used in the templatelinebreaksandtruncatechars_htmlbut the front-end displayed it directly<p>and<br/>tags, why is that?This is usually because you forgot to add|safeThe filter. Anqi CMS (and many template engines based on Django-like syntax) defaults to escaping all output in HTML to prevent XSS attacks. Whenlinebreaksandtruncatechars_htmlAfter generating the HTML code, if there is not|safeThese codes are safe, the template engine will treat them as plain text and escape them, causing the tags to be displayed directly. Plus|safeTell the template engine that 'this content is safe HTML and render it directly.'