What is the core difference between the `stampToDate` and the `date` filter mentioned in `tag-filters.md`?

As an experienced website operation expert, I know that accurate display of time information is crucial for user experience and SEO optimization when managing content.In the powerful template system of AnQiCMS, we often encounter scenarios where we need to format time data for output. At this time,stampToDateanddateThese two seemingly functionally similar tools will appear in our minds.However, there is a core difference between them, understanding this difference is crucial for efficient and error-free template development.

stampToDate: The exclusive translator of timestamps

First, let's talk aboutstampToDate. In the template tag system of Anqi CMS,stampToDateIt is designed as a special label for formatting timestamps. This means that when you get one from the backend, it isUnix timestampthen,stampToDateyour preferred tool.

Many core data of Anqi CMS, such as the creation time of articles (CreatedTimeAnd update time(UpdatedTime），in databases is usually stored in the form of Unix timestamps.A Unix timestamp is typically a 10-digit or 13-digit integer representing the number of seconds or milliseconds from 00:00:00 UTC on January 1, 1970, to the current time.For this purely numeric time data,stampToDateCan translate it into various date and time formats we are accustomed to reading.

Its use is very intuitive:{{stampToDate(时间戳, "格式")}}The timestamp is that number, and the format is a reference time format string unique to the Go language, such as2006-01-02 15:04:05This format string looks a bit special, but it is a clever design used by the Go language to define various date and time output patterns.

For example, if you want to display the publication date of an article on the article detail page, and the backenditem.CreatedTimereturns a timestamp, then you would write it like this:<span>发布日期：{{stampToDate(item.CreatedTime, "2006年01月02日")}}</span>Thus,1675881600Such a timestamp would be elegantly converted into2023年02月09日.

dateFilter:time.TimeThe standard companion of an object

The opposite of itdateA filter that exists as a built-in standard filter in the AanQi CMS template engine (Pongo2, similar to the Django template engine).dateThe function of the filter is also to format time, but it has a key prerequisite: it requires that the input value must be anative to the Gotime.Timedata typeInstead of the Unix timestamp we are used to.

It's like you have a piece of paper with the number "1675881600" in your hand, anddateA filter then requires a date object that is precisely printed with “2023-02-09 00:00:00 UTC”. If you try to pass a pure Unix timestamp todateThe filter, the template engine will report an error due to type mismatch, resulting in page rendering failure.

dateThe way to use the filter is{{ value|date:"格式" }}. Here,valueMust betime.TimeAn object. For example, if your Go backend code has already converted the timestamptime.Timeto an object and passed it to the template, you can usedatea filter to format it:<span>活动开始：{{ event.StartTime|date:"2006/01/02 15:04" }}</span>

Core Difference and Practical Selection

In short,stampToDateanddateof the filterThe core difference lies in the input data types they accept.

• stampToDateSpecialized HandlingDigital Unix Timestamp.
• dateFilter Specialized Handlingnative to the Gotime.Timeobject.

In the daily template development of AnQi CMS, due to theCreatedTime/UpdatedTimefields are usually provided in the form of timestamps, thereforestampToDateThe frequency of label usage will be higher, and it will also be more in line with our direct manipulation of backend dataIt avoids additional data type conversions at the template layer, keeping the template code concise and efficient.

AnddateFilters are more suitable for the following scenarios:

1. You are processing the data directly passed from the Go backend controller, which has been formatted astime.Timethe variable of the object.
2. Your data source is not the content model built-in to Anqicms, but obtained from elsewhere, and is itselftime.Timetype of time data.

Therefore, when we think about how to format time, the first thing to clarify is what the original form of the data in your hands is. Is it an original numeric timestamp, or has it already been parsed?time.TimeObject? Being clear about this will allow you to easily choose the most suitable template tool, ensuring the accurate display of time information.

Frequently Asked Questions (FAQ)

1. Why does AnQi CMS not provide objects directly in the fields of the content model, such asCreatedTime, but instead providestime.Timetimestamps, so they cannot be used directlydatefilter?

This is mainly based on several considerations. First, Unix timestamps are more efficient and universal in database storage, facilitating cross-system and cross-language data exchange.Secondly, for front-end rendering, timestamps can be processed directly through JavaScript and other scripting languages, or likestampToDateThis provides a simple template tag for formatting. In the Go backend, convert the timestamp totime.TimeObjects are simple, but providing timestamps directly is more flexible in some scenarios, and avoids unnecessary memory overhead and type conversion.stampToDateLabels are designed to make it convenient for template developers to directly handle this common data type.

2. I can convert a timestamp into in Anqi CMS template.time.TimeType, then usedatefilter?

It is not allowed. The template engine (Pongo2) of AnQi CMS is mainly used for rendering and displaying data, not for complex programming logic or data type conversion.Convert a numeric timestamp to Go language'stime.TimeObject, this is an operation at the Go language level, which needs to be completed in the backend controller or business logic, and then the convertedtime.TimeThe object is passed to the template. If you have a timestamp directly in the template, the correct approach is to usestampToDateFormat labels.

3. If I forget the reference time format in Go language (such as2006-01-02 15:04:05Do you have an easy way to remember or refer to it?

The reference time format of Go language is indeed unique. The memory method is: "Month Day Hour Minute Second Year", namely01/02 03:04:05 2006Can be understood as "January 2, Wednesday, 3:04:05 PM, 2006".This format is actually a specific date of the birth of the Go language (at 3:04:05 PM on January 2, 2006), using these numbers to represent the corresponding date and time components.If you really can't remember, you can always refer to the development document of Anqi CMS, or search for "Go time format" in the Go language community, and you can find a detailed comparison table soon.In practical development, it is a good habit to keep a memo of commonly used formats.