Provide general advice like using en_US_POSIX or setLocalizedDateFormatFromTemplate

As discussed on Slack, here are the suggestions / rules I always give to anyone willing to use a custom date format:

If possible it’s better to always avoid providing the dateFormat yourself, because it’s so easy to get it wrong for other locales by doing it yourself, you’re gonna run into some fallacies. A good set of rules are the following:

1. Use dateStyle and timeStyle whenever you can instead of dateFormat
2. If you need a specific format that can’t be achieved by dateStyle and timeStyle, then at least use df.setLocalizedDateFormatFromTemplate(…), or df.dateFormat = DateFormatter.dateFormat(fromTemplate:…options:…locale:…) to make sure it auto-adapts to the user’s locale; never use a direct String format as the dateFormat field to format dates for UI.
3. If you need to parse ISO Dates / “internet dates” used not for UI but for JSON or API, etc, preferably use ISO8601DateFormatter
4. In last resort, if you need to parse a date for JSON or API that doesn’t fall into ISO8601 format, but that also isn’t intended for UI and should not depend on the user’s locale/region/language because it’s a format for the API not for presenting in UI, then that’s the only case when you can use a fixed string in df.dateFormat like df.dateFormat = "yyyy-MM-dd'T'HH:mm:ssZ" BUT when you do that, then ALWAYS also set df.locale = Locale(identifier: "en_US_POSIX"). This is a special locale for your DateFormatter that guarantees that the formatting/parsing won’t depend on the phone’s locale and is designed exactly for parsing those “internet dates with fixed format”

@davedelong suggested that we post that advice on nsdateformatter.com as we think that could be very valuable to a lot of people.

The think is, I’m not sure how to do this. Do we want a new page / tab next to “Examples / Reference / About” on the website, with this as static content? Do we want something else, maybe some ⚠️ icon next to the Locale dropdown linking to said advice? I’m open to suggestions.

(Also, I just copy/pasted my Slack message verbatim here, but we might need a more appropriate wording to present that as static content on the website ofc)

[subdigital]

Yep. Feel free to ping me on Slack if you run into any issues.

On Apr 1, 2020, at 8:02 AM, Olivier Halligon [e-mail] wrote:

Sounds good. Will give it a try this evening. Since it’s just static content, it’s all just about adding code to Resources/Views/index.leaf right?

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/subdigital/nsdateformatter.com/issues/20#issuecomment-607235292, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAOOBGUK5IXBFF6J5TAR7DRKM3NBANCNFSM4LY4J5VQ.

[shawnbierman]

I think a new tab is probably the best place for it. Maybe “Guidance” ?

Best Practices?