As an experienced website operator proficient in AnQiCMS, I am well aware of the importance of content security output and also need to ensure the complete presentation of high-quality content.In AnQiCMS template development, dealing with HTML content often encounters a core issue: how to ensure that these HTML contents are rendered as expected rather than being escaped to plain text by the template engine?This not only involves the display effect of the content, but also concerns the security of the website.
AnQiCMS uses a syntax similar to Django template engine, one of its core design philosophies is security. This means that when you output variables directly in the template, for example,{{ 变量 }}The template engine will default to escaping special HTML characters within it. For example,<div>Hello</div>will be escaped as<div>Hello</div>，The browser will display it as plain text instead of rendering it as an HTML element.This default automatic escaping mechanism is an important security measure to prevent cross-site scripting (XSS) attacks.It effectively prevents malicious users from destroying websites or stealing user data by injecting HTML or JavaScript code.
However, in the actual content operation, we often need to output content that itself contains valid HTML structure.For example, the article content edited with the AnQiCMS backend rich text editor may contain paragraphs, images, links, and other HTML tags.If this content is also escaped, the frontend display of the website will be affected, and the user will see a chaotic HTML source code.To solve this problem, AnQiCMS provides a clear way to indicate to the template engine which content is trusted and safe HTML that does not require escaping.
UsesafeThe filter explicitly marks safe HTML
In AnQiCMS templates, the most commonly used and most direct method is to usesafeFilter. When you are sure that the HTML content contained in a variable is safe and needs to be output as is, you can apply it|safeFilter. This filter tells the template engine that the value of this variable is 'safe' HTML and can be output directly without escaping.
For example, on the article detail page, we usually obtain the full text content of the article from the database.This content is edited by the backend rich text editor and inherently contains HTML tags.Now, you need to make sure they render correctly.|safeFilter:
{# 默认用法，自动获取当前页面文档，并安全输出其内容 #}
<div>文档内容：{% archiveDetail archiveContent with name="Content" %}{{archiveContent|safe}}</div>
{# 对于自定义字段，如果也可能包含HTML，同样可以应用 `|safe` #}
{% archiveDetail myCustomHtmlField with name="MyCustomHtmlField" %}
<div>我的自定义HTML字段：{{myCustomHtmlField|safe}}</div>
Please note,archiveDetailTags during processingContentWhen the field is, if the background has enabled the Markdown editor and setrender=true, it will first convert Markdown to HTML. At this point,|safeIt is still the key to ensure that the converted HTML is not escaped.
UtilizeautoescapeTag control block escaping
Except for using for a single variablesafeIn addition to the filter, AnQiCMS also providesautoescape标签，用于控制模板中某个特定区块的HTML自动转义行为。This is very useful when you need to handle multiple variables that may contain HTML within a code block, or when you want to temporarily disable automatic escaping.
autoescapeThere are two states for the tag:onandoff.
{% autoescape on %}：Explicitly enable HTML automatic escaping, even if it is already enabled by default.{% autoescape off %}：Disable HTML automatic escaping.
一个使用autoescape off标签的例子如下：
{% autoescape off %}
<p>以下内容将不会被自动转义：</p>
<div>
{{ some_html_variable }}
{{ another_html_string }}
{# 这里的 <script> 标签如果来自变量，也不会被转义，需要特别小心 #}
{{ "<script>alert('Hello from AnQiCMS!');</script>" }}
</div>
{% endautoescape %}
Use{% autoescape off %}When labeling, you must be particularly careful.It will affect the output of all internal variables, meaning that any user input that has not been strictly sanitized by the backend, if outputted within this block, may introduce an XSS vulnerability.Therefore, unless you have full trust and control over the sources and security of all content within this block, it is not recommended to widely use this tag.|safeFiltering is a more refined and secure approach.
**Practice and Safety Considerations
As a website operator, safety is always the top priority when outputting HTML content in AnQiCMS templates.
- Trust Content SourceEnglish: Only for content created by administrators or strictly filtered and verified by the backend from the AnQiCMS backend rich text editor
|safeFilter. This content is usually considered trusted. - Never trust user input directly.For any unprocessed user comments, messages, or other original input content submitted by users, even if you think they are HTML, do not use them directly
|safeor{% autoescape off %}These contents must be strictly HTML sanitized and validated on the server side to ensure that no malicious scripts are included. - Understand the risk: Every time used
|safeFilter or{% autoescape off %}Tags, all of which mean that you are taking on the risk that this content may introduce XSS vulnerabilities. Always assess and understand these risks. - Review code：Regularly review template code, especially those that use
|safeorautoescape offparts, ensuring their usage is reasonable and safe.
by appropriately applying|safefilters and using them cautiously when necessaryautoescapeTags, you can effectively control the output of HTML content in the AnQiCMS template, ensuring the correct rendering of website content and maintaining the security of the website.
Frequently Asked Questions
Why does AnQiCMS template default to escaping HTML content?
AnQiCMS template engine defaults to escaping HTML for website security considerations, the main purpose is to prevent cross-site scripting attacks (XSS). By turning>/</&Templates can ensure that special characters are escaped as HTML entities, thus the template engine can prevent malicious users from injecting HTML or JavaScript code to execute unauthorized operations, thereby protecting the website and users' safety.
If I need to output containing<script>How should I operate the code snippet with tags?
In most cases, it is strongly recommended not to output containing directly in the front-end template<script>Label code snippet, especially when these codes may come from user input, as this can pose a significant security risk. If it is indeed necessary to output this kind of HTML in specific scenarios (for example, the content is obtained from a completely trusted source and has been strictly validated and sanitized on the backend), you can use|safefilter. For example:{{ trusted_script_content|safe }}.But in practice, it is better to avoid this approach, or encapsulate the script logic in an external JavaScript file, and pass data dynamically through the backend rather than passing the script code directly.
|safefilters and{% autoescape off %}What is the difference between tags?
|safefilters and{% autoescape off %}Tags are used to disable HTML escaping in features, but their scope and usage scenarios differ.|safeThe filter is applied to a single variable, it only tells the template engine that the value of this variable is safe and does not need to be escaped.{% autoescape off %}The tag is a block-level tag, it will turn off the automatic HTML escaping of all variables inside it until it meets{% endautoescape %}.|safeprovides finer control,autoescape offIt affects a larger code block, and a more comprehensive security assessment is required when used.