How to use `linebreaks` and `linebreaksbr` filters to convert line breaks in the pure text content input by the Safe CMS user to HTML

`or`
`tag?

In a content management system, handling plain text input from users and displaying it on the web page in the desired format is a common requirement.When the user enters text with line breaks in the background editor, the browser does not render them as HTML line breaks by default.All content may be挤在一行，resulting in messy formatting and affecting the reading experience.幸运的是，AnQiCMS提供了方便的模板过滤器来解决这个问题。linebreaksandlinebreaksbrThese two filters convert line breaks in plain text to those compliant with HTML standards.<p>or<br>Label.

Why does the line break in plain text fail on web pages?

When we edit documents, pressing the Enter key is actually inserting a 'carriage return' character (\nor\r\n）。But in the world of HTML, when the browser parses HTML content, it ignores multiple spaces and newline characters. Unless you use specific HTML tags, such as<p>(paragraph) or<br>(New line), otherwise all text will be treated as a continuous string, displayed in one line.

This is why even if you enter multi-line text in the AnQiCMS backend content editor, if it is output directly to the front-end page, they may still be cramped together.In order for these line breaks to 'come to life' on the web page, we need to process them.

Introduce the solution:linebreaksWithlinebreaksbr

AnQiCMS's template engine provides a series of powerful filters,linebreaksandlinebreaksbrIt is specifically used to handle pure text line breaks. Their role is to intelligently convert line breaks in plain text into HTML tags, thus achieving the formatted display of content.

1.linebreaksFilter: Automatically generate paragraphs and line breaks

linebreaksThe way the filter works is similar to the 'auto-wrap' feature in many text editors.It will recognize the newline patterns in plain text and convert them into more structured HTML paragraphs.

• Working principle:

  • A single newline character (such as when the user presses Enter once) will be converted to HTML's<br>tags to implement simple inline line breaks.
  • Continuous two or more newline characters (usually indicating that the user has entered an empty line, intending to start a new paragraph) will be converted into a pair<p>and</p>Labels, wrap around adjacent text content to form an independent paragraph.

• Use cases:When you want the text input by the user to automatically form structured paragraphs,linebreaksIt is an ideal choice. For example, it can be used to display article content, blog content, product descriptions, etc., which can keep the content well segmented visually, enhancing the reading experience.

• Code example:

  Assuming your document content field (such asarchive.Contentorarchive.Description) stores the following plain text:

  第一段内容。
  这是第一段的第二行。
  
  
  这是第二段内容。
  它有自己的独立意义。
  

  In the template, you can use it like this:linebreaksFilter:

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

  Rendered output:

  <div class="content-body">
      <p>第一段内容。<br />这是第一段的第二行。</p>
  
  
      <p>这是第二段内容。<br />它有自己的独立意义。</p>
  </div>
  

  Note:UselinebreaksorlinebreaksbrAfter all, since they generate HTML tags, they must follow|safeFilter.|safeis used to inform the template engine that this content is safe and does not require HTML entity escaping. If it is missing|safeYou may see the original on the page<p>and<br />Tags, rather than their intended rendering effect.

2.linebreaksbrFilter: Simple and direct inline line breaks

linebreaksbrFilter is more direct and pure. Its purpose is to replace all line breaks without distinction with HTML tags.<br>tags without introducing<p>Label.

• Working principle:No matter whether it is a newline or multiple consecutive newlines,linebreaksbrthey will all be replaced with one<br>label. It only pays attention to the physical line separation, not concerned with the semantic paragraph division.

• Use cases:When your plain text content needs to be preserved exactly with each line separation of user input, and you do not want it to be parsed as independent HTML paragraphs,linebreaksbrVery useful. For example, displaying poems, address information, code snippets, ordered or unordered list items, or any text that requires precise control of line height.

• Code example:

  Continue with the above plain text content:

  第一段内容。
  这是第一段的第二行。
  
  
  这是第二段内容。
  它有自己的独立意义。
  

  In the template, you can use it like this:linebreaksbrFilter:

  <div class="address-info">
      {{ user.Address|linebreaksbr|safe }}
  </div>
  

  Rendered output:

  <div class="address-info">
      第一段内容。<br />这是第一段的第二行。<br /><br />这是第二段内容。<br />它有自己的独立意义。
  </div>
  

  Here you will see, even empty lines will be converted into one<br />tags, because it only does simple substitutions.

How to choose an appropriate filter?

ChooselinebreaksOrlinebreaksbrmainly depends on your expectations of the content format:

• If you want plain text content to appearwith clear paragraphs and structurelike a formal article, thenlinebreaksis a better choice. It will create HTML paragraphs more intelligently.
• If you only needsimple inline line breaks, not concerned with paragraph semanticsEnglish or need to strictly follow the display of each line of input content, such as displaying a poem, an address, or a manually maintained list, thenlinebreaksbrit will be more in line with your needs.

Generally, for core content such as article details, product introductions,linebreaksCan provide a better semantic structure. And for the brief information such as the sidebar introduction, contact information, etc.,linebreaksbrit is more suitable.

Apply the filter to AnQiCMS template

In AnQiCMS, you can apply these filters after any template tag that outputs plain text content. Common use cases include:

• Document content: {{ archive.Content|linebreaks|safe }}
• Document description/introduction: {{ archive.Description|linebreaks|safe }}or{{ archive.Description|linebreaksbr|safe }}
• Single page content: {{ page.Content|linebreaks|safe }}
• Category Description： {{ category.Description|linebreaks|safe }}
• Custom text field:Any custom field defined as multiline text in the background.

By simply adding|linebreaks|safeor|linebreaksbr|safe, will bring new life to your AnQiCMS website content, with better layout and user experience.

Common Questions (FAQ)

Q1: I usedlinebreaksorlinebreaksbrFilter, but there is still no line break effect on the page, why is that? A1:This is likely because you forgot to add at the end of the filter chain|safeFilter.linebreaksandlinebreaksbrAll generated are HTML tags, if missing|safe，模板引擎会默认将这些HTML标签当作普通文本进行转义（例如<p>Will become<p>），导致浏览器无法正确解析。请确保您的代码类似于{{ archive.Content|linebreaks|safe }}.

Q2：These two filters will affect the SEO of my website? A2：In most cases, using them correctlylinebreaksorlinebreaksbrFilters have no negative impact on SEO, and may even have a positive effect.linebreaksgenerated<p>Tags have a good semantic structure, which helps search engines understand the segmentation of content paragraphs.linebreaksbrAlthough the semantics are slightly weaker, it can ensure the clear presentation of content, improve user experience, and indirectly benefit SEO.The key is to ensure the readability and structural rationality of the content, rather than just using tags for the sake of it.

Q3: Can I use these filters in all text fields? For example, in the title field? A3:Theoretically, it can be used on any text output, but in practical applications, it needs to be decided according to the characteristics of the field. For example, the title field (such asarchive.TitleIt is usually single-line text, and there is unlikely to be a newline character, even if there is, convert it to `<