fullcalendar/docs/events-and-sources.txt

127 lines
4.6 KiB
Plaintext
Executable file

.. _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``, see :ref:`allDayDefault <allDayDefault>` option)
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.
**url**: String (optional)
A URL that will be visited when this event is clicked by the user.
By default, the new page will be opened in the current window, but one
may specify an ``eventClick`` :ref:`Triggered Action <triggered-actions>` for
more complex behavior (just remember to return ``false`` to prevent the default action).
**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.