Building and managing websites in AnQi CMS, we often take advantage of its powerful and flexible template system to present colorful content.The template engine of AnQi CMS borrows the syntax of Django templates, bringing us a familiar development experience and powerful features.Automatic escaping.

This article will delve into how to cleverly usesafeFilter, safely and elegantly output HTML code passed from the backend, while avoiding unnecessary escaping.

Understand the template security mechanism of Anqi CMS

At the beginning of the design of Anqi CMS,safetyPlaced at the core position, this is not only reflected in its high-performance architecture built on the Go language, but also in every detail of the front-end template rendering. When we retrieve data from the database or other backend services and output it directly in the template, for example, an article title{{ archive.Title }}or a brief introduction{{ archive.Description }}The template engine will default to escaping HTML special characters in this content.

What is escaping?In simple terms, it is the act of converting<Converted to&lt;,>Converted to&gt;,"Converted to&quot;

This default automatic escaping mechanism is undoubtedly an important defense line for website security. However, in certain specific scenarios, we need the HTML code passed from the backend to be rendered by the browserNormal parsing and display

safeThe role of the filter: unlock the presentation capabilities of HTML

To solve the above problem, the template engine of Anqi CMS provides a namedsafefilter.safeThe core function of the filter is very intuitive: it tells the template engine,"I trust this content, do not escape it as HTML, and output it as HTML code directly."

When we pass a variable throughsafeAfter filtering, the template engine will consider the content of the variable as "safe", and it can be rendered directly as HTML code on the page.All HTML tags stored or generated on the backend will be parsed and displayed by the browser according to their original intent, rather than displayed as plain text.

Its basic syntax is very simple, just add the pipe symbol after the variable|andsafeas follows:

{{ 你的变量 | safe }}

Actual application scenarios: When to usesafeFilter?

UnderstoodsafeThe role of the filter, let's take a look at some typical and important application scenarios of it in the actual content operation of Anqi CMS.

  1. Rich text content on the article/product detail page:This is the most common and important use case.The rich text editor in the AnQi CMS backend allows us to edit complex content containing images, links, formatted text (such as bold, italic, lists), and more.archiveDetailWhen the label is obtained from the front-end, for example,archive.Contentit is itself a piece of HTML code. If it is not processed with,safethen the article content will display as one with<p>/<strong>This is plain text instead of the formatting effect we expected.

    Example:

    Without usingsafe(Wrong example, HTML tags will be displayed):

    <div>
    {# archive.Content 此时会被转义，显示原始HTML标签而不是渲染效果 #}
    {{ archive.Content }}
</div>

    Usesafe(Correct example, HTML effects will be rendered):

    <div>
    {# archive.Content 通过 safe 过滤器，其HTML内容将正常渲染 #}
    {{ archive.Content | safe }}
</div>

  2. Custom HTML code stored in the field:AnQi CMS supports flexible:Content ModelandCustom fieldsFunction.Sometimes, we create custom fields for specific content types (such as articles, products) to store special content that is not suitable for rich text editors but needs to be presented in HTML format, such as a special promotional banner code, an embedded video player code, or a complex product specification table.safeFilter.

    Example:Suppose we have a custom field named:promotion_htmlto store promotional HTML code:

    {% archiveDetail promotionHTML with name="promotion_html" %}
<div class="promotion-area">
    {# promotionHTML 变量中存储的HTML代码将被正确解析 #}
    {{ promotionHTML | safe }}
</div>

  3. Markdown content converted to HTML and output:If your content uses a Markdown editor, and the content needs to be processed on the backend or through a specific template filter (such asrenderFilter）converted to HTML and then output to the frontend, the converted HTML also needssafeFilter to ensure correct rendering.

    Example:AssumearchiveDetailTags during processingContentfields, throughrender=trueParameters to convert Markdown to HTML:

    {% archiveDetail articleContent with name="Content" render=true %}
<div class="article-body">
    {# 经过 Markdown 渲染后的 HTML 内容，需要 safe 过滤器来保证其正常显示 #}
    {{ articleContent | safe }}
</div>

Security risks and **Practice: UsingsafePrecautions

safeThe filter can help us achieve flexible HTML content display, but as its name suggests, it is“Believe”Content is safe under the premise of unescaping. Therefore, it is also a double-edged sword, which may bring potential security risks to the website if used improperly.

The most fundamental principle is: only use HTML content from sources that are 'fully trusted'safeFilter.

What is a 'fully trusted' source?

  • Rich text content edited and published directly by the administrator:Generally, we consider website administrators to be trustworthy and not to intentionally publish malicious code.
  • HTML content that has been strictly processed and sanitized: