How to use the `linebreaks` filter correctly within the `{% filter %}{% endfilter %}` block?

In the template development of Anqi CMS, we often need to display the plain text content entered in the background, such as article summaries, multi-line descriptions in product details, or user comments, in a way that is more in line with web reading habits.Directly output these plain text, you will find that the original line breaks are lost, and all the content is squeezed together, which seriously affects readability.linebreaksThe filter has become a powerful assistant in solving this problem, it can cleverly convert line breaks in plain text to standard HTML paragraphs and line break tags.

What islinebreaksFilter?

In simple terms,linebreaksA filter is a text processing tool, its core function is to intelligently convert the newline characters in plain text into HTML paragraph tags (\n)<p>) and line break tags (<br/>)

The specific working principle is:

1. If a text contains one or more consecutive blank lines (i.e., two or more newline characters),linebreaksit will wrap the text block between them with<p>...</p>tags to form independent paragraphs.
2. If the text only contains a single newline character (i.e., inline newline), it will convert it to<br/>a tag to force inline line break.

In this way, what you enter naturally in the background text box, with line breaks, can be beautifully presented on the front-end page, greatly enhancing the reading experience of the content.

Why in{% filter %}{% endfilter %}Using blocklinebreaks?

In the Anqi CMS template engine, filters can not only be applied to individual variables (such as{{ variable | linebreaks }}This can also act on a "block" that contains multi-line content or a complex structure. That is exactly{% filter %}{% endfilter %}The scene where the block takes effect.

When you need to unify the text content of a non-single variablelinebreaksWhen processing, for example, this content may contain static text, multiple dynamic variables, and even the output of other tags, using{% filter %}{% endfilter %}A block makes it very convenient and powerful. It allows you to wrap any content that you want to be processed by the filter inside this block and then apply the filter uniformly.

For example:Assume you have a footer declaration on a page, which includes copyright information and some multiline contact details.This content may be partially fixed text and partially from variables set by the system.{% filter linebreaks %}{% endfilter %}in the block.

How to use correctlylinebreaksBlock-level filter

UselinebreaksThe basic syntax of block-level filter is:

{% filter linebreaks %}
    你的多行纯文本内容，
    可以是静态文本，
    也可以包含 {{ 变量名称 }}，
    甚至可以是其他标签的输出。

    这里是另一个段落。
{% endfilter %}

However, there is a very important detail to note: The template engine of AnQi CMS defaults to automatically escaping all output HTML content to prevent cross-site scripting attacks (XSS). This means that iflinebreaksThe filter has generated<p>and<br/>Tags, and you have not performed any additional processing, these tags will be displayed on the page in plain text format (for example, you will see<p>Instead of a real paragraph).

In order tolinebreaksThe generated HTML tags can be correctly parsed and rendered by the browser, you need to use it in conjunction withsafefilter.safeThe filter tells the template engine that this content is safe and does not need to be HTML escaped.

Therefore, the correct and recommended usage is:

{% filter linebreaks | safe %}
    {# 假设 `system.SiteCopyright` 是从后台获取的多行版权信息 #}
    {{ system.SiteCopyright }}

    这是一段额外的静态多行说明。
    它可以是任何你想要格式化的纯文本。
    比如一个地址：
    北京市海淀区中关村大街1号
    安企CMS大厦10层
{% endfilter %}

withlinebreaksbrThe difference is:AnQi CMS also provideslinebreaksbrFilter. It islinebreakssimilar, but simpler: it just removes all line breaks\nto<br/>tags withoutlinebreakslike that.<p>Tags are used to create paragraphs. If you only need simple inline line breaks and do not need strict paragraph structure, thenlinebreaksbrit may be a better choice.

Actual application scenarios:

1. Article/Product Description:If your article or product description allows multiple lines of text to be entered in the background and you want to keep the line breaks when displayed on the front end,linebreaks | safeit is an ideal choice.
2. Custom multi-line text field:For example, if you define a multi-line text field for 'product features' in the content model, you want each feature to be on a separate line or paragraph.
3. Footer copyright or contact information:The website footer usually contains multiple lines of copyright statements, addresses, and usagelinebreaks | safewhich can maintain a neat layout.
4. Site closed prompt:The "shutdown prompt" content set in the background, if it needs to be displayed in multiple lines, it also applies.

By flexible applicationlinebreaksBlock-level filter, you can let the text content of the Anqi CMS website be presented to users in a more professional and readable way, greatly improving the user experience and content display effect.

FAQ

Q1: Why did I use{% filter linebreaks %}The filter, but the text on the page is still plain, without becoming paragraphs and line breaks? A1:This is likely because you did notlinebreaksAdd after the filter| safeFilter. The Anqi CMS template engine defaults to escaping all HTML content to ensure safety.linebreaksAlthough the filter has generated<p>and<br/>tags, but if they are not| safeMarked as “safe”, the template engine will escape and display it.<p>and<br/>The correct usage should be.{% filter linebreaks | safe %}.

Q2:linebreaksandlinebreaksbrWhat is the difference between filters? How should I choose according to my needs? A2:The main difference lies in the way they handle blank lines.

• linebreaksThe filter treats consecutive blank lines as paragraph separators, using blank lines between text blocks.<p>...</p>Tag encapsulates and converts<br/>. It is suitable for scenes that require structured paragraphs.
• linebreaksbrThe filter is simpler and more direct, it only replaces all line breaks in the text.\nReplace with<br/>Tag, it will not generate<p>Tag. If you just want to force line breaks in the text, without a strict HTML paragraph structure, thenlinebreaksbrIt is more suitable. Which one to choose depends on the exact HTML structure you want to present on the front end.

Q3:{% filter %}{% endfilter %}Can the block be nested? What is the order of operation for the filters if nested? A3: {% filter %}{% endfilter %}The block can be nested. When nesting exists, the filter is applied from the innermost to the outermost layer. This means the innermostfilterThe content within the block will first be processed by the specified filter, and then the output result will be used as the outer layerfilterThe input of the block, which is then processed by the outer filter, and so on. If you want to output HTML after processing by the inner filter and pass it to the outer filter or display it directly, don't forget to use it at the end of the inner filter chain| safeOtherwise, the inner generated HTML may be