Marketpath CMS Calendars and their associated Calendar Entries provide a great deal of capability beyond what a standard calendar tool can offer. Each calendar entry can have unlimited custom fields defined by its template and can also have its own unique page without having to create a separate blog post or article.
The Calendar is basically the parent container for its individual calendar entries but there are a couple things to note.
A Marketpath CMS Calendar has the following default fields:
The Timezone field sets the default timezone for calendar entries. When the calendar is first created it will preselect the Site's selected timezone. You can customize this to whichever timezone is required. Keep in mind, however, that the timezone can be changed on every individual calendar entry.
All dates in Marketpath CMS are stored in Coordinated Universal Time (UTC). However, when queried and used on the Live website, all dates and times are converted to the proper timezone. Calendars and Calendar Entries will be converted to their selected timezone. As a developer this means you will not have to adjust the timezone in your liquid code or with custom Javascript.
The Calendar Entry represents an actual event in the calendar.
A Marketpath CMS Calendar Entry has the following default fields:
The Link field deserves a little attention here. Content editors may choose to create a page for a calendar entry with detailed information. But if they simply want site visitors to go to an external link for registration or some other purpose, they can provide a direct link rather than inserting a link on a page and forcing the visitor to click again to the external link.
In your template code, we recommend checking for a page and if no page, then check for a link. Render each appropriately. Example code for a calendar (the entity) and a feed of its events shows this below.
{% calendar_entries events = calendar: entity %}
{% for event in events %}
<!-- determine link url -->
{% var event_url = "#" %} <!-- default -->
{% if event.has_url %}
{% set event_url = event.full_url %}
{% elsif event.link.is_valid %}
{% set event_url = event.link.value %}
{% endif %}
<a href="{{ event_url }}">{{ event.title }}</a>
{% endfor %}
A notable challenge of calendar entries is the variety of ways the calendar entry may be defined. Any event can 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 a 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!
Please fill out the form below with your feedback or any questions you may have after working through the "Calendars" lesson.