What are the similarities and differences between the `stampToDate` and `date` filters in handling time formatting and their applicable scenarios?

In AnQi CMS template development, we often need to display time data in a user-friendly format. The system provides two very practical tools for handling time:stampToDatefunctions anddateFilter. Although they all help us format time, there are some key similarities and differences as well as applicable scenarios. Understanding these can make our template development more efficient and accurate.

stampToDate: A master of handling timestamps

In Anqi CMS, when you retrieve content from the database (such as the publication time, update time) of articles, these time fields are usually stored in the form of Unix timestamps (a number representing the seconds or milliseconds since January 1, 1970, 00:00:00 UTC). For example, when you are usingarchiveListorarchiveDetailtags in the template,item.CreatedTimeoritem.UpdatedTimeIt returns a 10-digit integer timestamp for the field.

stampToDateThe function is specifically designed to handle such timestamps. Its usage is very intuitive, simply pass the timestamp as the first parameter, and the expected format string as the second parameter.

Usage scenario: stampToDateIt is what you process in the template.The time field directly obtained from the database.The preferred. For example, you need to display the publication date of the article:

{# 假设 item.CreatedTime 是一个10位时间戳，例如 1678886400 #}
<div>发布日期：{{stampToDate(item.CreatedTime, "2006-01-02")}}</div>
{# 显示结果可能是：发布日期：2023-03-15 #}

<div>更新时间：{{stampToDate(item.UpdatedTime, "2006年01月02日 15:04:05")}}</div>
{# 显示结果可能是：更新时间：2023年03月15日 10:30:00 #}

stampToDateThe strength lies in its direct reception of timestamps, without any preprocessing, it can be converted to any date or time format you want.

dateFilter: for Go languagetime.Time精细控制的对象

withstampToDatedifferent,dateFilter requires its input to be a native Go languagetime.Timetype object. If you try to pass a pure integer timestamp directly todateFilter, an error will occur during template parsing due to type mismatch.

Usage scenario: dateThe filter is applicable toAre you sure the variable is alreadytime.TimeTypeThis usually means that the data has already been processed and transformed into a specific format before being passed into the template in the backend Go language code.time.TimeAn object. Or, certain special system built-in variables may be provided in the form oftime.Time. In the normal template development of Anqi CMS, filters are used directly todatefilter.item.CreatedTimeSuch a database timestamp field is not common, as these fields are normally exposed to the template in the form of integer timestamps.

{# 假设 customTimeVar 是一个后端传递过来的 Go time.Time 对象 #}
<div>自定义事件：{{ customTimeVar|date:"2006/01/02 15:04" }}</div>
{# 如果 customTimeVar 是 2023年3月15日10点30分，显示结果可能是：自定义事件：2023/03/15 10:30 #}

It is worth noting that,dateThe filter has an aliastimeBoth have the same usage method and effect.

Common formatting standard: Go language time layout

whether it isstampToDateOrdateFilters that follow the Go language's time formatting rules. This rule may look particularly unusual at first glance, as it is not common.Y-m-d H:i:sInstead, it uses aspecific reference time:Mon Jan 2 15:04:05 MST 2006. You need to use the corresponding number or word from this reference time to represent the date/time part you want.

For example:

• Year:2006
• Month:01(number) orJan(abbreviation) orJanuary(full name)
• Date:02
• Hour:15(24-hour format) or03(12-hour format)
• Minute:04
• Seconds:05

This means, if you want to display "year-month-date", the format string should be"2006-01-02"; If you want to display "year/month/date time:minute", the format string is"2006/01/02 15:04".

Which filter do you want to choose?

In short:

• When you are dealing with timestamp fields directly from the database (such asitem.CreatedTime），Please usestampToDate.This is the most common and direct way to handle time in your AnQi CMS template.
• When you are sure that a variable is of Go languagetime.Timetype object, please usedatefilter.This usually happens in some advanced cases where the backend has already preprocessed the data. If you are not sure about the variable type, it is best to usestampToDatetry, to avoid unnecessary template rendering errors.

Remember this principle, and you will be more at ease in handling various time display needs in Anqi CMS.

Frequently Asked Questions (FAQ)

1. Why do I usedateFiltering processitem.CreatedTimewill it report an error?

item.CreatedTime(as well asUpdatedTimeIn an Anqi CMS template, it usually exists in the form of an integer timestamp instead of Go languagetime.Timetype object.dateThe filter strictly requires that the input must betime.TimeType. Therefore, when you pass a timestamp directly todatethe filter, an error will occur due to type mismatch. The correct approach is to usestampToDateA function that is specifically designed to handle timestamps.

2. Why does Go language use time formatting2006-01-02 15:04:05such numbers instead ofY-m-d?

This is a feature of the Go language design. It does not use symbols (such asYrepresenting the year) to define the format, but instead provides a specific reference time:Mon Jan 2 15:04:05 MST 2006. You need to mimic the style of the corresponding part of this reference time to build your format string. For example, if you want to display a four-digit year, write2006; If you want to display a two-digit month, you write01This approach may seem unique at first glance, but once familiar, you will find it very flexible and not easily confused.

3. If my timestamp is not a standard 10-digit integer (second level),stampToDateCan it be handled?

Of Security CMSstampToDateThe function is designed to handle 10-digit timestamps (second-level) as described in the documentation. If your timestamp is 13 digits (millisecond-level), you may need to process it on the backend first or perform some mathematical operations (such as dividing by 1000) to convert it to a second-level timestamp before passing it tostampToDateHowever, the best practice is to ensure that the time data is stored and passed to the template in a consistent second-level timestamp format to avoid unnecessary complexity.