How to automatically convert newline characters in multi-line text in AnQiCMS templates to HTML's `
` tag?

How to make the newline characters of multi-line text automatically display as HTML in the AnQiCMS template<br/>Tag?

In website content operation, we often encounter situations where it is necessary to display multi-line text, such as article summaries, product descriptions, or user comments, etc.This text content is typically created by pressing the Enter key during background editing.\nThe text is output directly to the HTML page, and the browser will not interpret it as a visual line break.On the contrary, HTML defaults to collapsing multiple spaces and line breaks into a single space, causing the originally line-formatted content to display as a long string of text.

To solve this problem, we need to convert the invisible newline characters in the text\nConvert to a line break tag that browsers can recognize<br/>. AnQiCMS's powerful template engine provides a simple and efficient 'filter' function that helps us easily achieve this transformation.

Understand the text processing filter in AnQiCMS templates

AnQiCMS's template engine borrows from Django template syntax, providing a variety of built-in filters to handle and format output content. For the need of line breaks in multi-line text, there are two very practical filters:linebreaksbrandlinebreaks.

1. linebreaksbrFilterThis filter is as intuitive as its name, it will replace each newline character in the text\ndirectly<br/>Label. This is very suitable for those who only need to display each line of text line by line, without needing additional paragraph formatting. Its effect is similar to the function in PHP.nl2brFunction.

2. linebreaksFilter linebreaksThe filter provides a more intelligent paragraph processing method. It will convert a single newline\nto<br/>However, if it encounters two consecutive newlines\n\n(usually indicating an empty line), it will convert it to<p>...</p>Paragraph tag, and use<br/>To handle single-line breaks within paragraphs. This is more suitable for scenarios where you need to format multi-line text content into HTML paragraphs.

How to apply these filters in AnQiCMS template?

Using these filters is very simple, just add them after the variable you need to process|过滤器名称Just do it.

Assuming we have a document description field obtained from the backgroundarchive.DescriptionIt includes multiple lines of text:

Example of background input content:

这是第一行文本。
这是第二行文本。

这是第三行文本，前面有一个空行。
第四行。

1. UselinebreaksbrThe filter implementation is simple line breaking

If you want the content to be displayed simply line by line, one line per line<br/>you can use the taglinebreaksbr:

<div class="description-content">
    {{ archive.Description|linebreaksbr|safe }}
</div>

The output HTML will be:

<div class="description-content">
    这是第一行文本。<br/>
    这是第二行文本。<br/>
    <br/>
    这是第三行文本，前面有一个空行。<br/>
    第四行。
</div>

2. UselinebreaksThe filter implements paragraph formatting

If you want content to be organized in paragraph form, text separated by blank lines becomes independent<p>Tags, and line breaks within paragraphs become<br/>thenlinebreaksFilters are a better choice:

<div class="description-content">
    {{ archive.Description|linebreaks|safe }}
</div>

The output HTML will be:

<div class="description-content">
    <p>这是第一行文本。<br/>
    这是第二行文本。</p>
    <p>这是第三行文本，前面有一个空行。<br/>
    第四行。</p>
</div>

3. Important|safeFilter: Avoid HTML tags from being escaped

While usinglinebreaksbrorlinebreaksAfter the filter, they will generate HTML tags (such as<br/>or<p>）。The AnQiCMS template engine, to prevent cross-site scripting (XSS) attacks, defaults to encoding all output content as HTML entities.<br/>such strings instead of actual line breaks.

To ensure that the generated HTML tags can be correctly parsed by the browser, we need to addlinebreaksbrorlinebreaksa filter after that, then add another one|safefilter.safeThe filter tells the template engine that this content is safe and does not require HTML entity encoding and can be output directly.

The correct usage is always:{{ 变量|过滤器|safe }}.

Error example (do not use)|safe):

{{ archive.Description|linebreaksbr }}

Possible output page content (note)<br/>It will be displayed as plain text):

这是第一行文本。<br/>
这是第二行文本。<br/>

Correct example:

{{ archive.Description|linebreaksbr|safe }}

What you will actually see in the browser:

这是第一行文本。
这是第二行文本。

Summary

Whether it is a simple inline line break or you want to format the text intelligently into an HTML paragraph, AnQiCMS provides thelinebreaksbrandlinebreaksFilters can meet your needs. Remember to add after using these filters to convert plain text to HTML tags.|safeA filter to ensure that the browser can correctly parse and render these tags, thereby making your multi-line text content presentable and clear on the front-end page.

---

Frequently Asked Questions (FAQ)

1. Why did I uselinebreaksbrFilter, but what is displayed on the page is<br/>text rather than actual line breaks?

This is likely because you forgot to add at the end of the filter chain|safeFilter. The AnQiCMS template engine defaults to encoding all output content as HTML entities to prevent security issues. When you uselinebreaksbrorlinebreaksThe filter has generated<br/>or<p>After the HTML tag, if not|safemarked as 'safe content', these tags will be encoded to<br/>or<p>Then display it on the page in plain text. Make sure your code is{{ 变量|linebreaksbr|safe }}.

2.linebreaksandlinebreaksbrWhat are the differences between filters? How should I choose?

The main difference lies in the way they handle blank lines.

• linebreaksbr: Convert each individual newline character\ndirectly to<br/>Label. It does not automatically create paragraphs<p>Label. If you just want to display each line of text independently, without any paragraph concept, or if your text is already wrapped in other block-level elements (such as<li>Thenlinebreaksbris the better choice.
• linebreaksTranslate a single newline character\nto<br/>Tag, but will convert consecutive two newline characters\n\n(Representing an empty line) converts to HTML paragraph tag<p>...</p>This makes the text look more like a structured paragraph. If you want the text to automatically form paragraphs and keep the line breaks within the paragraphs, thenlinebreaksis more appropriate.

Which filter to choose depends on the structure and style you want the content to be presented in.

Does this method apply to all multi-line text fields? Such as custom fields?

Yes, this method applies to any variable that stores multi-line text content in AnQiCMS, whether it is built-in or notarchive.Description/category.ContentOr you can customize the text field in the content model (textareafield. As long as the value of the variable contains\na newline character, you can use itlinebreaksbr|safeorlinebreaks|safeA filter to convert it to an HTML line break.