How to automatically convert line breaks in user input plain text content to HTML's `
` tag?

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 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 line and lose their original formatting.

This is not a problem with the AnQi CMS system itself, but a feature of the HTML web page rendering mechanism.In HTML, the browser defaults to treating all carriage returns (i.e., newline characters) as spaces and does not automatically wrap.Only when the content includes<p>(paragraph) or<br/>(Forced line break) When such HTML tags are used, the browser will display line breaks or paragraphs according to the tag instructions.

The Anqi CMS solution: powerful text filter

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

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

Get to know in-depthlinebreaksandlinebreaksbr

1. linebreaksbrFilter: A simple and direct line breakThis filter is the most direct solution, it will replace every line break in plain text content (\n) 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.

   Usage example:Assuming the content you enter in the background is:

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

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

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

   It will be rendered as:

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

2. linebreaksFilter: More intelligent paragraph processingCompared tolinebreaksbrSimple and rough,linebreaksThe filter becomes more intelligent and semantically appropriate. It does two things:

   • Convert a single newline (\n）to<br/>.
   • It replaces two or more consecutive newline characters (i.e., paragraphs separated by blank lines) with<p>and</p>wrap in tags to form a standard HTML paragraph.

   Usage example:Assuming the content you enter in the background is:

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

   Used 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 suits your specific content formatting needs. If the content is mostly short sentences or lists,linebreaksbrMaybe more appropriate; if the content is structured paragraph articles,linebreaksthey can provide better HTML semantics.

Why is it needed|safe?

While usinglinebreaksorlinebreaksbrwhen using filters, you will notice that they are all followed by a|safeFilter. This is a very critical step!

The AnQi CMS template system, for security reasons, defaults to escaping all output variables with HTML entities to prevent cross-site scripting (XSS) attacks. This means that if the filter will\nto<br/>There is not|safeThe browser will not display a line break, but will display it directly<br/>this text string.

|safeThe filter tells the template engine: "I know this variable outputs HTML content, please do not escape it, parse and display it directly as HTML." Therefore, when you uselinebreaksorlinebreaksbrThis filter that generates HTML tags must be added|safe.

Where can these filters be used?

These powerful text filters can be applied anywhere that stores plain text and needs to retain line breaks:

• Article details(archiveDetail）的ContentorDescriptionField:

  
  {% archiveDetail articleContent with name="Content" %}
  <div class="article-body">
      {{ articleContent|linebreaks|safe }}
  </div>
  

• Category details(categoryDetail）的ContentorDescriptionField:

  
  {% categoryDetail categoryDesc with name="Description" %}
  <p class="category-description">
      {{ categoryDesc|linebreaksbr|safe }}
  </p>
  

• Single page (pageDetail）的ContentField:

  
  {% pageDetail pageText with name="Content" %}
  <div class="page-content">
      {{ pageText|linebreaks|safe }}
  </div>
  

• Content Model Custom Field:If you define a multi-line text type custom field in the content model, for exampleproduct_featuresIt can also be handled in this way:

  
  {% archiveDetail features with name="product_features" %}
  <div class="product-features">
      {{ features|linebreaksbr|safe }}
  </div>
  

Practice: Make the article content automatically wrap

Suppose you are editing an Anqi CMS article detail page template (such asarticle/detail.html), and you want the main content of the article to be displayed according to the line break effect entered in the background.

1. Find the output position of the article content, usually it would be something like{{ archive.Content }}Or througharchiveDetailThe content obtained by 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 enter in the Anqi CMS background will be able to automatically and correctly achieve line breaks and paragraph effects on the front-end web page, greatly enhancing the flexibility of content display and user experience.

Frequently Asked Questions (FAQ)

1. Q: When should it be usedlinebreaksAnd when should it be usedlinebreaksbrWhat are the differences? A:It mainly depends on your needs for formatting.linebreaksbrMore direct, it will simply convert each newline (carriage return) to a<br/>Tags are suitable for handling lists, addresses, poems, or brief descriptions, and retain the original line-by-line display. Whilelinebreaksit is more intelligent, it will convert a single newline character to<br/>But will recognize text blocks separated by empty lines as different paragraphs, and enclose them with<p>tags, which is more suitable for processing structured article text and providing better HTML semantics.

2. Q: I have already usedlinebreaksbrthe filter, but the text displayed on the webpage is still<br/>this text does not actually wrap. What's the matter? A:This situation may be caused by your forgetting to add after the filter|safeLabel. The Anqi CMS template system defaults to escaping all output variables to prevent security issues. So, whenlinebreaksbra filter to convert line breaks into<br/>If not after,|safeLabel to clearly tell the template system