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

In daily website content operations, we often encounter situations where we need to import a large amount of text content from the outside.Whether it is articles obtained in batches through the content collection feature or product descriptions imported through the API interface, these contents often contain original newline characters.When this multi-line text content is displayed directly in the AnQiCMS front-end template, a common problem may occur: the content that is neatly segmented in the text editor is all crammed together on the web page, with all the text connected, which seriously affects the reading experience and the beauty of the page.\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 such actual operational needs. Its built-in Django-style template engine provides a series of practical filters, among which there is a special one for handling the rendering of multi-line text.linebreaksFilter.

UnderstandinglinebreaksThe working principle of the filter

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

1. Single-line newline conversion<br/>:If there is a single newline character in the text,\n)linebreaksit will be converted to an HTML newline tag.<br/>.
2. Double line breaks to<p>:If there are two or more consecutive newline characters in the text,linebreaks【en】It will consider this as the end of a paragraph and wrap the previous text block inside<p>...</p>the tag.

In this way,linebreaksThe filter can simulate the visual effects of paragraphs and line breaks in text editors, so that the imported text content can also maintain its original structure and readability on web pages.

Key steps: coordinate with|safeFilter usage

When usinglinebreaksWhen using the filter, there is a crucial detail to note: that it must be used in conjunction with|safethe filter. This is becauselinebreaksThe filter will generate HTML tags (such as <p>and<br/>）。AnQiCMS template engine defaults to HTML entity encoding all output content to prevent potential cross-site scripting (XSS) attacks.|safeFilter, the browser will display<p>label as<p>,<br/>label as<br/>, rather than parsing it as an actual HTML element.

Therefore, the correct usage is tolinebreaksThe results generated by the filter are marked as “safe”, which tells the template engine that the generated HTML is trusted and does not require encoding.

When to chooselinebreaksorlinebreaksbr

ExceptlinebreaksAnQiCMS also provides another related filterlinebreaksbrThe difference between them is:

• linebreaks:It pays more attention to paragraph structure. It will convert double line breaks to<p>Tags, and convert single newline characters to<br/>. Suitable for text that requires clear paragraph demarcation, such as article body, detailed introduction, etc.
• linebreaksbr:It only performs simple line breaks conversion. It will convert all line breaks to<br/>tags, no generation will be made<p>Tags. Suitable for scenarios where text needs to be separated by lines without paragraph semantics, such as address information, short lists, or code snippets, etc.

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

Actual operation example

Assuming you have imported a multi-line text article content using the content import feature into AnQiCMS and stored it inarchiveObjects'ContentFields. In your article detail template (usually{模型table}/detail.htmlor a custom document template), you can use it like thislinebreaksandsafea filter to 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 ... %}Tags are used to obtain the detailed content of articles. The original text obtainedarticleContentorarticleDescriptionis then processed through a pipe character.|Pass tolinebreaksorlinebreaksbrIt is then passed to the filter for processing.safeFilter, 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 on the website built with AnQiCMS in a neat, expected format, greatly enhancing the professionalism of content display and the user experience.

---

Common Questions (FAQ)

1. Why did I use it, butlinebreaksFilter, but the text is displayed directly on the page instead?<p>and<br/>of HTML tags, rather than the rendered effect?

   • Answer:This is because you may have forgotten to addlinebreaksafter 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 does not need to be escaped. It 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, it contains images, links, and custom styles, do I still need to uselinebreaks?

   • Answer:Generally, it is not necessary.Rich text editors (such as the editor built into the AnQiCMS backend) have already formatted the text as content containing HTML tags while you are editing.This content, after import, will be stored as an HTML string by AnQiCMS.linebreaksIt may try to process existing HTML tags again, leading to unnecessary conversions or display errors. For rich text content, you usually only need to use|safe[en]Filter to ensure that its HTML code is parsed correctly:{{ 您的富文本内容变量|safe }}.

3. [en]Question: Besides the article content, where else in the text may the multi-line text content need to be imported?linebreaksFilter?

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