During the development and maintenance of AnQiCMS templates, we often encounter situations where we need to confirm the content of variables.The template tag is used incorrectly, or the data structure passed by the backend does not meet the expected requirements, which may cause the page to display abnormally.At this moment, if we could directly see the internal structure, type, and current value of the variable, it would undoubtedly greatly enhance our debugging efficiency.dumpThe filter is exactly designed to solve this pain point, it acts like a透视镜透视镜, helping us to deeply understand the 'inner essence' of template variables.

The pain points of template debugging anddumpThe role of the filter

AnQiCMS uses a syntax similar to Django template engine, which is a concise and efficient template language that allows us to quickly build pages.However, when the page displays incorrectly, or certain data does not appear as expected, traditional debugging methods are often not intuitive.We may need to guess whether the variable name is spelled correctly, or what the type of the data passed in is, and what fields it includes.

dumpThe filter is designed to solve these confusions.Its core function is to clearly output the detailed structure, type, and current stored value of any variable to the page.This includes the names of the underlying data structures, field names, and their corresponding values in the Go language, making the content of variables clear at a glance.

How to usedumpFilter?

UsedumpThe filter is very simple and intuitive. You just need to attach it to the variable you want to check, just like using other filters. Its basic syntax format is: 

{{ 变量名|dump }}

For example, suppose you have aitemvariable in the template and want to know its specific content, you can write it directly like this:

<pre>{{ item|dump }}</pre>

We usually place it in<pre>Labels within the output will retain the original format, which is more convenient for reading, especially when the variable content is a complex structure.

Actual application scenarios and output interpretation

Let's look at several specific examples to seedumpThe actual application of the filter in AnQiCMS template debugging.

Scenario one: Check the individual data item in the loop.

In the list page or data loop, we often need to traverse.archiveList/categoryListThis label returns a set of data. If you want to view the complete structure of the loop, you can do this:itemThe complete structure, we can do this:

{% archiveList archives with type="list" limit="10" %}
    {% for item in archives %}
        <p>文章标题: {{ item.Title }}</p>
        <pre>{{ item|dump }}</pre> {# 在这里使用 dump 过滤器 #}
    {% endfor %}
{% endarchiveList %}

When you refresh the page, you will see output similar to this below each article title (this is just an example, the actual output will be longer and more detailed):

&models.Archive{Id:1, CreatedTime:1678886400, UpdatedTime:1678886400, DeletedTime:0, SiteId:1, ModuleId:1, CategoryId:5, UserId:1, ParentId:0, Title:"AnQiCMS模板调试：如何显示变量的详细结构", Link:"/article/anqicms-template-debug.html", SeoTitle:"", Keywords:"AnQiCMS,模板调试", Description:"本文将详细介绍AnQiCMS模板调试时，如何利用dump过滤器显示变量的详细结构、类型和值...", Content:"...", Logo:"https://en.anqicms.com/uploads/images/thumbnail.webp", Thumb:"https://en.anqicms.com/uploads/images/thumbnail-thumb.webp", Images:[]string{}, Flag:"c", OriginUrl:"", CanonicalUrl:"", CustomUrl:"", ReadLevel:0, Price:0.00, Stock:0, Views:1234, CommentCount:10, Likes:50, Dislikes:2, Sort:0, Status:1, CombineIds:nil, ExtraFields:map[string]interface {}{"author":"张三"}}

From the output above, we can clearly see:

  • This is amodels.Archivea structure of type&models.Archive{...}).
  • it includesId(Article ID),Title(Title),Link(Link),Keywords(Keywords)、Description(description),Content(Content) ofLogo(cover image),Views(views) and many other fields.
  • Each field's name (such asId) and its current stored value (such as1) are all displayed clearly.
  • likeExtraFieldsComplex fields like these will also show their internalmapstructure.

This information is very helpful for confirming whether a variable is assigned correctly, or whether a field name is spelled incorrectly.

Scenario two: Check system configuration variables.

When we need to get the global system settings, such as the website nameSiteName,"systemthe tag. If we are not sureSiteNamehow variables are passed, or want to seesystemwhat other information the tag can provide,dumpFilters can also be used for this:

<pre>{{ system|dump }}</pre>

You may get a structure containing all system configurations, allowing you to discover and use more useful fields.

Scenario three: Debugging custom parameters or complex objects

For custom fields or complex data objects passed from the background, their internal structure is often difficult to grasp.dumpThe filter can display these data objects exactly as they are, including nested structures such as structs, arrays, or mappings.

For example, in the document parameter tagsarchiveParamsEnglish, we get an array that contains custom fields. To understand eachitemyou can use it like thisdump:

{% archiveParams params %}
    {% for item in params %}
        <p>参数名称：{{item.Name}}</p>
        <pre>{{ item|dump }}</pre>
    {% endfor %}
{% endarchiveParams %}

The output may be similar to:

&models.ArchiveExtraField{Name:"作者", Value:"张三", FieldName:"author", Type:"text", Required:false, Content:""}

This tells usitemYesmodels.ArchiveExtraFieldtype, hasName/Valueand other fields, as well as their specific values.

When should it be useddumpFilter?

  • When the variable content is unclear: When you suspect a variable is nullnilor contains unexpected data.
  • When the data structure is complex：When processing nested structures such as structs, arrays, or mappings, it is necessary to understand their internal fields and levels.
  • When template rendering failsIf the page rendering fails, it is suspected that the variable access path is incorrect or the data type does not match.dumpIt can help you quickly locate the problem.
  • Custom field debuggingIn using a custom content model and fields, it is necessary to confirm whether these custom fields are passed to the template as expected.

UsedumpConsiderations for filters

  • Used only for debugging:dumpThe filter is a powerful debugging tool, but it should never be kept in the code of a production environment.It would expose the internal data structure and sensitive information of the website, increase security risks, and also output a large amount of unexpected content on the page, affecting user experience and page loading performance.
  • Remove in a timely manner：Once debugging is complete, be sure to remove all from the template{{ 变量名|dump }}code.
  • Combine<pre>tags：As shown in the above example, thedumpoutput should be enclosed in<pre>tags to better maintain its format and readability

skilled indumpFilter, it will bring great convenience to your AnQiCMS template debugging work, allowing you to build and maintain your website more efficiently.

Common Questions and Answers (FAQ)

  1. dumpCan the filter be used in a production environment?It is not recommended to use in a production environmentdumpFilter.It will directly output the detailed internal structure and value of the variable, which may contain sensitive information (such as database fields, system paths, etc.), posing a threat to the security of the website.At the same time, the output of a large amount of debugging information will also affect the page loading speed and user experience.dumpFilter.

  2. dumpCan the filter display detailed information of all types of variables?Yes,dumpThe filter is implemented based on the underlying data reflection mechanism of Go language, it can display the detailed structure, type, and current value of almost all types in Go language, including basic data types (strings, numbers, boolean values), arrays, slices (slice), maps, structs, and their combinations.

  3. How to use without destroying the page layoutdumpFilter?To avoiddumpThe simplest and most effective method to prevent the content output of the filter from disturbing the page layout is to wrap it in HTML's<pre>Tags within, for example<pre>{{ 变量名|dump }}</pre>.<pre>Labels preserve whitespace and newline characters in text and are typically displayed in a monospaced font, which makes complex structured output easier to read. Additionally, when debugging, you can also temporarily comment out the surrounding HTML code, leaving onlydumpOutput to observe.