How to correctly parse and display HTML content in the rich text editor in the AnQiCMS template?

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, and even tables, making the content bid farewell to the dull plain text.However, ensuring that these meticulously edited rich text contents are accurately displayed in the website front-end template is a key skill that every AnQiCMS user needs to master.

When we edit content through the rich text editor or Markdown editor on the AnQiCMS backend, this content will eventually be stored in the database in the form of HTML code. For example, a piece of text you input may become bold.<strong>加粗文字</strong>, the inserted image will be<img src="图片地址" alt="图片描述">.

AnQiCMS uses a template engine similar to Django, one of its design philosophies being security. To prevent security risks such as cross-site scripting attacks (XSS), the template engine, by default, will filter all data passed through{{ 变量 }}The output content is escaped as HTML. This means that if you directly output a variable containing HTML tags, for example{{ archive.Content }}, the ones you add in the editor<strong>The tag is not recognized by the browser as bold, but is displayed directly as<strong>加粗文字</strong>such plain text strings. It is obvious that this is not the effect we expect.

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 the AnQiCMS template engine that this content is safe and should not be escaped. Please output it 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 into HTML|safeThe filter can be used. Typically, the content of a rich text editor is stored in a document (archive) or a single page (page) ofContentin the field.

For example, on your article detail page (usuallyarchive/detail.htmlorarchive_detail.htmlIn the text, 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 the article'sContentfield content and assign it toarticleContentthe variable. Then,{{ articleContent|safe }}This line of code ensuresarticleContentAll HTML tags in the text, such as paragraphs<p>, image<img>, links<a>can be parsed and displayed normally by the browser, rather than as plain text output.

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 special characteristics of Markdown content

The strength of AnQiCMS lies in the fact that it also supports Markdown editors.Markdown content is different from traditional rich text HTML; it uses a concise markup syntax to write and ultimately needs to be converted to HTML to be displayed on the web.

AnQiCMS'archiveDetailandpageDetailtags are being retrievedContentWhen a field is, if the content settings of 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 forcing Markdown to HTML conversion even when the Markdown editor is not enabled, or conversely, preventing it from rendering (possibly because you want to use a JavaScript library for secondary processing), you canarchiveDetailorpageDetailthe tag withrenderParameter.

• Force rendering Markdown to HTML:

  {%- archiveDetail articleContent with name="Content" render=true %}
  {{ articleContent|safe }}
  

  render=trueWill 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 the AnQiCMS backend from converting Markdown content. In this case, if you want the content to be presented in HTML, thenarticleContentThe variable must be pure HTML, or you can use a JavaScript library to parse Markdown on the front end.

It should be noted that if Markdown content includes advanced elements such as mathematical formulas or flowcharts, AnQiCMS may mark them as specific code blocks, but their final visual presentation often still depends on the front-end to load additional JavaScript libraries (such as MathJax and Mermaid) to support, as followshelp-markdown.mdThe configuration method mentioned in the document.

Advanced control and **practice**

except|safeFilter, AnQiCMS also provides{% autoescape off %}and{% autoescape on %}The tag controls the automatic escaping behavior inside code blocks. If you need to disable HTML escaping for an entire block of content, useautoescapetag to avoid adding it after each variable|safe:

{% autoescape off %}
    <div class="some-html-block">
        {{ var1 }}
        {{ var2 }}
        <p>{{ var3 }}</p>
    </div>
{% endautoescape %}

In this code block,var1/var2andvar3HTML escaping will no longer be performed. However, please use it with caution.autoescape offIt can affect the entire block, and if it contains data from unreliable sources, it may introduce security vulnerabilities.

Consideration of security:Though|safeIt brings great convenience, but also please remember to use:|safeIt means you trust that this content is safe and does not contain malicious scripts.This is usually safe for content entirely created by you or trusted editors in the background.But if your website allows users to submit content containing HTML (such as comments or messages), and you do not want to strictly filter or review the content submitted by these users, then directly use|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 sanitization function.

Content truncation:Sometimes we may need to display an abstract of rich text content rather than the entire content.Directly truncating an HTML string may destroy the HTML structure, causing the page to display abnormally.AnQiCMS providedtruncatechars_htmlandtruncatewords_htmlFilters that can intelligently maintain the integrity of HTML structure while extracting HTML content, are very suitable for generating rich text summaries.

{# 截取HTML内容到指定字符长度，并保持HTML结构 #}
<p>{{ articleContent|truncatechars_html:150|safe }}</p>

Template file encoding:Ensure that your template files use UTF-8 encoding uniformly to avoid issues with Chinese content displaying as garbled.

Summary

In AnQiCMS template, correctly parsing and displaying HTML content in the rich text editor lies in understanding the default HTML escaping mechanism of the template engine and using it well|safeThe filter explicitly declares the security of the content. For Markdown content, the system provides intelligent automatic conversion, and you can also do it byrenderParameters 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.

Frequently Asked Questions (FAQ)

1. Why is the image and bold text I added in the rich text editor displayed as plain text on the front end?<img src="...">and<strong>...</strong>What is this plain text?

This is because the AnQiCMS template engine, for security reasons, defaults to escaping all output variable content. It will escape HTML tags.<and>Symbols are converted separately<and>This causes the browser to be unable to recognize it as an HTML tag for rendering. To solve this problem, you need to add after the variable that outputs rich text content.|safeFilter, for example `{{ archive.Content|