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

In website content management, we often encounter situations where we need to display multi-line text, such as the introduction of articles, product descriptions, or user comments.This text may just be simple strings with newline characters in the database. If output directly to the web page, the browser usually ignores these newline characters, causing all the text to be挤在一起, severely affecting the reading experience.AnQiCMS (AnQiCMS) provides a powerful template engine, one of thelinebreaksThe filter is designed to solve this problem, it can intelligently convert line breaks in plain text to HTML formatted paragraphs or line break tags, thus displaying the multi-line text effect we expect on the web page.

UnderstandinglinebreaksThe principle of the filter.

linebreaksThe filter is mainly used to replace line breaks in plain text (\n) Convert to HTML tags to display the layout of multiline text correctly on a webpage. When you pass a text containing line breaks tolinebreaksWhen the filter is applied, it performs the following conversion:

1. Single line newline character (\n):It will be converted to HTML's<br />Tag. 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 thatlinebreaksbrFilters. The main difference between them is:

• linebreaks:It will convert single-line breaks to<br />Translate the blank lines between paragraphs.<p>and</p>Tag to wrap content. It is more suitable for scenarios where structured paragraphs need to be generated.
• linebreaksbr:The behavior is simpler and more direct, it will convert all newline characters directly.<br />tags without generating any<p>This is suitable for scenarios where only simple line breaks are needed, without strict paragraph structure.

To understand more intuitively, we can imagine that there is a pure text like this:

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

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

afterlinebreaksAfter the filter is applied, the effect will be like this:

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

If we uselinebreaksbrAfter the filter is processed, the effect will be like this:

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

Apply in AnQiCMS templatelinebreaksFilter

Preview in the AnQi CMS templatelinebreaksAfter the filter effect on the multi-line text, you need to complete the following steps:

1. Confirm the text field to be processed: linebreaksThe filter is most commonly used to process fields stored in plain text format but need to be displayed in multi-line format on the front end, such as the "document summary" of an article (Description）Or some custom multi-line text field. If your "document content" field has enabled Markdown editor, then you should usually useContent）Field enabled Markdown editor, then you should usually userenderA filter 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 intemplateUnder the directory, each topic has its own independent folder. For example, the template for the article detail page may be located intemplate/您的主题名称/archive/detail.htmlortemplate/您的主题名称/{模型table}/detail.html. You need to find the correct template file based on the current page type and the theme 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 in multiline text format and the original data contains newline characters, you can find something similar{{ archive.Description }}such a line of code, and change 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|safeUsage:immediately following the filter:|safeIt is crucial. The template engine of Anqi CMS, for security considerations, defaults to escaping all output variable content, which means<p>/<br />such tags will be converted to<p>/<br />Therefore, it is displayed directly on the page, rather than being parsed as an HTML tag by the browser.|safeThe filter explicitly tells the template engine that this content is safe, does not need to be escaped, and can be output directly as HTML.

4. Save and preview the effect: After modifying the template file, save the changes. Due to the default caching mechanism of Anqicms, in order to ensure that the effects are visible immediately, you may need to find the "Clear Cache" function in the left navigation bar of the background management interface and click to clear the cache.Then refresh your webpage to previewlinebreaksThe multi-line text effect after filter processing.

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 reading habits of users.

Frequently Asked Questions (FAQ)

Q1: Why did I addlinebreaksthe filter, but the multiline text is still displayed in one line, or displayed directly?<p>/<br />these tags?

A1: This is likely because you forgot to add inlinebreaksthe filter behind|safeFilter. The Anqi CMS template engine defaults to escaping HTML tags to prevent security issues, resulting in<p>/<br />Display as plain text. Add|safeYou can tell the template engine that this content is safe HTML, no need to escape, the browser will parse it normally. For example:{{ archive.Description|linebreaks|safe }}.

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

A2: If you want the text to form paragraphs logically with clear spacing, it is recommended to uselinebreaks. It will use<p>Label wrapping paragraphs is usually more semantically and page formatting requirements.For example, an article summary, the main text of user comments. If your text is just simple inline line breaks and does not need to form an independent paragraph, or if you want to finely control the position of each line break (such as in poetry or address display), thenlinebreaksbrmay be more appropriate as it only inserts<br />Label. Which one to choose depends on the visual effect and HTML structure you want the content to display 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,linebreaksFilters are usually not **selected. Anqi CMS provides a special rendering mechanism for Markdown content, such as usingrenderFilter (such as{{ archive.Content|render|safe }}) to parse it correctly into HTML.linebreaksThe filter is mainly used for processingPlain textA newline character built into it should be converted to basic HTML paragraphs or line break tags, rather than parsing complex Markdown syntax.