When using AnQiCMS to manage website content, we often take advantage of its powerful custom field function to enrich page information.Especially for text that requires multiple lines of description, notes, or detailed explanations, the 'Multi-line text' type in custom fields is undoubtedly the ideal choice.However, when we expectantly display these text content with line breaks on the front-end page, we may find that the original line breaks are not automatically recognized by the browser, leading to all text being crowded together, which greatly reduces 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 format by default:\nWhat about the elegant format of the line break?<br/>Label or wrap it in a paragraph.It will simply treat all text as a continuous string.<p>) and line breaks(<br/>What about the elegant format of the line break?

The core solution lies in skillfully using 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.linebreaksandsafe.

Understanding AnQiCMS template filters

The template design of AnQiCMS emphasizes 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 separate line breaks in the text.\n) to<br/>Labels, while two consecutive new lines are recognized as the start of a new paragraph, and\n\nusually represent a blank line.)<p>and</p>Label it. This is very useful for us to render multiline text as structured paragraphs.

  2. linebreaksbrFilter (as an alternative):Withlinebreaksis similar,linebreaksbrAlso handles newline characters, but its behavior is simpler and more direct, simply converting all newline characters into\n) in plain text content with HTML's<br/>tags without automatically generating<p>Label. If you only want simple inline line breaks without distinguishing paragraphs, this filter will be more suitable.

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

实操步骤：让多行文本华丽变身

Below is an example to show 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 'Additional Description' (field name: extra_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 (such as "Article Modelextra_descriptionand select the field type as "multi-line text".

  2. Add line-break text to content:When you publish or edit an article (or product), find the custom field "additional description".Here, you can enter multi-line text content and create line breaks like in a notepad by pressing the Enter key.

    This is an additional description about the product. It may contain some important details, like:

    • Unique selling points of the product
    • Points to note
    • After-sales service contact information

    I hope this information can be displayed in clear paragraphs and line breaks. “`

  3. Edit the front-end template file:Now, we need to modify the front-end template file to properly display this custom field. Typically, the template file for the document detail page is located under 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. Render content using tags and filters:Indetail.htmlIn the file, find the location where you want to add 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 label, used to obtain the specific field value of the current document. We assign the content of theextra_description to a variable namedextraDescription.
    • {{ extraDescription|linebreaks|safe }}This part is the core. We extractextraDescriptionthe content of the variable, first by|linebreaksfiltering the newline characters inside to HTML tags<p>and<br/>Then, we continue by|safeThe filter tells the browser that these generated HTML tags are safe to render directly without needing to be escaped.

    If you only need a simple<br/>newline and do not want to generate<p>Label, change the code to:

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

Save your template file and refresh the front-end page. You will find that the content of the 'Additional Description' field has now been automatically rendered into well-structured HTML paragraphs and line breaks based on the newline characters you entered, greatly enhancing the readability of the content.

This way, the custom multi-line 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.

Common Questions (FAQ)

1. Why is the text displayed as one long paragraph in the front end even though I entered it with line breaks in the backend custom multi-line text field?This is because the rendering mechanism of HTML determines it. In HTML, the browser will not automatically recognize carriage returns in plain text content.\n）as a line break or new paragraph. If you want the text to display line breaks or paragraph effects on the web page, you must use HTML tags like<br/>（line break）or<p>（Paragraph）to indicate explicitly. When AnQiCMS outputs custom field content directly, it is in plain text format by default, so an additional template filter needs to be used to convert it.

2.linebreaksandlinebreaksbrWhat are the differences between these filters? Which one should I use?The main difference lies in how they handle line breaks.