JS library: Google Calendar as a list on your website

One of my clients asked me to display list of Google Calendar events on their website. They required a client-side solution so I was looking for a pure JavaScript way. None of ready to use scripts I have found didn't satisfy our needs so that I decided to write my own which is easy to configure. In this article you will get the script which turns your Google Calendar events into a human readable list on your website and a description of how to use it.

Get the Calendar url

There is a very easy way to get a JSON file containing your Google Calendar events by an url in following format:

https://www.googleapis.com/calendar/v3/calendars/{calendarid}/events?key={Your Public API Key}

What you need to do to be able to get the calendarid and the Public API Key and display the JSON is:

1. In the Google Developer Console enable the Calendar API and create a new the Public API Key
2. Make you calendar public and get the calendarid
3. Format the url in the url. It can look like this: https://www.googleapis.com/calendar/v3/calendars/milan.kacurak@gmail.com/events?key=AIzaSyCR3-ptjHE-_douJsn8o20oRwkxt-zHStY

Now we can access the Calendar data and it is time to display them on the website using the script.

Download on GitHub

About the script and how to use it

Script gets a public Google Calendar JSON output and transforms it into a list of events on a website. The script can display date, summary, description and location of an event. The script can work with events which last more than one day but it is not able to work with hours. The scripts sorts upcoming and past events and is able to display predefined number of them. Just look at how it could be installed and configured.

See example: http://www.kacurak.com/formatgooglecalendar/example.html

Get the script on Github: https://github.com/MilanLund/FormatGoogleCalendar, see the dist folder to locate the script

<!-- Step 1: Link required files -->
link the format-google-calendar library

<!-- Step 2: Create HTML markup -->
<ul id="events-upcoming"></ul>
<ul id="events-past"></ul>

<!-- Step 3: Call the FormatGoogleCalendar -->
formatGoogleCalendar.init({
 calendarUrl: 'https://www.googleapis.com/calendar/v3/calendars/milan.kacurak@gmail.com/events?key=AIzaSyCR3-ptjHE-_douJsn8o20oRwkxt-zHStY',
 past: false,
 upcoming: true,
 sameDayTimes: true,
 dayNames: true,
 pastTopN: -1,
 upcomingTopN: 3,
 itemsTagName: 'li',
 upcomingSelector: '#events-upcoming',
 pastSelector: '#events-past',
 recurringEvents: true, 
 upcomingHeading: '<h2>Upcoming events</h2>',
 pastHeading: '<h2>Past events</h2>'
 format: ['*date*', ': ', '*summary*', ' — ', '*description*', ' in ', '*location*'],
 timeMin: '2016-06-03T10:00:00-07:00',
 timeMax: '2020-06-03T10:00:00-07:00'
});

Options

• calendarUrl (string, url of a public Google calendar)
• past (boolean, determines if past events should be displayed)
• upcoming (boolean, determines if upcoming events should be displayed)
• pastTopN (integer, number of latest past events, -1 means display all)
• upcomingTopN (integer, number of upcoming events, -1 means display all)
• sameDayTimes (boolean, determines whether to show times for single-day events)
• dayNames (boolean, determines whether to show day names, beta feature)
• recurringEvents (boolean, determines if recurring events should be shown as multiple events)
• timeMin (timestamp, Lower bound (inclusive) for an event's end time to filter by. Optional. The default is not to filter by end time. Must be an RFC3339 timestamp with mandatory time zone offset, e.g., 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Milliseconds may be provided but will be ignored.)
• timeMax (timestamp, Upper bound (exclusive) for an event's start time to filter by. Optional. The default is not to filter by start time. Must be an RFC3339 timestamp with mandatory time zone offset, e.g., 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Milliseconds may be provided but will be ignored.)
• itemsTagName (string, tagname of each event item)
• upcomingSelector (string, selector name of a parent element of upcoming events)
• pastSelector (string, selector name of a parent element of past events)
• upcomingHeading (string, heading of upcoming events)
• pastHeading (string, heading of past events)
• format (array, describes format in which should be data displayed, it is a list of strings where wildcards are *date*, *summary*, *description*, *location*, if a string is a different value than a wildcard the string will be appended to the final output)

Notes

You can customize calendarUrl with use of various parameters which are listed in the Google Calendar API page. Following options of this library: recurringEvents, timeMin, timeMax operate directly with the Google Calendar API url parameters.