In AnQiCMS template, how to output HTML code directly without being automatically escaped?

In AnQiCMS templates, we often need to flexibly control the way content is displayed.You may have encountered such a situation: You carefully formatted a content containing HTML tags in the rich text editor in the background, but when the content is displayed on the front-end page, you find that these tags are displayed as plain text, rather than rendered according to the HTML structure.This is actually a security mechanism that is in operation by default in AnQiCMS and many modern content management systems.

Understanding the automatic escaping mechanism in the template

AnQi CMS is an enterprise-level content management system developed based on the Go programming language, which has always paid close attention to website security from the beginning of its design. It defaults to escaping all variables output in templates, which means that things like<Will become<,>Will become>,"Will become"This mechanism is mainly used to prevent cross-site scripting attacks (XSS). Imagine if a malicious user enters a segment of code in the comment box.<script>alert('您的账户被盗！');</script>Such code, if the system does not escape it directly outputs, then all users accessing this page may execute this malicious script, causing serious security issues.

However, in legal usage scenarios, such as when you enter a piece of text with rich text editor from the backend,<strong>/<p>

AnQiCMS template engine provides two main ways to handle this situation: usingsafefilters andautoescapeLabel.

Method one: usesafefilters to directly output HTML

When you want the template engine to trust the single HTML variable you provide and output it as-is without escaping,safeThe filter is your powerful assistant. It tells the template engine that the value of this variable is 'safe' and can be processed as raw HTML code.

For example, if you enter a text containing HTML in the article content field on the backend, we would usually call it like this:

{# 假设archive是当前文档对象，其Content字段包含HTML内容 #}
{% archiveDetail articleContent with name="Content" %}
<div>
    <p>以下是文章内容：</p>
    {{ articleContent|safe }}
</div>

Here,{{ articleContent|safe }}of|safeIt is the key. It will instruct the AnQiCMS template engine,articleContentThe value of the variable should be considered safe HTML and rendered directly, rather than being escaped. If omitted|safeYou might see similar<p>这是一段<strong>加粗</strong>的文字。</p>Such original strings displayed on the page, rather than the rendered effect.

Similarly, if you have some custom HTML code stored in a variable, you can also usesafeFilter:

{% set customHtml = "<h2>这是自定义的标题</h2><button>点击我</button>" %}
<div class="custom-section">
    {{ customHtml|safe }}
</div>

This is particularly important when using the AnQiCMS rich text editor (such as document content, category content, etc.), as these editors allow users to input rich content containing HTML, and it is almost always necessary to use it in the front-end display.|safeFilter to render correctly.

Method two: useautoescapeTag controls the escaping behavior of code blocks.

If you need to handle multiple HTML segments within a larger code block, or if you want to temporarily disable automatic escaping to embed a whole block of custom code,autoescapeTags provide more flexible control. It allows you to specify whether all variables and text within a region should be automatically escaped.

autoescapeTags need to be used withonoroffparameters, and are used to{% endautoescape %}End its scope.

For example, if you want to embed a piece of HTML script or third-party code that you fully control, and do not want it to be escaped by AnQiCMS, you can do it like this:

{% autoescape off %}
    <p>以下内容在一个特殊区域，不会被自动转义：</p>
    <div>
        {# 即使是可能包含HTML的变量，在这个区域内也会直接输出 #}
        {% set promoCode = "<script>console.log('推广代码已加载');</script>" %}
        {{ promoCode }}
        <a href="#">这是一个普通的HTML链接</a>
    </div>
    <!-- 这里可以放置任何你确信安全的第三方HTML/JS代码 -->
    <iframe src="https://example.com/embed" width="560" height="315" frameborder="0" allowfullscreen></iframe>
{% endautoescape %}

<p>此标签外的区域会恢复默认的自动转义行为。</p>

In{% autoescape off %}and{% endautoescape %}Between all content, including the output of variables, will not be automatically escaped.This is very useful for embedding complex external widgets, advertisement code, or pre-built HTML template fragments.

If you are in a certainautoescape offarea, and you also want a specific variable to be escaped (although this is relatively rare), you can explicitly re-enable it usingautoescape onre-enable:

{% autoescape off %}
    <p>这个区域大部分内容不转义。</p>
    {% autoescape on %}
        <p>但这个嵌套的区块会强制转义：</p>
        <div>{{ "<strong>强调文字</strong>" }}</div> {# 这里会输出 &lt;strong&gt;强调文字&lt;/strong&gt; #}
    {% endautoescape %}
    <p>继续不转义区域。</p>
{% endautoescape %}

Practical scenarios and **practice

Understand and use correctlysafefilters andautoescapeTags can greatly enhance your flexibility in AnQiCMS template development.

1. Rich text editor content:This is the most common scenario. For example, documents (archive）Categories（category）and single-page（pagethe content field (such asarchive.Content/category.Content/page.Content），usually come from the background rich text editor. This content is almost always displayed on the front end, usually requires coordination|safeFilter to render correctly.
2. Custom HTML fragment:When you hardcode some HTML structure in a template, orsystem/contactwhen configuration information obtained with tags such as contains HTML fragments,|safefilters can also be used.
3. Markdown rendered HTML:If you have enabled the Markdown editor in the AnQiCMS background and the content uses Markdown syntax, it will be processed by AnQiCMS'srenderThe output after filter processing is also HTML. In this case, it is still necessary to use|safeto ensure the correct rendering of HTML, for example{{ myMarkdownContent|render|safe }}.
4. embed third-party code:Ad code, statistics scripts, social sharing buttons, etc., these are usually complete HTML or JavaScript fragments, throughautoescape offWrapped up is the way to ensure they work properly.

Safety warning: |safefilters andautoescape offLabels are powerful tools, but they are also a double-edged sword.Make sure that the HTML content you mark as "safe" is completely trustworthy.|safeorautoescape offMay lead to XSS vulnerabilities, posing security risks to your website. In uncertain situations, it is best to keep the default automatic escaping behavior to ensure the overall security of the website.

Summary

AnQiCMS template automatically escapes content by default, which is an important security feature, but it is not uncontrollable. When we need to output raw HTML code, for a single variable, we can use|safeFilter; whereas for a code block, one can use{% autoescape off %}...{% endautoescape %}Labels. Correct understanding and application of these mechanisms can make our website content more abundant, and also effectively maintain the safety line of our website.

---

Common Questions (FAQ)

1. Why does AnQiCMS automatically escape the HTML code I enter?AnQiCMS defaults to HTML-escaping all output content to enhance website security and effectively prevent cross-site scripting attacks (XSS). It converts HTML special characters such as<and>Converted to their corresponding HTML entities (<and>），thus preventing the browser from interpreting these characters as actual HTML tags or executing scripts, protecting your website and users from malicious code.

2.|safefilters and{% autoescape off %}...{% endautoescape %}What is the difference between tags?They are all used to prevent HTML from automatically escaping, but their scope of action is different.|safeFilters are applied to the output of a single variable, for example{{ myVariable|safe }}, it only affects the value of that variable.{% autoescape off %}...{% endautoescape %}Tags affect the entire code block that they wrap, any variables inside that block that are not explicitly|safeprocessed will not be escaped. If you only need to process a few variables,|safeMore concise; if you need to embed a large block of raw HTML or script, `autoescape off