Why does AnQi CMS recommend using `stampToDate` to handle timestamps instead of using the `date` filter directly?

In the Anqi CMS template world, we often encounter situations where we need to format time data for display.Whether it is the publication time of the article, the update date of the product, or the submission time of user comments, a clear and readable date format is crucial for the website user experience.AnQi CMS is a powerful content management system developed based on the Go language, which is SEO-friendly and provides an efficient and clear strategy for handling time data.

When you browse the Anqi CMS template tag document, you will find that there are two filters (or template functions) that are related to time formatting: one is a generaldateFilter, another is designed specifically for handling timestampsstampToDateFilter. At first glance, both seem to be able to complete the task of time formatting, but why does Anqi CMS especially recommend using itstampToDateProcess timestamps instead of using them directlydateWhat about the filter? This embodies a thoughtful consideration of data types, Go language features, and the development experience

Deep understandingdateFilter: Type is the key

First, let's understanddateFilter. It is very common in many Django template engines, providing a concise way to format dates and times.In an ideal case, if you have a standard datetime object, such as the one native to Go languagetime.TimeType variable, thendateThe filter is very intuitive and convenient to use. You just need to pass the format string like this:

{{ someTimeObject|date:"2006-01-02 15:04:05" }}

However, the key issue lies in,dateThe filter has strict requirements for the input data type. As clearly stated in the AnQi CMS documentation：“Note that this value must betime.TimeType, not a timestamp, if it is a timestamp it will report an error.This sentence reveals the core limitations. Go is a statically typed language, an integer type timestamp (such as Unix timestamp, usually represented by 10-digit numbers for seconds) and atime.TimeObjects are a completely different concept in the Go type system. Passing an integer timestamp directly to the expectationtime.Timethe object'sdateFilter, it will cause a type mismatch error and eventually lead to page rendering failure.

stampToDateThe elegant solution of Anqi CMS to timestamps:

In order to solve this common problem of data type differences, Anqi CMS introducedstampToDateThis is a specialized template function. Its design goal is very clear: to safely and efficiently convert Unix timestamps (usually integer values obtained from databases) into readable date and time format.

When you usearchiveList/archiveDetail/commentListtags to retrieve document and comment data, asitem.CreatedTimeanditem.UpdatedTimeSuch fields, after being retrieved from the database, are often in the form of Unix timestamps.This is a common and efficient way to store time information in a database.In this case,stampToDatehas become **Choice:

{{ stampToDate(item.CreatedTime, "2006-01-02 15:04") }}

This function accepts two parameters: the first is a 10-digit timestamp (for example1609470335), and the second is a formatted string following the Go language standard layout. For example,"2006-01-02 15:04:05"It will format the timestamp in the form of “Year-Month-Day Hour:Minute:Second”.

Why is this distinction so important?

ThisdateandstampToDateClear distinction between and recommended for usestampToDateThe strategy, brings various benefits:

1. fits the characteristics of the data source:The Anqi CMS is designed in such a way that information such as the creation and update time of documents is often stored as Unix timestamps (integers) for efficiency in database storage and querying.stampToDateDirectly meets this data storage method, avoiding additional type conversion in the backend controller.
2. Follows the strong typing principle of the Go language: dateThe filter needs a complextime.TimeA structure, while the original timestamp is just a simpleint64type. If there is notstampToDate Developers have to perform explicit type conversions outside the template layer (such as controllers), which increases the complexity of the code.stampToDateThis conversion logic is encapsulated in the template layer, allowing frontend developers to focus more on content presentation without delving into the type details of Go language.
3. Enhance development efficiency and avoid errors:By providing a dedicated timestamp processing tool, Anqi CMS significantly reduces errors caused by mismatched time types during template development. Developers can pass timestamp data directly from the database with more confidence tostampToDateIt does not matter what type it is.
4. Clear division of responsibilities: stampToDateThe presence, making the intention of time formatting clearer. When we see it, we immediately know we are dealing with a timestamp; whereas if we usedateIt means that we are operating on a variable that has been completely converted to Gotime.TimeThis clarity helps in understanding and maintaining the code
5. Transmission of Go language formatting conventions: stampToDateContinued to use the unique time formatting method of Go language (based2006-01-02 15:04:05This reference time point), which is more natural and unified for developers familiar with the Go language.It ensures consistency in time formatting within the Anqie CMS template and the Go language ecosystem.

In summary, Anqi CMS recommends usingstampToDateThe filter is used to process timestamps, which is a practical and elegant embodiment of the Go language CMS in its design.It bridges the gap between the original timestamp stored in the database and the required format for template display with a dedicated tool, effectively optimizing the development experience and avoiding common problems that may arise from data type mismatches.

Frequently Asked Questions (FAQ)

1. Why is the time formatting string of Go language2006-01-02 15:04:05Instead of likeY-m-d H:i:sin this format?

Go language's date formatting uses a unique "reference time" mode. It does not use placeholders likeY-m-dbut instead uses a specific date and time value2006-01-02 15:04:05.999999999 -0700 MSTCome as a formatting template. You just need to selectively combine the various numbers and parts of this reference time according to the output format you want. For example, if you want to output年-月-日Then write2006-01-02If you want to output时:分Then write15:04At first glance, this method may seem unnatural, but once you get the hang of it, you'll find it very flexible and precise.

What if my timestamp is not 10 digits (second level) but 13 digits (millisecond level)?

Of Security CMSstampToDateThe filter is designed to process standard 10-digit Unix timestamps (i.e., time in seconds). If your timestamp is a 13-digit millisecond timestamp, pass it directly.stampToDateIt could lead to incorrect formatting results because it will parse it as a very large number of seconds.In this case, you need to divide it by 1000 before passing it, to convert it to a 10-digit second timestamp, or confirm whether the future version of AnQi CMS will provide a filter to support millisecond timestamps.In the current version, it is recommended to convert to a 10-digit second timestamp before use.

3. Can I convert an object to a timestamp in the template?time.TimeIn the template system of AnQi CMS, the document clearly states that

it is converting timestamps to date formats, whereasstampToDatethe date format is converted to timestamps.dateThe filter is formattingtime.TimeThe object. The document does not provide a built-in filter to converttime.TimeConvert an object back into an original Unix timestamp (integer). If there is indeed a need for this, the usual practice is to perform this conversion in the controller or backend logic, then transfer the converted