Managing website content in AnQiCMS, the rich text editor is undoubtedly our powerful assistant for creating rich and beautiful pages.It allows us to easily add styles, images, links, even tables, making the content bid farewell to boring plain text.However, presenting these carefully edited rich text contents accurately on the website front-end template is a key skill that every AnQiCMS user needs to master.
When we edit content in the AnQiCMS backend through the rich text editor or Markdown editor, this content will ultimately be stored in the database in the form of HTML code. For example, a piece of text you input may become bolded.<strong>加粗文字</strong>The inserted image will be<img src="图片地址" alt="图片描述">.
AnQiCMS uses a template engine similar to Django, one of its design philosophies is security. In order to prevent security risks such as cross-site scripting (XSS), the template engine, by default, will handle all data through{{ 变量 }}The content output in a way that performs HTML escaping. This means that if you directly output a variable containing HTML tags, like{{ archive.Content }}which you add in the editor,<strong>标签并不会被浏览器识别为加粗，而是直接显示为English<strong>加粗文字</strong>这样的纯文本字符串。显然，这并非我们所期望的效果。
Core Solution: Use|safeFilter
In order for the browser to correctly parse and render the HTML content in the rich text editor, we need to explicitly tell AnQiCMS's template engine that this part of the content is safe and should not be escaped. It should be output directly as HTML code. The key to achieving this is to use|safeFilter.
The method of use is very intuitive, just add after the variable that needs to be parsed as HTML|safeThe filter can be applied. Usually, the content of rich text editors is stored in documents (archive) or single pages (page).Contentfield in.
For example, on the article detail page (usuallyarchive/detail.htmlorarchive_detail.htmlIn English, when displaying the article content, you can call it like this:
<article>
<h1>{% archiveDetail with name="Title" %}</h1>
<div class="article-content">
{%- archiveDetail articleContent with name="Content" %}
{{ articleContent|safe }}
</div>
</article>
In this example,{% archiveDetail articleContent with name="Content" %}The tag is used to get theContentfield content and assign it toarticleContentthe variable. Then,{{ articleContent|safe }}This line of code will ensurearticleContentall HTML tags within,<p>、Image<img>English<a>This can be normally parsed and displayed by the browser, rather than as plain text strings.
Similarly, if you need to display rich text content in a single page, the calling method is also similar:
<section>
<h2>{% pageDetail with name="Title" %}</h2>
<div class="page-content">
{%- pageDetail pageContent with name="Content" %}
{{ pageContent|safe }}
</div>
</section>
Handling the specific characteristics of Markdown content
The strength of AnQiCMS lies in the fact that it also supports Markdown editor.Markdown content is different from traditional rich text HTML, it uses a concise markup syntax for writing, and it also needs to be converted into HTML to be displayed on the web page.
AnQiCMSarchiveDetailandpageDetailtag in retrievingContentWhen the field is, if the content settings in the system backend have enabled the Markdown editor, it will intelligently automatically convert Markdown content to HTML.This saves us the trouble of manual conversion.
However, if you need more fine-grained control, such as enforcing Markdown to HTML conversion even when the Markdown editor is not enabled, or vice versa, preventing its rendering (possibly because you want to use a JavaScript library for secondary processing on the frontend), you can inarchiveDetailorpageDetailtag.renderParameter.
Force rendering Markdown to HTML:
{%- archiveDetail articleContent with name="Content" render=true %} {{ articleContent|safe }}render=trueIt will force the AnQiCMS backend toContentThe Markdown content of the field is converted to HTML, regardless of whether the Markdown editor is enabled.Prevent Markdown rendering:
{%- archiveDetail articleContent with name="Content" render=false %} {{ articleContent|safe }}render=falseIt will prevent AnQiCMS backend from converting Markdown content. In this case, if you want the content to be presented as HTML, thenarticleContentThe variable itself must be pure HTML, or you use a JavaScript library to parse Markdown on the front-end.
It should be noted that, if the Markdown content includes advanced elements such as mathematical formulas or flowcharts, AnQiCMS will mark them as specific code blocks. However, their final visual presentation often still relies on the addition of extra JavaScript libraries (such as MathJax and Mermaid) to support them, as follows,help-markdown.mdThe configuration method mentioned in the document.
Advanced control and **practice
Except|safeFilter, AnQiCMS also provides{% autoescape off %}and{% autoescape on %}Tags can control the automatic escaping behavior within code blocks. If you have an entire block of content that needs to disable HTML escaping, useautoescapetag to avoid adding it after each variable.|safe:
{% autoescape off %}
<div class="some-html-block">
{{ var1 }}
{{ var2 }}
<p>{{ var3 }}</p>
</div>
{% endautoescape %}
Inside this code block,var1/var2andvar3no HTML escaping will be performed. However, be sure to use it carefully.autoescape offIt may affect the entire block, and if it contains data from untrusted sources, it may introduce security vulnerabilities.
Considerations for security:Although|safeIt brings great convenience, but please remember to use:|safe意味着您信任这些内容是安全的，不会包含恶意脚本。This is usually safe for content completely created by you or a trusted editor in the background.|safeMay pose XSS risk. In this case, you may need to consider additional security handling for user submitted content, such as usingstriptagsOr a custom HTML purification function.
Content truncation:Sometimes we may need to display a summary of rich text content rather than the entire content.Extracting directly from the HTML string may destroy the HTML structure, causing the page to display abnormally.truncatechars_htmlandtruncatewords_htmlFilters that can intelligently maintain the integrity of HTML structure while extracting HTML content, and are very suitable for generating rich text summaries.
{# 截取HTML内容到指定字符长度，并保持HTML结构 #}
<p>{{ articleContent|truncatechars_html:150|safe }}</p>
Template file encoding:Ensure that all your template files use UTF-8 encoding to avoid the issue of Chinese content displaying in garbled characters.
Summary
In AnQiCMS template, the key to correctly parse and display the HTML content in the rich text editor lies in understanding the default HTML escaping mechanism of the template engine and making good use of it.|safeThe filter explicitly declares the security of the content. For Markdown content, the system provides intelligent automatic conversion, and you can alsorenderParameters for finer control.While enjoying the flexibility of content display brought by AnQiCMS, always keep in mind the importance of content security, which is an indispensable part of building a robust website.
Common Questions (FAQ)
1. Why did the image and bold text I added in the rich text editor become plain text when displayed on the front end?<img src="...">and<strong>...</strong>Such plain text?
This is because AnQiCMS's template engine, for security reasons, defaults to escaping all output variable content. It will escape HTML tags.<and>Symbols are converted separately<and>, which causes the browser to be unable to recognize it as an HTML tag for rendering. To solve this problem, you need to add|safeFilter, such as `{{ archive.Content|