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

In website content operation, we often encounter such situations: the background text input box allows users to input multiline text, such as article introductions, product descriptions, contact addresses, etc.When these multi-line text containing newline characters are displayed in the website front-end template, if they are output directly, we will find that the newline characters do not take effect, and all the text is squeezed into one line.This is because the browser defaults to merging consecutive whitespace characters (including newline characters) into a single space.<p>), or a newline character ()<br/>) 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 two filters are specifically designed for this purpose.

Understand the root cause: how browsers handle newline characters

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

第一行文字
第二行文字

第三行文字

This text is usually stored in the database as\n(Newline) stored. If directly in the template{{ item.Description }}Output, the browser will treat it as plain text.In the HTML standard, browsers 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.\nconverted to HTML tags<br/>or convert paragraphs into<p>Label.

AnQiCMS solution:linebreaksWithlinebreaksbrFilter

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

1.linebreaksFilter: intelligently converts to paragraphs and line breaks

linebreaksThe filter works more intelligently. It identifies consecutive newline characters in the text:

• Two or more consecutive newline charactersThe text block separated by blank lines will be converted to HTML paragraph tags<p>...</p>.
• Single line break(which is the natural line break within the text line) will be converted to 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.

Example Usage:

Assumearchive.DescriptionThe value is:)

这是文章的第一段。

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

Here is how to use it in the template:)

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

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

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

There is a key point: If you copy the code and run it directly, you might find):<p>and<br/>Labels are displayed as ordinary text, rather than actual line breaks. This brings up another important filter:safe.

2.linebreaksbrFilter: Convert directly to line breaks

linebreaksbrThe filter is simpler and more direct. It will convert the text to HTML byeach newline character (\n)into the HTML tag. It does not attempt to generate<br/>any other kind of formatting.<p>Label.

This filter is suitable for scenarios that do not require complex paragraph structure and only need to display each line independently, such as contact addresses, project lists, poems, etc.

Example Usage:

Assumecontact.AddressThe value is:)

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

Here is how to use it in the template:)

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

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

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

Similarly, there is also a problem with tags being escaped.

Key security measures:safeFilter

WhetherlinebreaksOrlinebreaksbrThey 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,<Converted to<,>Converted to>This means that evenlinebreaksgenerated<p>or<br/>tags will be escaped into strings and displayed on the page, rather than being parsed as HTML elements by the browser.

To solve this problem, we must usesafeFilter.safeThe filter will explicitly tell the template engine that the content of this variable is 'safe' HTML, which does not require escaping and can be output directly.

The correct usage method:

tolinebreaksorlinebreaksbrFilter is related tosafeUse filters in combination and ensure thatsafeThe 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>

So, you can see the text content displayed correctly on the page in paragraphs or line breaks.

Application scenarios and precautions

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