How to debug variable content and type in AnQiCMS template (using dump filter)?

When using AnQiCMS to build websites and customize templates, we often encounter such situations: the content displayed on the page is not as expected, or it seems that a certain variable is not passing correctly.It is particularly important to be able to quickly view the actual content and data type of variables in templates at such times.dumpFilters, helping us easily reveal the secrets of variables.

Core Function:dumpThe magic of filters

dumpThe filter is like an X-ray machine, able to penetrate the surface of template variables and directly print out their internal structure, data type, and current value. When you are confused about the value of a variable or whether it is the type you expect, dumpYour** helper.

UsedumpThe filter is very simple, just apply it to the variable you want to check. The basic syntax is: 

{{ 你的变量 | dump }}

For example, if you are iterating over a list of images and want to view the specific information of each image item, you can do it like this:

{% bannerList banners %}
    {% for item in banners %}
        <a href="{{item.Link}}" target="_blank">
            <img src="{{item.Logo}}" alt="{{item.Alt}}" />
            <h5>{{item.Title}}</h5>
        </a>
        {# 就在这里，我们使用dump过滤器来检查当前的item变量 #}
        <pre>{{ item | dump }}</pre>
    {% endfor %}
{% endbannerList %}

When you refresh the page, you may see an output similar to this below each image item:

&config.BannerItem{Logo:"http://127.0.0.1:8001/uploads/202309/14/eba5aa9dc4c45d18.webp", Id:1, Link:"", Alt:"Hello", Description:"", Type:"default"}

This line of output contains rich information:

  • &config.BannerItem: This indicatesitema variable is a pointer toconfig.BannerItemPointer to a structure. This is the type defined in the underlying Go language of AnQiCMS, allowing you to clearly know where this object comes from.
  • {Logo:"...", Id:1, Link:"", Alt:"Hello", Description:"", Type:"default"}This directly listsBannerItemThe names of all public fields in the structure and their current values. You can check them immediately.Logo/Id/Link/AltWhether the values of these fields meet expectations.

Through this method, whether it is a string, number, boolean value, or more complex arrays, slices, maps (map), or structs,dumpThey can all clearly show their true faces.

Advanced debugging: Combine with other filters

ExceptdumpCombined with several practical filters, it can further improve your debugging efficiency:

  1. stringformat:"%#v"Output in Go source code format.IfdumpThe output is still not clear to you, or you want to view variables in a way closer to the Go source code declaration, you can usestringformatFilter and pass%#vThe parameter will output the variable in the form of a Go language struct syntax, which can also help you deeply understand the underlying representation of the variable.

    <pre>{{ item | stringformat:"%#v" }}</pre>

  2. length: Check the length of a collection or stringWhen you are dealing with lists, arrays, or strings, and you suspect they might be empty or not of the expected length,lengthfilters can come in handy.

    {% archiveList archives with type="list" limit="10" %}
    {# 检查列表是否为空 #}
    {% if archives|length == 0 %}
        <p>没有找到任何文档。</p>
    {% else %}
        {% for item in archives %}
            {# 检查文档标题的长度 #}
            <p>文档标题：{{ item.Title }} (长度: {{ item.Title|length }})</p>
        {% endfor %}
    {% endif %}
{% endarchiveList %}

    It can help you quickly determine if there is an element in the set, or if a string contains content.

  3. safe: Handling content that includes HTML.AlthoughdumpThe filter itself usually outputs plain text, but when you are debugging variables (such as article contentitem.ContentWhen the content itself contains HTML structure, you may need to ensure that it is correctly parsed by the browser rather than displayed as plain text.safeThe filter is born for this. During debugging, if the HTML of the content variable is not rendered correctly, you can try usingsafeto exclude escaping issues.

    {# 如果archiveContent包含HTML，确保其被正确解析 #}
<div>文档内容：{{ archiveContent | safe }}</div>

Actual operation process and scenario

Generally, you would follow the following steps to usedumpPerform variable debugging:

  1. Determine the debugging target:Find the part displayed abnormally on the page, locate the template file involved (usually in)/templateDirectory under).
  2. InsertdumpCode:Insert near a variable you suspect has a problem, or inside a loop.{{ 你的变量 | dump }}. If you are in a loop, each loop item will output its information.
  3. Refresh page:After saving the template file, refresh the browser page. If the page does not update immediately, please try clearing the cache of AnQiCMS background.
  4. Analysis output:Check carefullydumpInformation displayed on the page.
    • Does the variable exist?If the variable isnilor empty,dumpit will display a null value ornil.
    • Is the type correct?For example, you expect a string, but it shows up as a number, or as a complex structure.
    • Does the value meet the expectation?Check if the specific values of each field are correct.
  5. Modify and verify:Based ondumpProvide information, adjust your backend data, template tags, or variable logic.
  6. RemovedumpCode:Ensure that you remove the template after debugging is completed.dumpFilter to prevent sensitive information leaks or impact page performance.

dumpFilter when dealing with complex data structures, such as fromarchiveListorcategoryListIt is especially useful when getting list items from tags. You can see each one.itemAll properties of the object, including its associated ID, title, link, thumbnail, etc., so you can quickly locate the problem.

Precautions

  1. Do not retain in production environment for a long time: dumpThe filter exposes the internal structure and content of your website, which is a great隐患 for website security. After debugging is completed, please be sure to remove it from the template.
  2. Use and delete: Suggest to delete immediately after debugging is completed.dumpCode, develop good habits.
  3. Update the cache in a timely manner:Sometimes after modifying the template, the front-end page may not take effect immediately. Remember to go to the AnQiCMS background, use the 'Clear Cache' feature to clear the system cache to ensure