How to preview the effect of the `linebreaks` filter on multi-line text in a template?

In website content management, we often encounter situations where we need to display multi-line text, such as article summaries, product descriptions, or user comments.These texts may just be simple strings with newline characters in the database. If they are output directly to the web page, the browser will usually ignore these newline characters, causing all the text to be squeezed together and severely affecting the reading experience.linebreaksThe filter is designed to solve this problem, it can intelligently convert line breaks in plain text to HTML paragraph or line break tags, thus displaying the multi-line text effect we expect on the web page.

UnderstandinglinebreaksThe working principle of the filter

linebreaksThe filter is mainly used to remove line breaks from plain text (\nConvert to HTML tags, so that the layout of multi-line text can be displayed correctly on the web page. When you pass a text containing newline characters tolinebreaksWhen filtering, it will perform the following conversion:

1. single line break (\n):will be converted to HTML's<br />Label. This indicates inserting a simple line break in the text without starting a new paragraph.
2. Two or more consecutive newline characters (\n\nor more):are recognized as separators between paragraphs,linebreaksThey will convert them to HTML's<p>and</p>tags to wrap independent paragraphs.

WithlinebreaksThere is also a filter similar to onelinebreaksbrThere are filters. The main difference between them is:

• linebreaks:They will convert single-line breaks to<br />and convert the blank lines between paragraphs into<p>and</p>tags to wrap the content. It is more suitable for scenarios that require generating structured paragraphs.
• linebreaksbr:The behavior is simpler and more direct, it will convert all newline characters directly to<br />tags without generating<p>Label. This is suitable for scenarios that only require simple line breaks and do not need strict paragraph structure.

To better understand, we can imagine a pure text passage like this:

这是第一行文本。
这是第二行文本。

这是第三行文本，前面有一个空行。

AfterlinebreaksThe effect after the filter is applied will be like this:

<p>这是第一行文本。<br />这是第二行文本。</p><p>这是第三行文本，前面有一个空行。</p>

If you uselinebreaksbrThe effect after the filter is applied will be like this:

这是第一行文本。<br />这是第二行文本。<br /><br />这是第三行文本，前面有一个空行。

Applied in AnQiCMS templatelinebreaksFilter

To preview in the template of AnQi CMSlinebreaksAfter the filter processing, the effect of multi-line text, you need to complete the following steps:

1. Confirm the text field to be processed: linebreaksThe filter is commonly used to process fields stored in plain text format but need to be displayed in a multi-line format on the front end, such as the "Document Summary" of an articleDescription）or certain custom multi-line text fields. If your 'Document Content'Content）field is enabled with Markdown editor, then it is usually appropriate to userenderFilter to convert it to HTML becauselinebreaksThe filter mainly targets newline characters in plain text.

2. Locate the corresponding template file:The template files of Anqi CMS are usually stored in:templateIn the directory, each topic has its own independent folder. For example, the template for the article detail page may be locatedtemplate/您的主题名称/archive/detail.htmlortemplate/您的主题名称/{模型table}/detail.htmlYou need to find the correct template file based on the current page type and the theme template you are using.

3. Modify the template code and add a filter:Find the one to applylinebreaksThe variable output position of the filter. For example, if you want the description of the article to be displayed as multi-line text and the original data contains newline characters, you can find something similar{{ archive.Description }}This code line, and modify it to:

   <div class="article-description">
       {{ archive.Description|linebreaks|safe }}
   </div>
   

   Or if you prefer a simpler line break:

   <div class="article-description">
       {{ archive.Description|linebreaksbr|safe }}
   </div>
   

   Pay special attention|safeThe use of:Immediately following the filter:|safecrucial. The template engine of AnQi CMS, for security reasons, defaults to escaping all output variable content, which means<p>/<br />such tags will be converted to<p>/<br />Thus, it is directly displayed on the page instead of being parsed as an HTML tag by the browser.|safeThe filter explicitly tells the template engine that this content is safe and does not require escaping, and can be output directly as HTML.

4. Save and preview the effect:Modify the template file and save the changes.Since the Anqi CMS has a default cache mechanism, in order to see the effect immediately, you may need to find the 'Clear Cache' function in the left navigation bar of the background management interface and click it.linebreaksFiltered multi-line text effect.

By following the above steps, you can flexibly control the display of multi-line text on the page to make it more in line with your design and user reading habits.

Common Questions (FAQ)

Q1: Why did I add these tags in the template?linebreaksThe filter, but the multi-line text is still displayed in one line, or it is displayed directly.<p>/<br />these tags?

A1: This is very likely because you forgot tolinebreaksadd after the filter|safeFilter. The SafeCMS template engine defaults to escaping HTML tags to prevent security issues, causing<p>/<br />to be displayed as plain text. Add|safeYou can tell the template engine that this content is safe HTML, which does not need to be escaped, and the browser will parse it normally. For example:{{ archive.Description|linebreaks|safe }}.

Q2:linebreaksandlinebreaksbrWhat are recommended scenarios for using a filter? How should I choose it?

A2: If you wish for the text to logically form paragraphs with clear spacing between them, it is recommended to uselinebreaks. It will use<p>Label wrapping paragraph, usually more in line with semanticization and page layout requirements.For example, the abstract of an article, the full text of user comments.linebreaksbrmay be more appropriate, as it only inserts<br />Label. The choice mainly depends on the visual effect and HTML structure you want the content to be presented on the page.

Q3: My "document content" is entered using Markdown editor, usinglinebreaksIs the filter effective?

A3: If your 'Document Content' field is entered using a Markdown editor, the content itself is already in Markdown format. What you need is to convert it to HTML. In this case,linebreaksThe filter is usually not **selected. The Anqi CMS provides a dedicated rendering mechanism for Markdown content, such as usingrenderfilters (such as{{ archive.Content|render|safe }}To parse it correctly as HTML.linebreaksThe filter is mainly used for processing.Plain textThe built-in newline characters are converted to basic HTML paragraph or newline tags, rather than parsing complex Markdown syntax.