During the development and maintenance of AnQiCMS templates, we often encounter situations where we need to confirm the content of variables.Improper use of template tags or the data structure passed from the backend may lead to abnormal display of the page.If you can see the internal structure, type, and current value of the variable at this time, it will undoubtedly greatly improve our debugging efficiency.In the AnQiCMS template system,dumpThe filter is exactly designed to solve this pain point, it acts like a periscope, helping us gain a deep understanding of the 'inner nature' of template variables.

The pain points of template debugging anddumpThe role of the filter

AnQiCMS uses a syntax similar to the 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 when 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 type of data is passed in, and what fields it contains.

dumpThe filter is designed to solve these puzzles. Its core function is to clearly output the detailed structure, type, and current 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 it easy to understand the content of variables.

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 one in a templateitemTo know the specific content of a variable, you can directly write it like this:

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

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

Practical application scenarios and output interpretation

Let's look at some specific examples to see.dumpThe filter in the actual application of AnQiCMS template debugging.

Scenario one: Check the individual item in the loop.

In the list page or data loop, we often need to traverse.archiveList/categoryListThe data collection returned by the label. If you want to view the structure of a certain loop elementitemWe 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, below each article title, you will see output similar to this (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 above output, we can clearly see that:

  • This is amodels.ArchiveThe structure of the type(&models.Archive{...})
  • It includesId(article ID),Title(Title),Link(Link),Keywords(Keywords),Description(Description),Content(Content),Logo(Cover image),Views(Views) and many other fields.
  • The name of each field (for exampleId) and its current stored value (for example1) are all displayed at a glance.
  • likeExtraFieldsEven complex fields will show their internal details.mapthe structure.

This information is very helpful for confirming whether a variable is assigned correctly, or if there is a spelling error in a field name.

Scenario two: Check the system configuration variables

When we need to get the global system settings, such as the website nameSiteNameyou can usesystemLabel. If we are not sureSiteNameHow the variables are passed, or if you want to seesystemWhat other information the label can provide,dumpFilters can also be used:

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

You might get a structure that contains 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 backend, their internal structure is often difficult to grasp.dumpThe filter can display these data objects unchanged, including nested structures, arrays, or mappings.

For example, in the document parameter tagarchiveParamsIn Chinese, we get an array containing 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 look like:

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

This tells usitemIsmodels.ArchiveExtraFieldType, there isName/Valuefields, as well as their specific values.

When should it be useddumpFilter?

  • when the content of a variable is unclear.: When you suspect a variable is null,nilor contains unexpected data.
  • when the data structure is complex.When handling nested structures such as arrays, mappings, or complex data types, it is necessary to understand their internal fields and levels.
  • Error occurred during template rendering.If 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 debuggingAfter using custom content models and fields, it is necessary to confirm whether these custom fields are passed to the template as expected.

UsedumpFilter considerations

  • Used only for debugging:dumpThe filter is a powerful debugging tool, but it should never be kept in the code of the production environment.It exposes the internal data structure and sensitive information of the website, increases security risks, and also outputs a large amount of unexpected content on the page, affecting user experience and page loading performance.
  • Remove in a timely mannerOnce debugging is complete, be sure to remove all from the template.{{ 变量名|dump }}code.
  • Combine<pre>TagAs shown in the above example, we will.dumpEnclosed in the output<pre>Tags in, can better maintain the format, improve readability.

Proficient in masteringdumpThe filter will bring great convenience to your AnQiCMS template debugging work, allowing you to build and maintain websites more efficiently.

Frequently Asked Questions (FAQ)

  1. dumpCan the filter be used in a production environment?It is not recommended to use the filter in a production environmentdumpA filter. 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.Before deploying online, be sure to remove alldumpfilter.

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

  3. How to use without destroying the page layoutdumpFilter?To avoiddumpThe content output by the filter disrupts the page layout, the simplest and most effective method is to wrap it in HTML's<pre>tags, for example<pre>{{ 变量名|dump }}</pre>.<pre>The tag preserves whitespace and line breaks in text and is usually displayed in a monospace font, which makes complex structured output easier to read. In addition, you can temporarily comment out the surrounding HTML code to retain onlydumpObserve the output.