How to automatically render the multi-line text (including line breaks) of AnQiCMS custom fields as HTML '`

` and '`
` tags?

When using AnQiCMS to manage website content, we often take advantage of its powerful custom field feature to enrich page information.Especially for text that needs to include multi-line descriptions, notes, or detailed explanations, the 'multi-line text' type in custom fields is undoubtedly the ideal choice.However, when we eagerly display these text contents with line breaks on the front-end page, we may find that the original line breaks are not automatically recognized by the browser, resulting in all the text being compressed into a mass and greatly reducing the reading experience.

This is actually a feature of the HTML rendering mechanism: browsers do not automatically convert line breaks in plain text to HTML's\nto the elegant format<br/>Labels or wrap them in paragraphs. It will simply treat all text as a continuous string.How to automatically render the content extracted from a custom multiline text field in AnQiCMS, into a paragraph with HTML tags (<p>）and line breaks.<br/>of it?

The core solution lies in the clever use of the template filters provided by AnQiCMS.AnQiCMS's template engine is powerful, it allows us to perform secondary processing and formatting on the output variable content.For handling the line break problem in multiline text, we mainly use two key filters:linebreaksandsafe.

Know AnQiCMS template filter

AnQiCMS template design pays great attention to flexibility and ease of use, it draws on the syntax of the Django template engine, allowing developers to use various tags ({% ... %}) and filters ({{ variable|filter_name }}）to control the display of content.

1. linebreaksFilter:This filter is specifically used to intelligently convert line breaks in plain text to HTML.<p>and<br/>tags. It will convert individual line breaks in the text.\n）to<br/>Labels, while two consecutive line breaks (\n\nusually represent the start of a new paragraph, and using<p>and</p>Tags wrap. This is very useful for rendering multi-line text into structured paragraphs.

2. linebreaksbrFilter (as an alternative):withlinebreakssimilar,linebreaksbrIt also handles newline characters, but its behavior is simpler and more direct, simply replacing all newline characters(\n) with HTML's<br/>tags without automatically generating them<p>Label. If you only want simple inline line breaks, not distinguishing paragraphs, this filter is more suitable.

3. safeFilter:This is one of the most critical filters. AnQiCMS template engine, for security reasons, defaults to escaping all output HTML content to prevent cross-site scripting (XSS) attacks.This means, evenlinebreaksorlinebreaksbrThe filter was successfully generated.<p>and<br/>Labels, they will also be escaped.<p>and<br/>Such plain text strings that will not be parsed as actual HTML elements by the browser.safeThe role of the filter is to inform the template engine: "This content is safe, please do not escape it with HTML, and output it directly as HTML." Therefore, when we need to output HTML tags generated by the filter, safeThe filter is indispensable.

Practical steps: Make multiline text beautiful

We will demonstrate through a specific example how to automatically render the content of a custom multi-line text field into a format with HTML paragraphs and line breaks.

Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS background Assuming you have added an "extra description" field (call field:) in the "article model" or "product model" in the AnQiCMS backgroundextra_descriptionThe 'Multi-line text' custom field.

1. Set the custom field in the background content model:First, you need to log in to the AnQiCMS backend, navigate to "Content Management" -> "Content Model".Select the model you want to edit (for example, "article model"), then click "edit" or "add field".Here, you can add a new field, set its "parameter name" to "additional description", and set the "call field" toextra_descriptionand select 'Field type' as 'Multi-line text'.

2. Add text with line breaks:When you post or edit an article (or product), find the custom field "Additional Description".Here, you can enter multi-line text content and create line breaks as you would in a notepad.

   这是一段关于产品的额外描述。
   它可能包含一些重要的细节，
   比如：
   
   - 产品的独特卖点
   - 使用注意事项
   - 售后服务联系方式
   
   这些信息希望能够以清晰的段落和换行展示。
   

3. Edit the front-end template file:Now, we need to modify the front-end template file to correctly display this custom field. Usually, the template file for the document detail page is located in your template directory.archive/detail.htmlorproduct/detail.html. You can edit the template online through the "Template Design" feature in the AnQiCMS backend, or directly modify the files via FTP/SFTP.

4. Use tags and filters to render content:Indetail.htmlIn the file, find the location where you want to display the "extra description" and then add the following code:

   {# 假设自定义字段的调用字段是 'extra_description' #}
   {% archiveDetail extraDescription with name="extra_description" %}
   <div class="extra-description-section">
       <h3>额外描述：</h3>
       {# 使用 linebreaks 过滤器将换行符转换为 <p> 和 <br/> 标签，并使用 safe 过滤器防止 HTML 转义 #}
       {{ extraDescription|linebreaks|safe }}
   </div>
   

   Explain this line of code:

   • {% archiveDetail extraDescription with name="extra_description" %}This is the AnQiCMS document detail tag, used to get the specific field value of the current document. We will assign the content of the field namedextra_descriptionto a template variable namedextraDescription.
   • {{ extraDescription|linebreaks|safe }}This is the core. We extractextraDescriptionthe content of the variable, first through|linebreaksa filter to convert the internal newline characters to HTML tags.<p>and<br/>Then, we go through|safeA filter that tells the browser that these generated HTML tags are safe and can be rendered directly without needing to be escaped.

   If you only need a simple<br/>line break without generating<p>Label, you can change the code to:

   {% archiveDetail extraDescription with name="extra_description" %}
   <div class="extra-description-section">
       <h3>额外描述：</h3>
       {# 只使用 linebreaksbr 过滤器生成 <br/> 标签 #}
       {{ extraDescription|linebreaksbr|safe }}
   </div>
   

After saving your template file, refresh the front-end page, and you will find that the content of the "additional description" field has now been automatically rendered into a clear HTML paragraph and line break, greatly improving the readability of the content.

In this way, the custom multiline text field of AnQiCMS is no longer just a container for plain text, but a powerful tool that can output structured and formatted content, helping you to better display information and optimize the user experience.

Frequently Asked Questions (FAQ)

1. Why am I typing in the background custom multi-line text field and the front-end displays it all squished together?This is due to the rendering mechanism of HTML. In HTML, browsers do not automatically recognize carriage returns in plain text content.\nFor a new line or paragraph. If you want the text to display as a new line or paragraph on a webpage, you must use HTML tags like<br/>(new line) or<p>(Paragraph) to clearly indicate. When AnQiCMS outputs custom field content directly, it is in plain text format by default, so an additional template filter needs to be used for conversion.

2.linebreaksandlinebreaksbrWhat is the difference between these two filters? Which one should I use?The main difference between them lies in how they handle the line break.