In the template development and content operation of Anqi CMS, sometimes we need to directly display HTML code or run JavaScript scripts on the page instead of having them parsed by the browser as plain text.This usually occurs in scenarios where third-party statistical code, ad scripts need to be embedded, or code examples need to be displayed in article content.However, for security reasons, Anqi CMS defaults to escaping content output to templates to prevent security vulnerabilities such as cross-site scripting (XSS).

To safely display HTML or JS code in templates without being escaped, we need to understand several key mechanisms provided by the security CMS.

Understand the default security mechanism of AnQin CMS

Firstly, it is crucial to understand the default behavior of the Anqi CMS.As an enterprise-level content management system, Anqi CMS attaches great importance to security from the very beginning.When you enter any content that may contain HTML tags or JavaScript code in the background and try to output it directly in the front-end template, the system will default to performing HTML entity encoding.<script>tags will be converted to&lt;script&gt;,<p>tag will become&lt;p&gt;This mechanism, although it may seem inconvenient in some cases, is an effective defense against XSS attacks on websites.

Remove escaping:safeFilters are crucial

when you are sure that the content you need to output is safe and reliable, and you want it to be normally parsed as an HTML element or executed as JavaScript code, you can use the safe CMS template engine provided bysafeFilter.safeThe filter tells the template engine that the content it processes has been explicitly marked as “safe” by the developer, and does not require HTML escaping and can be output directly.

Usage:

You only need to add it after the variable that needs to be unescaped|safe.

For example, if you have a variablecustomHtmlStored with custom HTML content:

<div>
    {{ customHtml|safe }}
</div>

Or, when you need to embed a JavaScript statistics code:

<head>
    <!-- 其他头部内容 -->
    <script>
        {{ statisticCode|safe }}
    </script>
</head>

Intag-tongji.mdIn the document, it also mentions similar usage:{{- pluginJsCode|safe }}. This indicates that for JS code snippets that need to be executed directly, usingsafefilters is the standard processing method.

Application scenario:

  1. Embed rich text in the article or page content:If you enter rich text content with complex HTML structures (such as custom layout tables, reference blocks with specific styles) in the background content editor, and you want this HTML to be correctly parsed by the front end. Normally, likearchiveDetailis obtained from the labelContentField, you will see something similar{{archiveContent|safe}}Usage, this ensures that the rich text format of the article content is preserved.
  2. Embed third-party scripts:JavaScript code snippets provided by services such as Google Analytics, Baidu Statistics, and online customer service systems need to be directly inserted into the page.<head>or<body>Only then can it work normally.
  3. Display code example:If you want to display HTML, CSS, or JavaScript code snippets on a webpage without having them executed by the browser, but also want them to appear with syntax highlighting or similar features, it is usually preprocessed on the server side into HTML entities (for example, using a Markdown converter), and then throughsafeFilter output to maintain its format. However, if it is only for displaying code without execution, it is more recommended to put it in<pre>and<code>Label, and ensure that the content itself has been properly escaped (or escaped on the server side, then)safeOutput).

Risk alert:

safeThe filter provides flexibility, but also comes with potential security risks. Once used,safeThis means that you completely trust the content in the variable.If the variable comes from user input or unfiltered external data, it may lead to XSS attacks.Malicious users may inject JavaScript code to steal sensitive information, tamper with page content, or hijack user sessions.safeThe content source of the filter output is reliable and has undergone strict filtering and verification.

Local control of escaping:autoescapetags

ExceptsafeThe filter, the template engine of AnQi CMS also providesautoescapeTag block, used to turn on or off the automatic escaping feature in a specific area.

Usage:

{% autoescape off %}
    <!-- 在这个区块内的所有变量输出都不会被转义 -->
    <div>{{ variableWithHtmlContent }}</div>
    <script>{{ anotherScriptVariable }}</script>
{% endautoescape %}

{% autoescape on %}
    <!-- 在这个区块内的所有变量输出都会强制被转义 -->
    <div>{{ potentiallyMaliciousContent }}</div>
{% endautoescape %}

autoescapeLabels are used for scenarios where it is necessary to uniformly escape multiple variables within a large code block, avoiding the need to add an escape to each variable|safeor|escape.

Markdown content special handling

Inhelp-markdown.mdThe document mentions that the new version of the Aanqi CMS supports Markdown editor, and after enabling it, the document content will be 'automatically converted to html from Markdown'.This means that if you write content using Markdown syntax in the background (including Markdown-formatted HTML or JS code blocks), the system will automatically convert it to HTML and display it.

For likearchiveDetailtags obtainedContentfield, it also supports onerenderparameter to manually control the behavior of Markdown rendering:

{# 启用Markdown转HTML #}
<div>文档内容：{% archiveDetail archiveContent with name="Content" render=true %}{{archiveContent|safe}}</div>

{# 不进行Markdown转HTML #}
<div>文档内容：{% archiveDetail archiveContent with name="Content" render=false %}{{archiveContent|safe}}</div>

Here is the point to note, even thoughrender=trueConverted Markdown to HTML, the final HTML output may still be required|safeThe filter must be displayed and executed correctly in the browser to avoid HTML tags from being escaped again.

Summary

In the AnQi CMS template, safely displaying HTML or JS code lies in understanding and proper applicationsafeFilter. It provides you with the flexibility to bypass default security escaping, but it also requires you to take responsibility for the source and safety of the content. CombinedautoescapeLabel and understanding of Markdown rendering, you can more accurately control the display behavior of template content, and meet various content operation needs while ensuring website security.

Common Questions (FAQ)

  1. Why does placing HTML code (such as<p>这是一个段落</p>) in the template display as text instead of paragraph style?This is the default security mechanism of the AnQi CMS at work. To prevent potential cross-site scripting (XSS) attacks, the system will default to escaping all output HTML tags.<Converted to&lt;,>Converted to&gt;English.This browser will not parse it as an HTML element, but display it as plain text.|safea filter. For example{{ myHtmlContent|safe }}.

  2. UsesafeAfter the filter, does it mean that any HTML or JS code I embed is absolutely safe?并非如此。safeThe filter only tells the CMS template engine to stop escaping the content. It does not perform any security scan or filter on the content itself. Therefore, usingsafeMeans that you as a developer or operator are fully responsible for the security of this content.If content is from user input, external API, or other untrusted sources, you must perform strict filtering, verification, and disinfection before the content enters the database or is output to the template to prevent the injection of malicious code (such as XSS attacks).safeis a “trust” mark, but the premise of trust is that you have ensured its security.

  3. Can I directly input HTML code or JS script in the content editor of the Anqi CMS backend, and then run it on the front end through the filter?safeCan the filter run it on the front end?Can, but need to distinguish cases and operate cautiously.

    • HTML code:If your content editor supports rich text editing (such as WYSIWYG editor), the editor itself can usually handle and store HTML. When you usearchiveDetailEnglish tags get the article content and add it.|safeWhen the filter is applied, these HTML tags can be normally parsed and displayed.
    • JavaScript script:Although it is technically possible to input in the content editor<script>label it and|safeoutput, but this is not the recommended practice. The content editor will usually remove or escape<script>Tag to avoid potential risks.Even if the editor does not remove it, mixing business logic or statistical scripts into the article content will make website maintenance complicated and difficult to control versions.{{ myScriptCode|safe }}Such variable output. For statistical code, it is usually directly bytag-tongji.mdCoordinated with the system variables mentioned|safeOutput.