In daily website content operations, we often need to enter some multi-line text content in the Anqi CMS backend, such as the introduction of articles, the characteristics description of products, or detailed descriptions in custom fields.This content is usually entered in plain text format. However, when we expect them to be displayed on the front-end web page with the original paragraph and line break effects, we find that they are often cramped into a single line, losing their original formatting.

This is not a problem with the AnQi CMS system itself, but a characteristic of the HTML web page rendering mechanism.In HTML, the browser defaults to treating all newline characters (i.e., line breaks) in plain text as spaces and does not automatically wrap.<p>(paragraph) or<br/>(Forced line break) Such HTML tags, the browser will perform the corresponding line break or section display according to the tag instructions.

The Anqi CMS Solution: Powerful Text Filter

To ensure that the pure text content entered by the user is perfectly presented with original line breaks on the front-end webpage, Anqi CMS provides a flexible and powerful template filter mechanism. Among them,linebreaksandlinebreaksbrThese filters are designed specifically to solve the problem of line breaks in plain text.

These filters can intelligently parse newline characters in plain text and automatically convert them into HTML newline tags that browsers can recognize, thus perfectly preserving the original formatting you entered in the background.

Deeply Understandlinebreaksandlinebreaksbr

  1. linebreaksbrFilter: Simple and direct line breakThis filter is the most direct solution, it will replace every line break (\n) in plain text content with HTML's<br/>Label. This means that no matter how many times you press Enter in the background, the front-end page will display a forced line break at the corresponding position.

    Example Usage:Suppose the content you enter in the background is:

    第一行文字
第二行文字
第三行文字

    Using in the front-end templatelinebreaksbrFilter, code as follows:

    {{ 你的纯文本变量|linebreaksbr|safe }}

    It will be rendered as:

    第一行文字<br/>
第二行文字<br/>
第三行文字

  2. linebreaksFilter: More intelligent paragraph processingCompared withlinebreaksbrsimple and粗暴，linebreaksThe filter is more intelligent and semantically appropriate. It does two things:

    • Convert a single newline character(\n) to<br/>Label.
    • Translate the continuous two or more newline characters (i.e., paragraph-separated by blank lines) into<p>and</p>tags to form standard HTML paragraphs.

    Example Usage:Suppose the content you enter in the background is:

    这是第一段。
这里是第一段的第二行。


这是第二段。

    Using in the front-end templatelinebreaksFilter, code as follows:

    {{ 你的纯文本变量|linebreaks|safe }}

    It will be rendered as:

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

    You can choose a filter that is more suitable according to the specific requirements of content layout. If the content is mostly short sentences or lists,linebreaksbrit may be more appropriate; if the content is structured paragraph articles,linebreaksIt can provide better HTML semantics.

Why is it needed?|safe?

When usinglinebreaksorlinebreaksbrWhen using filters, you will notice that they are always followed by a|safeThis is a very critical step!

The template system of Anqi CMS defaults to escaping all output variables as HTML entities for security reasons, to prevent cross-site scripting (XSS) attacks. This means that if the filter sets\nConverted to<br/>No more|safeThe browser will not see a line break, but will display the text directly.<br/>this text string.

|safeThe filter tells the template engine: 'I know the variable outputs HTML content, please do not escape it, and parse it directly as HTML for display.' Therefore, when you uselinebreaksorlinebreaksbrThis generator for HTML tags must include.|safe.

Where can these filters be used?

These powerful text filters can be applied to any storage of plain text that needs to retain line breaks:

  • Article details (archiveDetail) ofContentorDescriptionFields: 
    
{% archiveDetail articleContent with name="Content" %}
<div class="article-body">
    {{ articleContent|linebreaks|safe }}
</div>
  • Category details (categoryDetail) ofContentorDescriptionFields: 
    
{% categoryDetail categoryDesc with name="Description" %}
<p class="category-description">
    {{ categoryDesc|linebreaksbr|safe }}
</p>
  • Single page (pageDetail) ofContentFields: 
    
{% pageDetail pageText with name="Content" %}
<div class="page-content">
    {{ pageText|linebreaks|safe }}
</div>
  • Custom fields of content model:If you have defined a multi-line text custom field in the content model, such asproduct_features, it can also be handled in this way:
    
{% archiveDetail features with name="product_features" %}
<div class="product-features">
    {{ features|linebreaksbr|safe }}
</div>

Practice Exercise: Auto-wrap Article Content

Suppose you are editing the article detail page template of an enterprise CMS (such as)article/detail.html），and hope that the article content can be displayed according to the line break effect input by the background.

  1. Find the output position of the article content, usually it will be something like{{ archive.Content }}or througharchiveDetailto get the content of the tag.
  2. ApplylinebreaksorlinebreaksbrFilter, and add|safe.

Example code snippet:

{# 获取当前文章的完整内容 #}
{% archiveDetail articleContent with name="Content" %}

<article class="main-article">
    <h1 class="article-title">{% archiveDetail with name="Title" %}</h1>
    <div class="article-meta">
        发布时间：<span>{% archiveDetail with name="CreatedTime" format="2006-01-02" %}</span>
        分类：<a href="{% categoryDetail with name='Link' %}">{% categoryDetail with name='Title' %}</a>
    </div>
    <div class="article-body">
        {# 使用 linebreaks 过滤器，将纯文本换行符转换为 HTML 段落和换行标签 #}
        {{ articleContent|linebreaks|safe }}
    </div>
</article>

By following these steps, the plain text content you input in the Anqi CMS backend will be automatically and correctly displayed with line breaks and paragraph effects on the front-end web page, greatly enhancing the flexibility of content display and the user experience.

Common Questions (FAQ)

  1. Q: When should it be usedlinebreaks, When should it be usedlinebreaksbrWhat are the differences? A:It mainly depends on your layout requirements.linebreaksbrmore direct, it simply converts each newline (return) to a<br/>Labels, suitable for handling lists, addresses, poems, or brief descriptions, maintaining the original line-by-line display.linebreaksare more intelligent, as it will convert a single newline character into<br/>However, it will recognize text blocks separated by empty lines as different paragraphs, and enclose them with<p>tags, which is more suitable for handling structured article content and provides better HTML semantics.

  2. Q: I have already usedlinebreaksbrthe filter, but the text displayed on the web page is still<br/>this text, which does not actually break into a new line. What is wrong with that? A:This might be the case if you forget to add the filter after|safeTags. The Anqi CMS template system defaults to escaping all output variables as HTML entities to prevent security issues. Therefore, whenlinebreaksbrFilters will convert newline characters to<br/>After, if not|safeTag to clearly tell the template system