How to ensure that multi-line text content imported from outside can be correctly rendered through the `linebreaks` filter in AnQiCMS?

In the daily operation of website content, we often encounter the need to import a large amount of text content from outside.Whether it is articles obtained in bulk through the content collection function or product descriptions imported through the API interface, these contents often contain the original newline characters.When this multiline text content is directly displayed in the AnQiCMS front-end template, a common problem may occur: the neatly segmented content in the text editor is all squished together on the web page, with all the text connected, seriously affecting the reading experience and the beauty of the page.The reason behind this is that browsers default to ignoring the original newline characters in text (such as\nor\r\n），unless they are converted to HTML paragraph tags（<p>）or newline tags（<br/>)

AnQiCMS as a powerful content management system fully considers these actual operational needs. Its built-in Django-style template engine provides a series of practical filters, one of which is specifically designed to handle the rendering of multi-line text.linebreaksfilter.

UnderstandinglinebreaksThe principle of the filter.

linebreaksThe core function of the filter is to intelligently convert the original newline characters in the text content into HTML tags. Specifically, it will perform the following conversion:

1. Single line newline conversion<br/>:If the text contains a single newline\n)linebreaksIt will be converted to an HTML line break<br/>.
2. Double line break transforms<p>:If the text contains two or more consecutive newline characters,linebreaksIt considers this to be the end of a paragraph and wraps the previous text block in<p>...</p>in the tag.

By this means,linebreaksThe filter can simulate the visual effects of paragraphs and line breaks in a text editor, allowing the imported text content to maintain its original structure and readability on the web.

Key steps: cooperate|safeusing a filter

While usinglinebreaksWhen using a filter, there is a crucial detail to note: that it must be used in conjunction with|safefilter was used. This is becauselinebreaksDuring the transformation process, a filter will generate HTML tags such as<p>and<br/>）。AnQiCMS's template engine, to prevent potential cross-site scripting attacks (XSS), defaults to encoding all output content with HTML entities.This means, if it is missing|safeWhen a filter, the browser will transform<p>Label shows as<p>,<br/>Label shows as<br/>Instead of parsing it as actual HTML elements.

Therefore, the correct usage is tolinebreaksThe filter marks the result as "safe", telling the template engine that the generated HTML is trustworthy and does not require encoding.

When to chooselinebreaksorlinebreaksbr

exceptlinebreaks，AnQiCMS also provides another related filterlinebreaksbr. The difference between them is:

• linebreaks:It pays more attention to paragraph structure. It will convert double line breaks to<p>Label, and convert a single newline character to<br/>. Suitable for text that needs clear paragraph division, such as article text, detailed introduction, etc.
• linebreaksbr:Perform a simple line break conversion. It will convert all line breaks to<br/>Tag, it will not generate<p>Label. Suitable for scenarios where text is needed to be separated by lines and does not require paragraph semantics, such as address information, brief lists, or code snippets.

Choose which filter, depending on the final effect you want the text to display on the page.

Actual operation example

Assuming you have already imported an article containing multi-line text using the content import feature, and stored it inarchivethe object'sContentIn the field. In your article detail template (usually{模型table}/detail.htmlor a custom document template), you can use it like thislinebreaksandsafeto correctly render the content:

<div class="article-content">
    {% archiveDetail articleContent with name="Content" %}
    {{ articleContent|linebreaks|safe }}
</div>

{# 如果您希望只进行简单的换行，不生成段落标签，可以使用 linebreaksbr #}
<div class="article-description">
    {% archiveDetail articleDescription with name="Description" %}
    {{ articleDescription|linebreaksbr|safe }}
</div>

In the above example,{% archiveDetail ... %}The tag is used to get the detailed content of the article. The original text obtainedarticleContentorarticleDescriptionis then processed through a|pass tolinebreaksorlinebreaksbrfilter before being passed on tosafeFilter, to ensure that the generated HTML tags can be correctly parsed and rendered by the browser.

By such simple processing, the multi-line text content you import externally can be presented in a tidy, expected format on the website built with AnQiCMS, greatly enhancing the professionalism and user experience of content display.

---

Frequently Asked Questions (FAQ)

1. Ask: Why did I uselinebreaksFilter, but it directly displayed on the page instead<p>and<br/>The text of HTML tags, not the rendered effect?

   • Answer:This is because you may have forgotten tolinebreaksafter the filter|safeFilter. The AnQiCMS template engine defaults to escaping all output HTML tags to prevent security issues.|safeThe filter tells the template engine that this part of the content is safe, and it does not need to be escaped, and can be parsed directly as HTML. Therefore, the correct usage is{{ 您的变量|linebreaks|safe }}.

2. Ask: My content has already been edited through the rich text editor, which includes images, links, and custom styles, and still needs to uselinebreaks?

   • Answer:In most cases, it is not necessary. Rich text editors (such as the built-in editor in AnQiCMS backend) have already formatted the text into content containing HTML tags while you are editing.This content will be stored as an HTML string after import, by AnQiCMS.If used againlinebreaksIt may try to reprocess existing HTML tags, leading to unnecessary conversions or display errors. For rich text content, you usually just need to use|safeThe filter to ensure that its HTML code is parsed correctly:{{ 您的富文本内容变量|safe }}.

3. Question: Besides the main article text, where else might multiline text content imported need to be used?linebreaksFilter?

   • Answer:Any plain text field imported from the outside may benefit fromlinebreaksFilter. This includes but is not limited to: product introduction and features on product detail pages, multi-line text fields in custom content models, and even some direct text descriptions filled in on single pages.If the content is in plain text form and you expect the newline characters to be converted to HTML effects, you can consider using it.