Guide to safely output HTML content in AnQiCMS templates
When using AnQiCMS to build a website, we often need to display content with rich formatting, such as article content, product descriptions, category details, or single-page content. This content is usually input through the rich text editor in the background and naturally contains HTML tags such as<p>/<strong>/<em>/<a>How to correctly and safely output this content with HTML tags in front-end templates is a very important issue.If not handled properly, it can cause abnormal display of the page, and in severe cases, it may introduce security vulnerabilities such as cross-site scripting (XSS).
AnQiCMS's template engine design pays great attention to security.It defaults to handling variable content fetched from the backend and outputted to the template in a "cautious" manner.This means, when you use directly{{ 变量名 }}The form of outputting a string containing HTML tags when, for example, the article content, the template engine will automatically escape the HTML special characters in the content to prevent potential XSS attacks. For example,<Will be escaped to<,>Will be escaped to>,"Will be escaped to"This is the case, so the user on the front end does not see the rendered HTML effect, but the original HTML tag string that has not been parsed, for example, the page will display<p>这是一段加粗的文字</strong></p>.
So, when we determine that the content is safe and needs to be rendered in HTML format, how should we handle it? AnQiCMS provides|safeA filter to solve this problem.
Use|safeFilter to safely output HTML content
|safeThe filter tells AnQiCMS template engine: "This content has been confirmed as safe HTML, please render it directly as HTML code without any escaping."
For example, to output the article content (archive.Content), and make the HTML tags effective, we should write the template code like this:
{# 输出文章正文，并允许HTML标签渲染 #}
<div>
{% archiveDetail articleContent with name="Content" %}
{{ articleContent|safe }}
</div>
Here, archiveDetailTags are used to obtain the detailed content of the article,articleContentThe variable carries the content of the article. Next, by{{ articleContent|safe }}We instruct the template engine toarticleContenttreat the HTML tags within it as trusted code for parsing and rendering.
Similarly, for other content that may contain HTML tags, such as category descriptions,categoryDetailofContentField, single-page contentpageDetailofContentField) orsystemCopyright information in the tag (SiteCopyright), as long as you confirm that this content is strictly reviewed and free of security risks, it can be used|safeFilter:
{# 输出分类详情中的内容 #}
<div>
{% categoryDetail categoryContent with name="Content" %}
{{ categoryContent|safe }}
</div>
{# 输出单页面详情中的内容 #}
<div>
{% pageDetail pageContent with name="Content" %}
{{ pageContent|safe }}
</div>
{# 输出系统设置中的版权信息，如果其中包含HTML标签 #}
<div>
{% system siteCopyright with name="SiteCopyright" %}
{{ siteCopyright|safe }}
</div>
Handle Markdown format content
AnQiCMS also supports Markdown editor.When you use Markdown format to write articles in the background, the system will convert them to HTML code.When outputting such content in the template, you need to ensure the following two points:
- Markdown to HTML:If the Markdown editor is enabled in the background "Global Settings" -> "Content Settings" or
archiveDetailspecified explicitly in the tagrender=true(such as{% archiveDetail with name="Content" render=true %}），AnQiCMS will convert Markdown text to HTML before outputting. - HTML safe rendering:The converted HTML still needs to be used.
|safeThe filter must be applied to render correctly.
Therefore, even if the content is written in Markdown, it is recommended to add it when outputting to the template.|safeFilter:
{# 输出Markdown转换后的文章内容，并安全渲染HTML #}
<div>
{% archiveDetail articleContent with name="Content" render=true %}
{{ articleContent|safe }}
</div>
render=trueEnsure Markdown is converted to HTML, while|safethen these HTML are allowed to be normally parsed by the browser.
When not to use|safefilter (or use|escape)
Though|safeThe filter is very convenient when displaying rich content, but please remember the security implications behind it.|safeIt tells the system “This content is safe, please trust it.” Therefore,Absolutely cannot pass content from untrusted sources (such as user submitted comments, messages, or any unsterilized inputs) directly through|safeFilter outputThis will directly expose the risk of XSS attacks, malicious users may insert JavaScript code, steal user information, modify page content, and even hijack sessions.
If you really need to display HTML tags as plain text (for example, in a code example) or to ensure that any existing HTML tags are escaped, you can rely on AnQiCMS's default automatic escaping behavior, that is, not using|safe. If you need to explicitly escape, you can use|escapeFilter:
{# 显示HTML标签作为文本，而不是渲染它 #}
<pre>
{% archiveDetail codeSnippet with name="SomeHtmlCodeField" %}
{{ codeSnippet|escape }}
</pre>
Here|escapeThe filter will force HTML special characters to be escaped to ensure they are displayed as literal text.
Summary
AnQiCMS's template mechanism provides a basic security protection through default HTML escaping. When you need to render confirmed-safe content with HTML tags, please use|safeFilter. But when handling any content from users or other untrusted sources, always be cautious, ensuring that the content is strictly sanitized and validated on the server side to avoid potential security vulnerabilities.Correctly understand and apply|safeThe filter is the key to ensuring the integrity and content security of the AnQiCMS website.
Frequently Asked Questions (FAQ)
1. Why did my article's main content show up?<p>/<strong>Are HTML tags, rather than the rendered effect?This is usually because you used it directly in the template{{ 变量名 }}The method of outputting the article content, while the AnQiCMS template engine, for security reasons, defaults to escaping HTML special characters. To correctly render HTML tags, you need to use|safeFilter, for example{{ archive.Content|safe }}.
2. The content I get from user comments can be used directly|safeAre the filter outputs?It is strongly recommended not to use directly|safeThe filter outputs unprocessed user comments. User comments may contain malicious HTML tags or JavaScript code, which, if output directly, could cause cross-site scripting (XSS) risks.Before outputting any user-generated content, it is imperative to perform strict server-side data cleaning, filtering, and sterilization, removing all untrusted HTML tags and attributes.Even after purification, it should be carefully considered whether to use it based on specific security policies|safe.
3. Markdown formatted article, if the Markdown editor is enabled on the back end, it still needs to be used|safe?Yes, it still needs to be used|safe. Even if the Markdown editor is enabled on the backend, the system will convert it to HTML, but the template engine will still follow the default escaping rules when outputting these HTMLs.Therefore, to ensure that the converted HTML can be correctly rendered by the browser, you still need to use it in the template.|safeFilter, for example{{ articleContent|safe }}.