UPDATE: These changes were implemented in Drafts v35. Details on date formatting in the User Guide.
Drafts has always supported formatted dates using strftime format strings when outputting in templates, etc. More background in the templates article.
The uses the strftime function built-in to Apple’s platforms, and it’s great, but has some downside in terms of localization and lack of flexibility.
I’m working on extended Drafts template engine to also support the use of Apple’s DateFormatter class, which is more powerful and has better support for generating date strings in a localizable fashion. DateFormatter has a different syntax for templates (which you can learn and play with at the excelling NSDateFormatter website).
I’m going to do this, while remaining backward-compatible, but adding support for some markup in date format strings. Currently, the mark up is planned as described below. This is an RFC - this does not yet work. It will be rolled out in Drafts v35 soon. I’m interested in comments on this markup - if it makes sense, if you see any conflicts/issues.
Proposed Syntax:
Date tags will continue to work with the basic format: [[tagName|formatString]]. Any existing tags will continue to assume the formatString value is a strftime format string. For example:
[[date|%Y-%m-%d]]→ 2022-12-02
Two special characters will be introduced to make the formatString as a DateFormatter template, rather than a strftime format string. These will be ~ and =. If the formatString starts with one of those character, it will be stripped off and the remainder of the format string will be routed through DateFormatter. As such:
~: Treat format string as a list of elements to include, and letDateFormatterfigure out the best way to layout that date based on the current locale. For example, passing~MMMdyyyyas the format string says “I want a date string with a short month, date, and four digit year”. In US English, that would come out like “Jan 2, 2000”. In UK English, “2 Jan 2000”, in Italian “2 gen 2020”. Any additional spacing/punctuation would be ignored.=: Treat format as an explicit template, inserting localized element values. This is more like the strftime model, where you can include your own preferred spacing and punctuation, and just the localized date component values are inserted. For example,=MMM d, h:mm awould output “Jan 2, 10:20 AM” (in US English locale).
When using DateFormatter format strings (any starting with ~ or =), several special values are recognized for standard, common formats as well, these are:
=shortDate=shortDateTime=longDate=longDateTime=iso8601
These map to the standard formats defined by Apple’s DateFormatter class for date and time styles, or allow easy output of industry standard ISO 8601 format date strings.
Localization
Because DateFormatter is better integrated into the OS, it will output based on the current locale selected on the device, so allows more transportable output in actions. But the format strings will also allow override to a specific locale, if desired. This will be handled by looking for parenthesized markup of a specific locale string for DateFormatter format strings. So to force a date to output in a specific locale, use the syntax ~(locale)formatString. For example ~(it_IT)MMMdyyyy or ~(us_GB)MMMdyyyy. When evaluated, the ~(..) will be stripped and the remaining format string evaluated in the specified locale, regardless of the current locale on the device.
Compatibility
This should largely be free of issues rolling out in and update. The only exception would be in any one has existing date template tags with strftime format strings starting in either ~ or = in their action templates, but that seem that would be exceedingly rare.