google_calendar.txt

Google Calendar
===============

FullCalendar can display events from a public [Google Calendar](http://calendar.google.com/).
Google Calendar can serve as a backend that manages and persistently stores event data
(a feature that FullCalendar currently lacks).

<div class='warning' markdown='1'>
On Nov 17th 2014, Google shut down V1 and V2 of their Calendar APIs, which FullCalendar relied upon.
Please upgrade to the latest version of FullCalendar or at least replace `gcal.js` with
**[this file](https://github.com/arshaw/fullcalendar/blob/master/dist/gcal.js)**
(will work down to FullCalendar v2.0.0).
Also, your own Google Calendar API key is now required.
</div>

Before you code...
------------------

**You must first have a Google Calendar API Key**:

1. Go to the [Google Developer Console](https://console.developers.google.com/)
   and create a new project (it might take a second).
2. Once in the project, go to **APIs & auth > APIs** on the sidebar.
3. Find "Calendar API" in the list and turn it ON.
4. On the sidebar, click **APIs & auth > Credentials**.
5. In the "Public API access" section, click "Create new Key".
6. Choose "Browser key".
7. If you know what domains will host your calendar, enter them into the box.
   Otherwise, leave it blank. You can always change it later.
8. Your new API key will appear. It might take second or two before it starts working.

**Make your Google Calendar public:**

1. In the Google Calendar interface, locate the "My calendars" area on the left.
2. Hover over the calendar you need and click the downward arrow.
3. A menu will appear. Click "Share this Calendar".
4. Check "Make this calendar public".
5. Make sure "Share only my free/busy information" is **unchecked**.
6. Click "Save".

**Obtain your Google Calendar's ID:**

1. In the Google Calendar interface, locate the "My calendars" area on the left.
2. Hover over the calendar you need and click the downward arrow.
3. A menu will appear. Click "Calendar settings".
4. In the "Calendar Address" section of the screen, you will see your Calendar ID.
   It will look something like "abcd1234@group.calendar.google.com".

Dependencies
------------

Next, you must have all the required js/css files. This includes the standard fullcalendar.js
and fullcalendar.css, **in addition to gcal.js**:

	<script type='text/javascript' src='fullcalendar/gcal.js'></script>
	
Writing the code
----------------

Now it's time to initialize your calendar in JavaScript. This is the most minimal example:

	<script type='text/javascript'>
	
	$(document).ready(function() {
		$('#calendar').fullCalendar({
			googleCalendarApiKey: '<YOUR API KEY>',
			events: {
				googleCalendarId: 'abcd1234@group.calendar.google.com'
			}
		});
	});
	
	</script>
	
If you want to specify some [Event Source] options, you can include them in the `events` object:

	<script type='text/javascript'>

	$(document).ready(function() {
		$('#calendar').fullCalendar({
			googleCalendarApiKey: '<YOUR API KEY>',
			events: {
				googleCalendarId: 'abcd1234@group.calendar.google.com',
				className: 'gcal-event' // an option!
			}
		});
	});
	
	</script>

Timezones
---------

The Google Calendar plugin respects the [timezone](timezone/timezone) parameter.
If it is `false` (the default), the timezone setting of the Google Calendar will be used,
as defined in Google's UI.
If it is specified, this will be ignored and the timezone will be forced.

Multiple Google Calendars
-------------------------

You can specify multiple Google Calendars by using the `eventSources` option:

	<script type='text/javascript'>

	$(document).ready(function() {
		$('#calendar').fullCalendar({
			googleCalendarApiKey: '<YOUR API KEY>',
			eventSources: [
				{
					googleCalendarId: 'abcd1234@group.calendar.google.com'
				},
				{
					googleCalendarId: 'efgh5678@group.calendar.google.com',
					className: 'nice-event'
				}
			]
		});
	});
	
	</script>

Advanced
--------

If you need different API keys per calendar, you can set a `googleCalendarApiKey`
option on each individual [Event Source] when written in extended form.

If you need to detect errors with the Google API, there's no way to get at this with
jQuery's AJAX error handler. You'll need to use the FullCalendar's `googleCalendarError` callback,
which is available as a normal option, or a per-[Event Source] option.


[Event Source]: event_data/Event_Source_Object