How to correctly escape special characters in the AnQiCMS template to avoid display errors?

In website content management, we often need to display text that contains various special characters.If these special characters are not handled correctly, it may cause page layout chaos, abnormal function, and even trigger security vulnerabilities.AnQiCMS provides a powerful mechanism during template rendering to help us handle these special characters, ensuring the correct display of content and the security of the website.

Understanding the challenges posed by special characters

Web pages are constructed with HTML tags, for example<p>used for paragraphs,<strong>used for bold. When our content naturally contains things like</>/&/"/'Such characters, if output directly, may be incorrectly parsed by the browser as part of the HTML structure, rather than displayed as plain text.

For example, if you want to display a piece of code on a pageif (a < b && c > d)The browser may think it is<band>dIs part of the label, causing the display to error. More seriously, malicious users may inject special characters containing scripts (such as<script>alert('xss');</script>If the system does not escape it directly, it will be displayed, which will lead to cross-site scripting attacks (XSS), posing a threat to website security.

AnQiCMS's intelligent default processing: automatic escaping

To address these issues, the AnQiCMS template system took this into consideration from the outset, adopting syntax similar to the Django template engine, one of whose core features isAutomatic escapingThis means that by default, AnQiCMS will automatically escape HTML special characters for variable content passed from the backend to the template.

In particular, when template variables are output, AnQiCMS will automatically convert the following HTML special characters to their HTML entities:

• <to<
• >to>
• &to&
• "to"
• 'to'

This automatic escaping mechanism greatly enhances the security of the website, prevents the majority of common XSS attacks, and ensures the correct display of content, even if it contains characters similar to HTML tags, which will be displayed safely as text.

When do you need to intervene manually:safeFilter

Although automatic escaping is the default and safe option, there are times when we really need to display the original unescaped HTML content.For example, when you use the rich text editor in the AnQiCMS backend to edit an article content with formatting (such as bold, italic, images, etc.) and store this content in the database.When displayed in the template, you want these HTML formats to be correctly parsed and rendered by the browser, rather than displayed as plain text HTML tags.

In this case, you can use|safeThe filter to tell AnQiCMS template system that you trust this content, it should not be automatically escaped.

The method of use is very simple, just add it after the variable you need to output|safeand it is done:

{# 假设 articleContent 变量包含了来自富文本编辑器的 HTML 内容 #}
<div>
    {{ articleContent|safe }}
</div>

Please note:Use|safeThe filter means that you explicitly tell the template system that this content is safe and will not cause XSS attacks or other display issues. Therefore, you should only use it when you completely trust the source of the content, or have strictly filtered the content for security.|safe.

Fine control of escaping behavior:autoescapeTag

In addition to using for individual variables:|safeFilters, AnQiCMS also provides:{% autoescape on/off %}Tags, allowing you to control the escaping behavior of larger blocks in the template.

• {% autoescape off %}: All variables within this label block will beturned offautomatically escaped, which is equivalent to|safe.

  {% autoescape off %}
      <p>这是原始 HTML 内容：{{ rawHtmlFromTrustedSource }}</p>
      <p>这也是：{{ anotherRawHtml }}</p>
  {% endautoescape %}
  

• {% autoescape on %}: All variables within this label block will beenabledautomatically escaping each variable. Since automatic escaping is the default behavior, this tag is usually used inautoescape offWithin the block, use it to re-enable escaping.

  {% autoescape off %}
      <p>显示原始 HTML: {{ trustedHtml|safe }}</p>
      {% autoescape on %}
          <p>这里的内容重新开启自动转义: {{ untrustedText }}</p>
      {% endautoescape %}
  {% endautoescape %}
  

UseautoescapeThe tag can help you control escaping in a local scope without adding each variable individually.|safeFilter, this is very convenient when processing a large number of HTML fragments from the same trusted source.

Special scenario processing:escapejsFilter

When we need to pass data from a template to JavaScript code, it is not enough to perform HTML escaping; we also need to perform JavaScript-specific escaping. For example, if a string contains a newline character\nor single quotes'Inserting it directly into a JavaScript string will cause a syntax error.

At this point, we can use|escapejsA filter to escape content with JavaScript syntax. It will convert special characters (such as newlines, quotes, backslashes, etc.) into a format that JavaScript can safely handle, for example\nto\u000A,'to\u0027.

{# 假设 dataFromBackend 是一个包含特殊字符的字符串，需要传递给 JavaScript #}
<script>
    var myString = "{{ dataFromBackend|escapejs|safe }}";
    console.log(myString);
</script>

Similarly remind: |escapejsWill usually be with|safeUsed together because|escapejsThe filter itself may also generate strings that need to be considered as original output. Its main purpose is to prevent JavaScript syntax errors and injection.

Summary

The AnQiCMS template system provides a solid security foundation for the website through the default automatic escaping feature.In most cases, you do not need to perform any additional operations, the system will handle special characters for you.Only when you really need to render raw HTML or embed data securely in JavaScript code should you consciously use|safeand|escapejsFilter, or{% autoescape %}Label. Always remember to fully understand the potential security risks when using these manual control escaping tools and ensure the reliability of the content source.

Frequently Asked Questions (FAQ)

1. When should I use|safeFilter?You should only use it when you completely trust the content to be displayed, and the content is expected to contain HTML tags|safeFilter.The most typical scenario is to display articles, product descriptions, and other content submitted by users through rich text editors, which includes the formatting that users expect.In all uncertain cases, it is best to let AnQiCMS maintain the default automatic escaping behavior to ensure website security.

2. Why does my JavaScript code not work in the template or show syntax errors?This is usually because you try to embed a template variable containing special characters (such as quotes, backslashes, newline characters) directly into a JavaScript string. In this case, you need to use|escapejsFilter. For example, tovar myVar = "{{ template_variable|escapejs|safe }}";This processing can avoid JavaScript syntax errors and safely pass data.

What is the most common risk if I do not escape special characters?If special characters are not properly escaped, the most common risk is cross-site scripting (XSS). Malicious users may submit in the input box<script>alert('恶意代码')</script>This code, if the website template directly displays this content without escaping, the user's browser will execute this malicious script, leading to security issues such as theft of user information and session hijacking.Additionally, it may cause page layout chaos, some content may not display normally, and other display errors that are not security-related.