Marketpath CMS Developer Tutorial Series

Calendars

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.

As a benefit, all of the timezones created in the CMS are consumable by the "moment timezone" javascript library, which you can use to parse and format the dates after the page is loaded.

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.

With all of the challenges related to displaying calendar entries, one successful tactic that Marketpath has used to simplify processing and displaying calendar entries has been to utilize the FullCalendar javascript library to filter and display events. It integrates smoothly with the Marketpath Live API and is capable of handling each of the pitfalls described here while still allowing the developer some control over how it is displayed. As a bonus, it even makes it easy to add feeds from multiple calendars into the same live site calendar display!

---- End of Lesson ----

Question? Correction?

Let's work together to make our documentation as helpful as possible.

What is your name? 
What is your email address? 
Feedback: