During the development of AnQi CMS templates, we often need to view the content contained in variables, especially when variables may carry HTML structures. How to quickly and accurately view the original HTML content instead of the parsed or escaped results by the browser is the key to efficient debugging.The AnQi CMS adopts a template engine syntax similar to Django, providing several powerful tools to help us solve this problem.

Understanding the need for debugging: Why do we need to view the original HTML?

Using directly in the template{{ 变量名 }}When outputting variables, for security reasons, the Anqi CMS template engine defaults to escaping HTML tags. This means that if you expect to see<p>这是一个段落</p>Such an HTML structure, when actually output to the page, may become&lt;p&gt;这是一个段落&lt;/p&gt;.Although this default behavior can effectively prevent XSS (cross-site scripting attack) and other security issues, it can hinder us from directly viewing the real HTML code contained in variables when debugging templates or handling rich text content.

To address this pain point, we can cleverly use the filters provided by the template engine to 'bypass' the default escaping, or even more thoroughly inspect the internal structure of the variables.

Method one: usesafeThe filter directly displays HTML content

When you are sure that the variable contains valid, safe HTML content, and you want it to be parsed and rendered normally by the browser instead of being escaped into entity characters, safeThe filter is your first choice.

The function is to explicitly tell the template engine: \

How to use:

Just add to the variable|safeIt can be. For example, if your article detailarchivehas an objectContentThe field stores the HTML content generated by the rich text editor. If you want to see the rendered effect of these HTML on the page directly, or want to confirm the HTML structure by viewing the page source code, you can use it like this:

<div>
    {# 默认情况下，Content中的HTML可能会被转义 #}
    <p>默认输出（可能已转义）：</p>
    {{ archive.Content }}

    {# 使用 safe 过滤器后，Content中的HTML将直接输出，并被浏览器解析 #}
    <p>使用 |safe 后的输出：</p>
    {{ archive.Content | safe }}
</div>

After you add this code to the template and refresh the page, you can clearly see by using the browser's "View Page Source" or "Inspect Element" feature.{{ archive.Content | safe }}The original HTML structure at the location, not the escaped text. This is very helpful for checking if rich text content is generated as expected in HTML, or for troubleshooting style issues.

Method two: usedumpFilter to view the original structure and value of variables

Sometimes, we not only want to know if there is HTML in the variable, but also want to understand the type of the variable, its complete original string form (including the escaped parts), and even its internal data structure. At this time,dumpThe filter comes into play.dumpThe filter will print the detailed structure, type, and original value of the variable, especially useful for complex variables (such as objects, arrays).

How to use:

Similarly, add after the variable|dump. For example:

<pre>
    {# 查看整个 archive 对象的详细信息 #}
    <p>archive 对象原始结构：</p>
    {{ archive | dump }}

    {# 单独查看 Content 字段的原始字符串表示，包括其内部类型和转义情况 #}
    <p>archive.Content 字段原始结构：</p>
    {{ archive.Content | dump }}
</pre>

UsedumpAfter the filter, you will see text on the page similar to the output of Go language struct, for example&models.Archive{Id:1, Title:"文章标题", Content:"&lt;p&gt;原始HTML内容&lt;/p&gt;" ...}In this way, you can clearly seeContentwhether the field really contains&lt;p&gt;Such escape characters, not the result rendered by the browser.This is extremely effective for understanding the actual storage method of variables, troubleshooting data source issues, or dealing with unexpected escape problems.|dumpEnclosed in the output<pre>Tag inside.

Method three (advanced): combinestringformatFilter to get pure string representation

In some specific scenarios, you might thinkdumpThe filter outputs too much information, or you just want to get a pure string form of a variable, even including its string quotes. At this point,stringformatThe filter combined with specific formatting parameters can provide assistance.

For example,stringformat:"%q"The variable content will be output as a string with double quotes in Go language, which can clearly show the boundaries and all characters inside the string, including those special characters that are not visible in daily life.

How to use:

<pre>
    {# 使用 %q 格式化，以带引号的字符串形式查看 Content 的原始内容 #}
    <p>archive.Content (纯字符串带引号)：</p>
    {{ archive.Content | stringformat:"%q" }}

    {# 或者使用 %#v 格式，获取更像Go语言代码片段的表示 #}
    <p>archive.Content (Go风格代码片段)：</p>
    {{ archive.Content | stringformat:"%#v" }}
</pre>

This method is a very useful supplement when it is necessary to accurately view whether a string contains invisible characters such as spaces, newlines, or to confirm that the string has been correctly parsed.

Summary and debugging tips

When debugging the AnQiCMS template, you can choose the appropriate filter according to your specific needs:

  • |safeWhen you need to directly render HTML from a variable on the page and want to check the HTML structure by viewing the page source code.
  • |dumpWhen you need to view the complete internal structure, type, and the original (possibly escaped) representation of a variable.
  • |stringformat:"%q"or|stringformat:"%#v": When you need to view the variable content in a concise pure string format (with or without quotes), especially when checking for special characters.

Debugging Tips:

  1. Temporary Operations:These debugging codes are usually temporarily added to template files. Once the problem is resolved, please be sure to delete them to avoid unnecessary code exposure or affecting page performance.
  2. Isolated variable:If you are debugging variables in complex loops or conditional judgments, you can first use{% set my_temp_var = item.some_field %}Assign the target variable to a temporary variable, then use a filter to debug the temporary variable, which can help to locate the problem more clearly.
  3. Browser Developer Tools: Combine the browser's developer tools (F12) to observe in the 'Elements' panel|safeThe rendered effect, by viewing the original HTML response loaded in the "Source Code" or "Network" panel, can help you fully understand the variable content at different stages.

Mastering these debugging techniques will greatly enhance your efficiency in developing Anqi CMS templates and content operations.

Frequently Asked Questions (FAQ)

1. Why do I output directly in the template?{{ archive.Content }}The result is not a beautiful HTML layout, but a heap of text with&lt;and&gt;?

This is the default behavior of the AnQi CMS template engine for security considerations. To prevent malicious script injection (XSS attacks), the template engine automatically escapes HTML special characters in variables and converts them to HTML entities (for example<becomes&lt;）。If you are sure that the content is safe HTML and you want the browser to parse and display it correctly, you need to use|safea filter such as{{ archive.Content | safe }}.

2. I wasarchive.Contentusing on|safeFilter, but the page still looks problematic, and some images cannot be loaded, what's going on?

|safeThe filter only prevents the template engine from escaping HTML, it cannot correct the errors in the HTML content itself. If yourarchive.ContentIt contains irregular, incomplete HTML tags, or there are problems with image paths and JS script link, the browser will still fail to parse. In this case, it is recommended that you first use{{ archive.Content | dump }}or{{ archive.Content | stringformat:"%q" }}CheckContentThe original HTML code, carefully check its structure and path to find the specific problem.

3. Use|dumpThe filter prints too much and too complex information, is there a way to only view the original value of a custom field I care about?

Of course. If you only want to viewarchiveThe value of a custom field (for examplecustom_fieldcan be used directly on this field|dumpFilter, for example{{ archive.custom_field | dump }}If this custom field is a complex structure and you only need a sub-attribute, you can specify it further, such as{{ archive.custom_field.sub_property | dump }}This can help you focus on debugging specific data, avoiding interference from irrelevant information.