How to convert multi-line text (including newline characters) in a template to an HTML paragraph or `
tag display?

In website content operations, we often encounter such situations: the back-end text input box allows users to input multiline text, such as article summaries, product descriptions, contact addresses, etc.When these multi-line texts containing line breaks are displayed in a website front-end template, if output directly, we will find that the original line breaks do not take effect, and all the text is squeezed into a single line.This is because the browser defaults to merging consecutive whitespace characters (including newline characters) into a single space.So, how can we elegantly convert these multiline text to HTML paragraphs in AnQiCMS<p>) or a newline character (<br/>) in the format so that it is displayed correctly on the page?

AnQiCMS uses a template engine syntax similar to Django, providing powerful filter functions to handle such issues. Among them,linebreaksandlinebreaksbrThese filters are specifically designed for this.

Understand the root cause: the browser's handling of newline characters.

Firstly, we need to understand why the direct output of multiline text does not work. When you enter:

第一行文字
第二行文字

第三行文字

This text is usually stored in the database as\n(Newline) Store. If you enter it directly in the template{{ item.Description }}Output, the browser will treat it as plain text. In the HTML standard, the browser will ignore most whitespace between tags, including newline characters.Therefore, the above text will be displayed as 'First line text Second line text Third line text', with all line breaks replaced by a space.In order to make line breaks take effect, we need to\nConvert to HTML in<br/>tags, or convert paragraphs into<p>.

AnQiCMS's solution:linebreakswithlinebreaksbrFilter

AnQiCMS provides two main filters to solve this problem, each with its focus:

1.linebreaksFilter: intelligently converts to paragraphs and line breaks

linebreaksThe filter works more intelligently. It recognizes consecutive newline characters:

• Two or more consecutive newline characters(A block of text separated by blank lines) will be converted to an HTML paragraph tag<p>...</p>.
• A single newline(A natural line break within the text) will be converted to an HTML line break tag<br/>.

This filter is very suitable for processing multi-line text that has paragraph concepts, such as detailed descriptions or summaries of articles, it can automatically generate a reasonable paragraph structure for the text content.

Usage example:

Assumearchive.DescriptionThe value is:

这是文章的第一段。

这是文章的第二段。
它包含一个内部换行。

Use it like this in the template:

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

Possible output HTML (if you forget):|safe):

<div class="description-area">
    <p>这是文章的第一段。</p>
    <p>这是文章的第二段。<br />它包含一个内部换行。</p>
</div>

Here is a key point: If you directly copy the code and run, you might find out that:<p>and<br/>The tag is displayed as plain text, not as actual line breaks. This leads to another important filter:safe.

2.linebreaksbrFilter: Simply converts to line breaks directly

linebreaksbrThe filter is simpler and more direct. It will convert each newlinein the text to HTML tags. It does not attempt to generate\n)HTML tags. It does not attempt to generate<br/>any content.<p>.

This filter is suitable for those who do not need complex paragraph structures and only need to display each line independently, such as contact addresses, project lists, poems, and so on.

Usage example:

Assumecontact.AddressThe value is:

广东省深圳市南山区
科技园深南大道10000号
某某大厦10层

Use it like this in the template:

<address>
    {{ contact.Address|linebreaksbr }}
</address>

Possible output HTML (if you forget):|safe):

<address>
    广东省深圳市南山区<br />科技园深南大道10000号<br />某某大厦10层
</address>

Similarly, there is also a problem with the escaping of tags.

Key security measures:safeFilter

whether it islinebreaksOrlinebreaksbrThey will all convert text content to HTML tags. The AnQiCMS template engine, for security reasons (to prevent cross-site scripting attacks XSS), defaults to escaping all output HTML content, that is,<to<,>to>EvenlinebreaksGenerated<p>or<br/>Tags, they will be escaped as strings and displayed on the page, rather than being parsed as HTML elements by the browser.

We must use to solve this problemsafefilter.safeThe filter explicitly tells the template engine that the content of this variable is 'safe' HTML, which does not need to be escaped and can be output directly.

The correct usage:

tolinebreaksorlinebreaksbrthe filter meetssafeUse filters in combination and make suresafeThe filter is the last in the chain of calls.

{# 使用 linebreaks 转换为段落和换行 #}
<div class="description-area">
    {{ archive.Description|linebreaks|safe }}
</div>

{# 使用 linebreaksbr 转换为纯换行 #}
<address>
    {{ contact.Address|linebreaksbr|safe }}
</address>

This way, you can see the text content displayed on the page in paragraphs or line breaks as expected.

Application scenarios and precautions

• Description or summary (archive.Description): Often contains multiple paragraphs, using{{ archive.Description|linebreaks|safe }}Can automatically generate paragraph structure.
• Product features or parameters (archive.FeaturesOr custom multi-line text field): If there are line breaks between features, but no strict paragraph structure.