fullcalendar/docs/events-and-sources.txt

.. _event-sources:

Event Sources
=============

The following options determine *how* events get on the calendar:

**events**: Array/String/Function
	An array of :ref:`CalEvents <CalEvent>` can be used to hardcode events into the
	calendar.
	
	Or, a URL can be provided. This URL should return JSON for an array of
	:ref:`CalEvents <CalEvent>`. GET parameters, determined by the
	``startParam`` and ``endParam`` options, will be inserted into the URL.
	These parameters indicate the UNIX timestamp of the start of the first
	visible day (inclusive) and the end of the last visible day (exclusive).
	
	Or, a function can be provided for custom fetching. The function is
	queried every time event data is needed. The function is passed a ``start``
	Date object, an ``end`` Date object, and a function to be called when
	fetching is complete. Here is the general form::
	
		events: function(start, end, callback) {
		
			// do some asynchronous ajax
			$.getJSON("/myscript",
				{
					start: start.getTime(),
					end: end.getTime()
				},
				function(result) {
				
					// format the result into an array of CalEvents
					// (not seen here)
					
					// then, pass the CalEvent array to the callback
					callback(calevents);
				
				});
		
		}

**eventSources**: Array
	Similar to the ``events`` options, except one may specify *multiple* sources.
	For example, one may specify an array of JSON URL's, an array of custom
	functions, an array of hardcoded event arrays, or any combination.

**startParam**: String, *Default*: ``'start'``
	A GET parameter of this name will be inserted into the URL when fetching
	events from a JSON script. The value of this GET parameter will be a UNIX
	timestamp denoting the start of the first visible day (inclusive).

**endParam**: String, *Default*: ``'end'``
	A GET parameter of this name will be inserted into the URL when fetching
	events from a JSON script. The value of this GET parameter will be a UNIX
	timestamp denoting the end of the last visible day (exclusive).

**cacheParam**: String, *Default*: ``'_'``
	When using a JSON url, a parameter of this name will
	automatically be inserted into the URL to prevent the browser from
	caching the response. The value will be the current millisecond time.

.. _CalEvent:

CalEvent Objects
================

A CalEvent is a data structure that frequents FullCalendar's API. It is the
standardized currency used in :ref:`event-sources`. It is also passed to various
:ref:`Triggered Actions <triggered-actions>`. Here are the properties of a
CalEvent:

**id**: Integer/String
	Uniquely identifies the given event. Instances of repeating events should
	all have the same id.

**title**: String
	The text on an event's element
	
**allDay**: Boolean (optional, defaults to ``true``)
	Determines whether the start-date and end-date's times should be ignored.
	If ``true``, times will be ignored. If ``false``, times will be considered,
	displaying them on each event (like the text '3pm').

**date**: Date
	Alias for ``start``

**start**: Date
	A javascript Date object indicating the date/time an event begins.
	
	In an :ref:`Event Source <event-sources>`, for convenience,
	one can also use a string in IETF format (ex: "Wed, 18 Oct 2009 13:00:00 EST"),
	a string in ISO8601 format (ex: "2009-11-05T13:15:30Z") or an integer
	UNIX timestamp.

**end**: Date (optional)
	A javascript Date object indicating the date/time an event ends.
	As with ``start``, IETF and ISO8601 strings can be used.
	
	**If an event is all-day...**
	
	the end date is *inclusive*. This means an event with ``start`` *Nov 10* and
	``end`` *Nov 12* will span *3 days* on the calendar.
	
	**If an event is NOT all-day...**
	
	the end date is *exclusive*. This is only a gotcha when your ``end`` has time 00:00.
	It means your event ends on midnight, and it will *not* span through the next day.

**className**: String/Array (optional)
	A CSS class (or array of classes) that will be attached to this event's
	element.
	
**editable**: Boolean (optional)
	Overrides the master ``editable`` option for this single event.

**source**: Array/String/Function (automatically populated)
	A reference to the original array, JSON URL, or function the event
	came from. Do not worry about populating this value, FullCalendar will
	do this automatically.