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 situations where the content displayed on the page is not as expected, or it seems that a variable has not been passed correctly.At this moment, it is particularly important to be able to quickly view the actual content and data type of variables in the template.Fortunately, AnQiCMS's template engine (which adopts a syntax similar to Django) provides us with a very practical tool -dumpFilter, helping us easily reveal the mysteries of variables.

Core function:dumpThe wonder of filters

dumpThe filter acts like an X-ray machine, able to penetrate the appearance 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. Its basic syntax is: 

{{ 你的变量 | dump }}

For example, suppose 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 %}

After you refresh the page, you may see similar output 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 by the AnQiCMS bottom layer Go language, allowing you to clearly know where the object comes from.
  • {Logo:"...", Id:1, Link:"", Alt:"Hello", Description:"", Type:"default"}This lists directly.BannerItemThe names of all public fields in the structure and their current values. You can check them immediatelyLogo/Id/Link/AltWhether the values of these fields meet the expectations.

In this way, whether it is a string, number, boolean value, or more complex arrays, slices, maps (map) or structures,dumpThey can clearly show their true colors.

Advanced debugging: combined with other filters

exceptdumpCombined with other practical filters, it can further improve your debugging efficiency:

  1. stringformat:"%#v"Output in Go language source code formatIfdumpThe output may not be clear enough to you, or you may want to view the variables in a way closer to the Go language source code declaration, you can usestringformatFilter and pass in%#vParameters. It will output the variable in the Go language struct syntax, which can also help you understand the underlying representation of variables in depth.

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

  2. length: Check the length of a set or stringWhen you are dealing with lists, arrays, or strings, and you doubt whether they are empty or do not meet the expected length,lengthThe filter can be useful.

    {% 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 an element is in the set or if a string contains content.

  3. safe: Processes content containing HTML.AlthoughdumpThe filter usually outputs plain text, but when you debug variables (such as article contentitem.ContentWhen the content itself contains HTML structure, you may need to ensure that it is parsed correctly 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 to usesafeto exclude escaping issues.

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

Actual operation process and scenarios

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

  1. Determine the debugging target:Find the abnormal part displayed on the page, locate the template file involved (usually in/templatein the directory).
  2. Insertdumpcode:Insert near the 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 the page:After saving the template file, refresh the browser page. If the page does not update immediately, please try clearing the AnQiCMS backend cache.
  4. Analysis output:Check carefullydumpInformation output on the page.
    • Does the variable exist?If the variable isnilor empty,dumpIt will display an empty 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 each field's specific value for correctness.
  5. Modify and verify:Based ondumpAdjust your backend data, template tags, or variable logic based on the provided information.
  6. removedumpcode:Be sure to remove from the template after debugging is complete.dumpA filter to prevent the leakage of sensitive information or affect page performance.

dumpA filter is useful when dealing with complex data structures, such as fromarchiveListorcategoryListList items obtained from tags. You can see eachitemAll properties of the object, including its associated ID, title, link, thumbnail, etc., so as to quickly locate the problem.

Points to note

  1. Do not retain in the production environment for a long time: dumpThe filter will expose the internal data structure and content of your website, which is a great security risk. Please remove it from the template after debugging is complete.
  2. Delete after use:Suggest to delete immediately after debuggingdumpCode, develop good habits.
  3. Update the cache in time:Sometimes after modifying the template, the front-end page may not take effect immediately. Remember to go to the AnQiCMS background, use the 'Update Cache' feature to clear the system cache, and ensure