Many AnQi CMS users may encounter a situation during template development: they may use multi-line text in the template, butlinebreaksA filter, expecting it to automatically identify and convert line breaks in text to HTML paragraphs (<p>) or line breaks (<br/>）Label, but the actual presentation on the page is still text with literal HTML tags, rather than the expected effect after browser parsing.This is indeed confusing, but in fact, the problem usually arises from some misunderstandings about the default behavior of the AnQiCMS template engine.

AnQiCMS has built-in a powerful template engine, one of its design philosophies is to prioritize security.This means that, by default, all content output from the backend database or other variables to the frontend page will be HTML escaped (Escaping).This mechanism is designed to prevent potential XSS (cross-site scripting) risks, ensuring that even if malicious scripts or incomplete HTML tags are accidentally mixed in, they will be displayed as plain text rather than being executed or parsed by the browser.

When you apply a variable containing multiple lines of text tolinebreaksWhen a filter is applied, this filter indeed works according to its intended design: it identifies newline characters in the text and replaces them with HTML's<p>and<br/>Label. Specifically, for a single newline, it will use<br/>instead; and for two consecutive newlines (i.e., blank lines), it will wrap the text before and after them separately<p>Inside the tag. However, due to the default escaping mechanism of the template engine, these newly generated<p>and<br/>tags are not considered true HTML, but are escaped to become&lt;p&gt;and&lt;br/&gt;Such character entities, when browsers encounter these entities, will naturally display them as ordinary text, rather than rendering them as actual HTML elements.

The key to solving this problem is to clearly inform the template engine,linebreaksThe content generated by the filter is "safe" HTML and does not need to be escaped.This needs to introduce another important filter in the AnQiCMS template engine-|safe.|safeThe filter's role is to cancel the HTML escaping of variable content, allowing the browser to directly parse and render the HTML code contained within.

Therefore, the correct practice is to|safeFilter follows|linebreaksUse the filter after. Here is an example:

{# 假设archive.Description是您的多行文本变量 #}
{{ archive.Description|linebreaks|safe }}

Please note the order of the filter application here:|linebreaksIt must be executed first, converting line breaks in the text to HTML tags; then|safeRerun, tell the template engine that these tags are safe and can be output directly. If the order is reversed, for example, written as{{ archive.Description|safe|linebreaks }}, you can be|linebreaksThe content has already been marked as safe and may be incorrectly parsed, orlinebreaksThe generated tags will not besafeprocessed, thus failing to achieve the expected effect.

Some additional considerations and suggestions:

  1. Markdown editor withlinebreaksCompatibility:If your content is entered through the background Markdown editor, then Markdown itself will convert multi-line text, paragraphs, and other elements into HTML structure. In this case, it is recommended to uselinebreaksThe filter may not be necessary, it may even lead to repeated or confused HTML structure. After enabling the Markdown editor, AnQiCMS will usually automatically render the content, you can througharchiveDetailin the labelrender=trueParameters to ensure that Markdown content is correctly converted. When dealing with such content, you may only need{{ archive.Content|safe }}This is because the Markdown conversion has already completed the line break processing.

  2. linebreaksbrFilter:If you just need to convert newline characters in the text to<br/>tags without needing<p>Label the paragraph wrapping, thenlinebreaksbrThe filter will be a simpler, more lightweight choice. Its usage is similar, also needs to be coordinated withlinebreakssimilar, also needs to be coordinated with|safeFilter:

    {{ archive.Description|linebreaksbr|safe }}

  3. Safety warning:Although|safeThe filter can solve the problem of HTML tags not being parsed, but it also means that you trust all the content in the variable. If the content of this variable may come from user input and has not been strictly filtered and verified, then use|safeIt may introduce an XSS vulnerability. Be sure to ensure that you apply it in practice|safeThe content source of the filter is可信的, or it has been strictly processed by the backend security.

In short, when you find that in AnQiCMS,linebreaksthe filter fails to convert multiline text into HTML tags correctly, the most common solution is to append it after its|safeFilter. Understand the default HTML escaping behavior of the template engine as well as|safeThe role of the filter will help you develop templates more efficiently and securely.

Frequently Asked Questions (FAQ)

  1. Ask: Can I use it simultaneouslylinebreaksand handle the same block of content with the Markdown editor?Answer: It is usually not recommended to do this. The Markdown editor itself will convert multi-line text and paragraph syntax to HTML tags, and then uselinebreaksThe filter may cause redundant HTML structure or unexpected nesting issues. When entering content through a Markdown editor, you usually just need to use|safeThe filter ensures that the converted HTML content is rendered correctly.

  2. Question:|safeWhat security risks do filters have?Answer:|safeThe filter informs the template engine that the content it processes is "safe" HTML and does not require escaping. This means that if the content contains malicious scripts (such as user input that<script>alert('XSS')</script>), the browser will execute these scripts directly, thereby causing a cross-site scripting (XSS) risk. Therefore,|safeThe filter should only be used for content sources that you completely trust and have confirmed to be free of malicious code.

  3. Question: Besides,linebreaksWhat other filters might be needed in AnQiCMS?|safeto be used together?Answer: Any filter or variable output that generates or contains HTML tags, if you want these HTML tags to be parsed by the browser instead of being escaped and displayed, you need to|safeFilter. For example, rich text content read from a database, or HTML fragments generated by custom logic, may need|safe. But always keep in mind the security considerations.