Last Updated 3/6/2018
Calendars may seem simple, but can actually be very tricky to implement well. Watch out for these pitfalls and become a super-scheduler!
The first notable pitfall of calendars and calendar entries is timezones. The calendar may be defined with one timezone, and each calendar entry may be created in a different timezone, so what should you do?
We take some of the pressure off of timezones by storing all dates in the CMS in UTC. While this makes it simple to convert between timezones, it does have a couple drawbacks:
- You have to explicitly convert dates from UTC in order to display them in your target timezone
- It makes it much more complicated if you want to display dates in the timezone they were created with since you may be converting between multiple timezones on a single page where the timezone could be one of a large number of string values. Eg: "America/Indiana/Indianapolis", "EST5EDT", or "Etc/GMT+5" to name a few.
The second notable pitfall of calendar entries is the variety of ways that the calendar entry may be defined. Any event could be an all-day event or a partial-day event. In either case, the start date and end date do not have to be on the same day, which means that you could have an single-day all-day event, a multi-day all-day event, a single-day timed event, or a multi-day timed event. This gets challenging to display, and is equally challenging to query.
If you search for events after January 12, should the search include an event that starts on January 1 and ends on January 14? Tough question - some people will answer "yes" and some people will answer "no". Currently, the CMS will include results that either start OR end after the specified collection start date.
On the related search - events before January 12, Marketpath answers the same way. Calendar entries are included in the results that either start OR end before the specified collection end date. When performing these queries, remember that all dates are stored (and therefore filtered) in UTC.
Let's work together to make our documentation as helpful as possible.