In the template development of Anqi CMS, we often need to display time data in a user-friendly format. The system provides two very practical tools to handle time:stampToDatefunctions anddateFilter.Although they can all help us format time, there are some key differences and application scenarios among them. Understanding these can make our template development more efficient and accurate.

stampToDateEnglish time stamp handler

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

stampToDateFunctions are designed to handle such timestamps.The way it is used is very intuitive, simply pass the timestamp as the first parameter and the format string you expect as the second parameter.

Use cases: stampToDateIs what you process in the templateThe time field directly obtained from the databaseThe default. 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 of it 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.TimeThe fine control of the object

WithstampToDatedifferent,dateThe filter requires its input to be a native Go language typetime.TimeIf you try to pass a pure integer timestamp directly todateFilter, an error will occur due to type mismatch during template parsing.

Use cases: dateFilter is applicable toAre you sure the variable has already beentime.TimeTypeThis usually means that the data has been processed and converted into a specific format by the backend Go language code before being passed into the template.time.TimeObject. Alternatively, some special system built-in variables may be provided directly in the form oftime.Time. In the normal template development of Anqi CMS, the filter is used directlydatefilter.item.CreatedTimeSuch a database timestamp field is not common, as these fields are exposed to the template in the form of integer timestamps by default.

{# 假设 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 and effect.

Common formatting standard: Time layout in Go language.

WhetherstampToDateOrdateFilter, they all follow the time formatting rules of the Go language. This rule may look special at first glance, it is not the commonY-m-d H:i:s, but uses aspecific reference time:Mon Jan 2 15:04:05 MST 2006. You need to use the corresponding number or text 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]
  • Minutes:04
  • Seconds:05

This means, if you want to display “year-month-day”, the format string should be"2006-01-02"；If you want to display “year/month/day Time:Minute”, the format string is"2006/01/02 15:04".

Which filter do you want to choose?

In short:

  • When dealing with timestamp fields directly obtained from a database (such as)item.CreatedTime), Please usestampToDate.This is the most common and direct way to handle time in the AnQi CMS template.
  • When you are sure that a variable is of type object in Go languagetime.Timeplease 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 use it first.stampToDateTry it to avoid unnecessary template rendering errors.

Remember this principle, and you will be able to handle various time display needs more freely in the Anqi CMS.

Common Questions (FAQ)

1. Why do I only show a few tags instead of all the tags I expected after using the tag?dateFilter processingitem.CreatedTimeWill it report an error?

item.CreatedTime(andUpdatedTimeEnglish in security CMS templates usually exist in the form of integer timestamps, not Go languagetime.Timetype objects.dateThe filter strictly requires that the input must betime.TimeType. Therefore, when you pass a timestamp directly todatethe filter, it will report an error due to type mismatch. The correct way is to usestampToDateFunction, it is designed to handle timestamps.

Why does Go language use time formatting?2006-01-02 15:04:05such numbers, instead ofY-m-d?

This is a feature of Go language design. It does not use symbols (such asYrepresenting the year) to define the format, but provides a specific reference time:Mon Jan 2 15:04:05 MST 2006。You need to construct your format string by imitating the style of the corresponding part in this reference time. For example, if you want to display a four-digit year, write2006；if you want to display a two-digit month, write01This way, although it may seem unique at first contact, once you get familiar with it, you will find that it is very flexible and not easily confused.

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

Anqi CMS'sstampToDateThe function is designed to handle 10-digit timestamps (second-level). If your timestamp is 13 digits (millisecond-level), you may need to process it on the backend first, or convert it to a second-level timestamp by performing some mathematical operations (such as dividing by 1000) in the template, and then pass it tostampToDate. However, 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.