How to convert newline characters in multi-line text to HTML `tags for display in AnQiCMS templates?
How to display text enclosed in `tags?

In AnQiCMS content management, we often enter multiline text with line breaks, such as article content, product description, or contact address.However, when this content is presented on the website front end, we may find that the original clear line breaks are missing, and all the text is compressed into one line.This may affect the reading experience of the content, and may not be consistent with our original design intention.

Why is this? In simple terms, the HTML specification states that browsers will automatically ignore single newline characters in text.\n）and consecutive whitespace characters, treating them as a single space. Only<p>tags (paragraphs) or<br>Tags (newline) can create a visual line break.Therefore, even if we press the Enter key in the background content editor, these line breaks in plain text are just a normal space in the browser.

AnQiCMS's template system is based on the powerful Django template engine syntax and provides simple yet powerful template filters (filters) to elegantly solve this problem, ensuring that your multiline text content is displayed as expected.

Template filter: The tool to solve the line break display problem

AnQiCMS provides two core filters to handle newline characters in plain text:linebreaksandlinebreaksbrEnglish translations are not provided as per the instruction.

1. linebreaksFilterThis filter will convert each independent or consecutive newline character in the text to an HTML paragraph tag.<p>and</p>If a newline character is present in a<p>Label inside also has a newline character, it will further convert these internal newline characters to<br/>Label. This is very suitable for handling the main body of articles, as it can automatically divide your content into standard paragraphs and maintain line breaks within paragraphs.

   Example Usage:Assumearchive.ContentIt is the main content of your article, which includes multi-line text.

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

   AfterlinebreaksAfter processing, the original:

   这是第一段文字。
   这是第一段的第二行。
   
   
   这是第二段文字。
   

   May be converted to:

   <p>这是第一段文字。<br/>这是第一段的第二行。</p>
   <p>这是第二段文字。</p>
   

2. linebreaksbrFilterThis filter is more direct and simple. It will only convert each newline character in the text to\n), without adding any extra<br/>tags.<p>Label wrapping. This is applicable to content that does not require paragraph semantics but needs to maintain line breaks, such as brief descriptions, address information lists, etc.

   Example Usage:Assumecategory.DescriptionIt is a brief description of the category, or a contact address, and it needs to be displayed strictly by line.

   <address>
       {{ category.Description|linebreaksbr|safe }}
   </address>
   

   AfterlinebreaksbrAfter processing, the original:

   联系地址：某某市某某区
   电话：123-4567-890
   

   It will be converted to:

   联系地址：某某市某某区<br/>电话：123-4567-890
   

Where should these filters be applied?

These filters can be directly applied to variables in AnQiCMS templates used to display multiline text. Common application scenarios include:

• Document Details Page：displayarchive.Content(Article content),archive.Description(Article summary) et al.
• Category details page:displaycategory.Content(Category content),category.Description(Category description) et al.
• Single Page Details Page：displaypage.Content(Single page content),page.Description(Single-page description) etc.
• Custom field:Any custom field defined as "Multi-line text" type in the content model, which contains newline characters, can also use these filters.

Select an appropriate filter

• Uselinebreaks:If your multiline text is a long paragraph, you would like it to be displayed structured like a normal article, with spacing between each natural paragraph, and the internal line breaks become single-line breaks.linebreaksis a very good choice. It will bring you clearer paragraph structure.
• Uselinebreaksbr:If your multiline text is a short address list, phone number list, or if you simply want to convert each newline to an HTML line break tag without additional paragraph tags wrappinglinebreaksbrIt is more suitable, it provides the most direct line break effect.

Special reminder:|safeThe importance of filters

Whether usinglinebreaksOrlinebreaksbrFilter, you need to add one after it|safeFilter, such as{{ my_variable|linebreaks|safe }}This is because:linebreaksandlinebreaksbrIt will generate HTML tags (<p>and<br/>），而 AnQiCMS 的模板引擎默认为了安全考虑，会自动对所有输出的 HTML 标签进行转义（例如把",<Converted to<）。If not added|safeThese tags will be displayed as plain text on the page, rather than being interpreted as line breaks by the browser.|safeTell the template engine that you trust this content is safe HTML, and allow it to be rendered normally by the browser.

By simply adding|linebreaksor|linebreaksbrFilter it, and you can easily display the multi-line text content in AnQiCMS on the web page in a more beautiful and expected manner.This not only enhances the user reading experience, but also makes your website content management more flexible and efficient.

Common Questions (FAQ)

1. Q: Why did I use|linebreaksor|linebreaksbrAfter, the content still does not wrap, even<br>Are the tags all displayed directly?A: This is very likely because you forgot to add at the end of the filter chain|safeFilter. AnQiCMS's template engine defaults to escaping all outputs that may generate HTML to prevent XSS attacks.|safeThe filter informs the template engine that this content is safe HTML that can be normally parsed and rendered by the browser, rather than displayed as plain text. For example, the correct syntax should be{{ archive.Content|linebreaks|safe }}.

2. Q: I should chooselinebreaksOrlinebreaksbrFilters? What are the differences?A: It depends on the display effect and semantic content you hope for.

   • linebreaksFilters will convert consecutive newline characters in text to<p>Label, and<p>Single newline characters within the label are converted to<br/>. It is suitable for long text that needs to be structured into paragraphs (such as article content), the browser will provide each<p>Label adds the default paragraph spacing.
   • linebreaksbrThe filter is more direct; it will only convert each newline in the text to a<br/>tags.<p>Label. This applies to addresses, list items, or brief descriptions, etc. that do not require paragraph semantics.