In AnQiCMS template development, to ensure the correct display of content and the security of the website, we often use some built-in filters to process special characters. Among them,escapeandescapejsThe filter is a very important tool, serving different scenarios and having different types of special characters to be escaped.
escapeFilter: The Guardian of HTML Safe Escaping
escapeThe filter is mainly used to escape special characters that may be incorrectly parsed as HTML code by the browser, thus preventing security vulnerabilities such as cross-site scripting (XSS) and ensuring that the content is displayed as plain text as expected.
In the AnQiCMS template,escapeThe filter will mainly target the following five core HTML special characters for escaping:
<(less than sign)will be escaped as<. If it is not escaped, the browser may interpret it as the start of an HTML tag.>(Greater than sign)will be escaped as>. Similarly, it may also be interpreted as the end of an HTML tag.&(and sign)will be escaped as&。Because the ampersand is the start of an HTML entity reference, not escaping it may cause the content after it to be incorrectly parsed as an HTML entity."(double quotes)will be escaped as"In HTML attribute values, if double quotes are used without escaping, they may end the attribute value prematurely, posing a security risk.'(single quote)will be escaped as'In HTML attribute values (or in JavaScript strings), if single quotes are used without escaping, the string may end prematurely, causing issues.
It is worth noting that AnQiCMS's template engine is enabled by default for automatic escaping. This means that in most cases, you do not even need to explicitly useescapeFilter, the special characters included in the template output content will also be automatically escaped. This is an important security feature aimed at protecting websites from XSS attacks by default.
However, in certain specific scenarios, you may need to intervene manually, such as: when you go through{{ variable|safe }}The filter disabled the automatic escaping of a specific variable, but then wanted to re-escape part of its content in HTML; or when going through{% autoescape off %}After the entire code block is automatically escaped by the instruction, when it is necessary to re-enable escaping for specific variables,escapeThe filter becomes particularly important.
For example, if you have a variableuserInputincludes<script>alert('xss');</script>such content, and it is desired to be displayed on the page as text rather than executed as a script:
{# 默认情况下，AnQiCMS会自动转义，所以下面的输出是安全的 #}
<p>{{ userInput }}</p>
{# 如果您显式关闭了自动转义，但又想转义特定部分，可以这样使用 #}
{% autoescape off %}
<p>{{ unsafeHtmlContent|escape }}</p>
{% endautoescape %}
In the above example,|escapeEnsured that special characters in the content are converted to HTML entities, thus safely displayed as plain text in the browser.
escapejs过滤器：JavaScript 环境下的字符净化器
whileescapejsThe filter serves different scenarios: it focuses on preparing strings for the JavaScript environment. When you need to output backend data as part of JavaScript code to the front end, escapejsCan effectively prevent JavaScript syntax errors or injection vulnerabilities caused by special characters.
WithescapeMainly for escaping HTML special characters, which is different fromescapejsThe escaping rules are more strict and comprehensive to meet the requirements of JavaScript syntax. It will convert all characters except letters (a-zA-Z), numbers (0-9), spaces, and slashes (/) into Unicode escape sequences (\uxxxxThe form).
This means:
- Newline characters, carriage return: For example
\nwill be escaped as\u000A,\rwill be escaped as\u000D. - Quotation marks': single quotes
'will be escaped as\u0027, double quotes"will be escaped as\u0022. - 反斜杠:
\will be escaped as\u005C. - Other special symbols: For example
!/@/#/$/%etc., as well as various non-ASCII characters (such as Chinese) will be escaped as\uxxxxForms, to ensure they are not misunderstood or corrupted in JavaScript string literals.
For example, when you need to safely embed a variable containing complex text (which may include quotes, newlines, or even HTML tags) into a JavaScript string:
<script>
var message = "{{ backendMessage|escapejs|safe }}";
alert(message);
</script>
In this example,backendMessageThe content of the variable will be processed firstescapejsIfbackendMessageYesHello, "World"!\nThis is a test.then the processing ofescapejsmay change afterHello, \u0022World\u0022!\u000AThis is a test..|safeis necessary here, because it tells the template engine:escapejsThe content has been processed into a JavaScript-safe string and can be output directly without undergoing the default HTML escaping (otherwise, HTML escaping may escape again)\Symbol, leading to JavaScript parsing failure).
Summary: Choose the appropriate tool.
In short,escapeandescapejsIt is one of the two different but equally important escaping mechanisms in the AnQiCMS template, each serving HTML and JavaScript in different context environments.
escapeFilterEnglish: mainly used for HTML text output, escaping< > & " 'Prevent XSS and HTML structure corruption.In AnQiCMS, due to default automatic escaping, it is more often used explicitly under specific requirements (such as re-enabling after disabling automatic escaping).escapejsFilter：专门用于JavaScript字符串输出，将大部分非字母、数字、空格、斜杠的字符转义为Unicode序列，确保JavaScript语法正确性和防止JS注入。
Correctly understanding and using them can help us build websites that are both secure and robust, avoiding page rendering errors or potential security vulnerabilities caused by special characters.
Common Questions (FAQ)
Q1: Why didn't I useescapeFilter, but the HTML tags on the page are still escaped?
A1:AnQiCMS's template engine is default enabled autoescape (auto). This means, for website safety, all through{{ 变量 }}The content output in form, if it contains HTML special characters (such as</>/&English），will be automatically converted to HTML entities to prevent cross-site scripting (XSS). Therefore, you usually do not need to use explicitly.escapeFilter, because the system has already done this work for you.
Q2: Can I use it directly?escapeFilter to escape JavaScript code?
A2:No.escapeThe filter mainly targets special characters in the HTML environment for escaping. The character set and method it escapes are different from those required by the JavaScript environment. If youescapeUsed for JavaScript code, may cause JavaScript syntax errors or fail to achieve the expected security effects. Please make sure to use the one specially designed for JavaScript.escapejsFilter to escape string data that needs to be used in JavaScript.
Q3: How can I ensure that a piece of content is treated as safe HTML and displayed directly on the page without being escaped as plain text?
A3:In this case, you can use|safea filter. For example{{ trustedHtmlContent|safe }}.|safeThe filter tells the template engine that the content of this variable is reviewed and trusted, and can be safely output as raw HTML without automatic escaping. However, please use it with caution.|safeEnsure that the content you output is safe, otherwise it may introduce XSS vulnerabilities.