In AnQiCMS template development, for the safety of the website, the system defaults to automatically escaping all HTML content output to the page. This means that when you directly output a variable containing special HTML characters in the template, for example,<script>alert('XSS')</script>，AnQiCMS 会将其转换为 English&lt;script&gt;alert(&#39;XSS&#39;)&lt;/script&gt;。这种机制能够有效防止跨站脚本（XSS）攻击，保护网站及用户数据的安全。

However, in the actual content operation, we sometimes need to display the real HTML content, such as rich text edited in the background, embedded third-party code snippets, or some predefined layout structures. In this case, AnQiCMS provides a flexible mechanism to control the automatic escaping function of HTML content, with the core beingautoescapeTags andsafeFilter.

Understand the default automatic escaping mechanism

The default behavior of AnQiCMS template engine (based on Django template syntax in Go language) is security first.No matter what variable you output, if it may contain HTML tags or special characters, the system will automatically convert it to HTML entities.This default behavior runs through the entire template, saving you the trouble of manually handling escaping, and also providing the first layer of security.

For example, if you have a variableuser_descriptionwith the value<b>AnQiCMS</b> 是一个 <i>优秀</i> 的内容管理系统output directly in the template{{ user_description }}when you see&lt;b&gt;AnQiCMS&lt;/b&gt; 是一个 &lt;i&gt;优秀&lt;/i&gt; 的内容管理系统, not bold and italic text.

Useautoescapetags control the scope of escaping

When you need to turn off or turn on automatic escaping in a piece of template code,autoescapeThe label comes into play. It allows you to define a clear area within which to change the default escape behavior.

Turn off automatic escaping:{% autoescape off %}

If you have a piece of safe HTML content that you want to output exactly as it is, without escaping it into HTML entities, you can wrap this content with{% autoescape off %}and{% endautoescape %}tags.

{# 默认情况下，这里的内容会被转义 #}
<p>{{ some_raw_html }}</p>

{% autoescape off %}
    {# 在这个区块内，HTML 内容将不会被自动转义 #}
    <div>
        {{ some_trusted_html_from_database }}
        <p>这里可以安全地输出<span>原始的</span>HTML。</p>
    </div>
{% endautoescape %}

{# 这个区块之后，自动转义又会恢复默认开启状态 #}
<p>{{ another_potentially_unsafe_input }}</p>

This method is very suitable for fetching rich text content that has been strictly reviewed by administrators from the background, or for HTML fragments that you manually write and are confident have no security vulnerabilities.

Enable automatic escaping:{% autoescape on %}

Although AnQiCMS is enabled by default for automatic escaping, if you need to escape the content of a child area within a certain parent areaautoescape offyou can use it.{% autoescape on %}This can help you control the escaping behavior of each part more finely when dealing with complex or nested template structures.

{% autoescape off %}
    <p>这段内容不会被转义。</p>
    {% autoescape on %}
        {# 即使父级是 off，这个子区域的内容也会被转义 #}
        <p>这里的 {{ user_input_again }} 会被转义。</p>
    {% endautoescape %}
    <p>这段内容依然不会被转义。</p>
{% endautoescape %}

UsesafeThe filter disables escaping for individual variables.

If you only need to disable auto-escaping for a specific variable in the template instead of an entire code block,safethe filter is a more concise choice. You just need to add|safe.

<p>这是来自管理员的富文本内容：{{ article.content|safe }}</p>
<p>这个用户评论：{{ user_comment }}</p> {# 用户评论依然会被转义 #}

Use|safe相当于您向模板引擎声明：“我确认”article.content这个变量的内容是安全的，请直接按 HTML 格式输出，不要进行转义。”}]

escapeFilter: Scenes where forced escaping is required

WithsafeThe opposite of the filter function isescapeA filter that is used to explicitly escape content as HTML. However, since AnQiCMS defaults to auto-escaping, it is usually sufficient to directly output the variable{{ some_content }}Already escaped. If additional|escapefilters are added, it may

escapebe used more commonly withautoescape offLabel used in conjunction, when you are in an area where automatic escaping is turned off, and you need to force escape a variable within it, you can use it.

{% autoescape off %}
    <p>这个区块的内容不会被自动转义。</p>
    <p>但是这里的 {{ some_variable_that_needs_escaping|escape }} 会被转义。</p>
{% endautoescape %}

**Practice and Safety Considerations

When deciding to turn off automatic escaping or usesafeFilter the data with caution.These features should only be applied to HTML content that you fully trust and confirm does not contain malicious code.Any content from user input, which is not strictly filtered, should always be automatically escaped to effectively prevent cross-site scripting (XSS) attacks and protect the website and users' safety.

In summary, understand and apply flexiblyautoescapeTags andsafeFilter, it will help you in AnQiCMS template development, ensuring that the website content is displayed in a rich and varied manner while also building a solid and reliable security barrier for the website.

Common Questions (FAQ)

Q1:autoescapeTags and|safeWhat are the main differences between the filters?

A1: The main difference lies in the scope of action.autoescapeLabels are used to control onecode block(from{% autoescape off %}to{% endautoescape %}to) the HTML escaping behavior,|safeFilter is used to controlIndividual variablesof escape. If you have a large block of rich text content to output, usingautoescape offis more appropriate; if you only occasionally need to output the original HTML for one or two variables, then|safeFilter is more convenient.

Q2: When should we useautoescape offor|safeFilter?

A2: Both of these methods should be used when youFully trustedContent source is used.For example, the article detail page content edited by the back-end administrator through the rich text editor, or the hard-coded, confirmed secure HTML structure in the template.For any content that comes directly from user input and has not been strictly filtered, these methods should be avoided to prevent potential XSS attacks.

Q3: Why is it sometimes used|escapeFilter will escape the content twice?

A3: AnQiCMS's template engine is enabled by default for automatic escaping.This means, when a variable is output, it has already undergone an escape.|escapeFilter, then the content will be escaped twice. For example,<The first time it is escaped into&lt;, and the second time it may be escaped into&amp;lt;.|escapeFilter is usually used only after you have already used{% autoescape off %}Closed within the auto-escaping region, you need to use it explicitly to manually escape specific variables.