When using AnQiCMS for website content management and template development, we often encounter a problem related to HTML content display: why does the rich text content that I edit in the background display as raw code with angle brackets on the front end instead of a beautifully formatted layout? This is actually the "automatic escaping" mechanism of the AnQiCMS template engine at work, and to solve this problem,safeFilter has become the key tool we must master.

Why does automatic escaping occur?

AnQiCMS template engine, by default, will escape all content output to the page as HTML entities. This means that if you enter<p>这是一段文本</p>The template engine converts it for safety,&lt;p&gt;这是一段文本&lt;/p&gt;After this processing, the browser will display these escaped contents as plain text, rather than parsing them as HTML tags.

This 'safety first' design philosophy is mainly to prevent a common network attack method - cross-site scripting (XSS).If the template engine does not automatically escape user input, malicious users can insert malicious JavaScript code into comments, messages, or any other input fields.When other users browse pages containing this malicious code, these scripts will execute in their browsers, which may lead to serious security issues such as information leakage and session hijacking.AnQiCMS 作为一个致力于提供安全解决方案的系统，其默认的自动转义行为正是这种安全考量的体现。

safeFilter: When Must It Be Used?

Although automatic escaping is for security reasons, there are times when we indeed need to display content with HTML structure correctly on the page, such as the formatting of articles, custom style codes, images, and links, etc.This is where we need to explicitly tell the AnQiCMS template engine: 'This part of the content is safe, please do not escape it, and parse it directly as HTML to display.'safeWhat is the Role of a Filter?

Here are Some That We Must UsesafeTypical Scenarios of Filters:

  1. Article/Document Details Content (Archive/Document Content)This is the most common use case. When we use a rich text editor to write articles in the background, it will include heading levels (<h1>,<h2>), paragraphs (<p>）、picture（<img>), link (<a>）and various formats (bold, italic, etc.). These are HTML structures. When we obtain and display the article througharchiveDetailtagsContentfield, if not addedsafeFilter, all these HTML tags will be escaped, causing the page to display the original code instead of formatted articles.

    For example, when you want to display the content of an article, the correct way is:

    {% archiveDetail articleContent with name="Content" %}
{{ articleContent|safe }}

    Here are the|safeIt is to tell the template engine,articleContentThe content in the variable is reliable HTML and can be rendered directly.

  2. 分类详情/单页面详情内容 (Category/Page Content)Similar to the article details, if we fill in rich text format for the category or single page in the background category management or single page managementContentContent (for example, a detailed introduction to our page or a detailed description of a category), and bycategoryDetailorpageDetailtags to retrieve and display this content, the same applies tosafeFilter to ensure that the HTML structure is parsed correctly.

    For example, display detailed descriptions of categories:

    {% categoryDetail categoryContent with name="Content" %}
{{ categoryContent|safe }}

  3. Rich text content in custom fieldsAnQiCMS allows us to define additional custom fields for content models or categories. If a custom field is designed to store rich text information (such as product specifications, event descriptions, etc.), and we indeed use a rich text editor to fill these fields in the background, then when outputting the values of these custom fields in the template, it is also necessary to applysafeFilter.

    Suppose you have a custom field.product_description_htmlIt may be used like this:

    {% archiveDetail productDescriptionHtml with name="product_description_html" %}
{{ productDescriptionHtml|safe }}

  4. The backend configuration may contain fields with HTML.In the global settings or contact information settings modules of the website, some text fields may also allow administrators to enter a small amount of HTML tags to achieve specific display effects. A common example is the copyright information of the website.SiteCopyright)，admin may wish to include a link to the filing official website in the copyright information<a>Label.

    For example, display copyright information:

    {% system siteCopyright with name="SiteCopyright" %}
<p>{{ siteCopyright|safe }}</p>

    In this case, usesafefilter to make<p>or<a>The tag is correctly parsed by the browser.

UsesafePrecautions

AlthoughsafeThe filter solves the problem of displaying HTML content, but we must be aware that it is aDisable security protectionswitch. UsesafeThis means that you have guaranteed the security and reliability of this part of the content.

  • The source of trust is the premise.: Only use content sources that you trust completely.safeFilter. Typically, this refers to content that is created or edited directly by website administrators through the backend rich text editor.
  • Be alert for user input.:must notUsing for any user input content that has not been strictly purified (such as comments, messages, articles submitted by users)safeFilter.Because users may exploit this vulnerability to carry out XSS attacks.Even if your AnQiCMS backend editor has a security filtering mechanism, you should handle HTML content from external or untrusted sources with caution.
  • Rendering Markdown contentIf the content is stored in Markdown format and converted to HTML by therender=trueparameter, then the resulting HTML also needssafeThe filter must be enabled to display correctly.renderThe filter is responsible for converting Markdown to HTML strings,safeThe filter is responsible for telling the template engine that this HTML string is safe and can be output as-is.

In short,safeThe filter is a powerful and necessary feature in AnQiCMS templates, which gives us the flexibility to display rich text content.But as a website operator, we should treat it like a double-edged sword, always placing the safety of the content and the reliability of the source first, ensuring that the website is both beautiful and secure.

Common Questions (FAQ)

Q1: UsesafeDoes the filter mean that the website is not secure?A1: Not at all.safeThe filter itself is a neutral tool.It simply tells the template engine that 'this part of the content is confirmed to be safe, please render it directly as HTML'.If it is used to display rich text content edited by website administrators that is trustworthy, it is completely safe.If used incorrectly to directly display user-submitted, unreviewed, and unsanitized (sanitization) original HTML content, it may open a potential cross-site scripting (XSS) vulnerability, thereby making the website insecure.

Q2: I am using a Markdown editor to write content in the background, and it needs to be added when displayed on the front end.safeFilter?A2: Yes, still needed. Markdown editors will convert your Markdown syntax content to HTML strings. When you go througharchiveDetailorpageDetailThe label acquisition and display of these contents is usually done throughrender=trueParameters to trigger the Markdown to HTML conversion.The result after conversion is an HTML string, the template engine will still automatically escape it.|safethe filter so that the browser can correctly parse and display the converted HTML structure.

Q3: BesidessafeFilter, does AnQiCMS have other ways to control HTML escaping?A3: Yes. AnQiCMS template engine also supportsautoescapeLabel. You can use{% autoescape off %}and{% autoescape on %}to enable or disable the automatic escaping feature within a template code block.{% autoescape off %}块内的所有内容都将不再自动转义，相当于对所有输出都隐式地应用了EnglishsafeFilter, but this usage is usually not recommended, as it may inadvertently introduce security risks. UsuallysafeApplying filters to specific variables is a more refined and recommended practice.