mirror of
https://github.com/wassname/fullcalendar.git
synced 2026-09-12 12:21:04 +08:00
initially commit for new docs branch
This commit is contained in:
Adam Shaw
@@ -0,0 +1,76 @@
|
||||
|
||||
Event Object
|
||||
============
|
||||
|
||||
A standard object that FullCalendar uses to store information about an event.
|
||||
|
||||
An Event Object has a number of properties, although only two of them are required
|
||||
for `events`/`eventSources` (the `title` and `start` properties). Here they are:
|
||||
|
||||
**id**: String/Integer (optional)
|
||||
: Uniquely identifies the given event. Different instances of repeating events should all have the same `id`.
|
||||
|
||||
**title**: String
|
||||
: The text on an event's element
|
||||
|
||||
**allDay**: `true` or `false` (optional)
|
||||
: Whether an event occurs at a specific time-of-day. This property affects whether an event's time is shown.
|
||||
Also, in the agenda views, determines if it is displayed in the "all-day" section.
|
||||
|
||||
**Don't include quotes** around your `true`/`false`. This value is not a string!
|
||||
|
||||
When specifying Event Objects for `events` or `eventSources`,
|
||||
omitting this property will make it inherit from
|
||||
[allDayDefault](), which is normally `false`.
|
||||
|
||||
**start**: Date
|
||||
: A JavaScript Date object indicating the date/time an event begins.
|
||||
|
||||
When specifying Event Objects for `events` or `eventSources`,
|
||||
you may specify 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 a UNIX timestamp.
|
||||
|
||||
**end**: Date (optional)
|
||||
: A Javascript Date object indicating the date/time an event ends.
|
||||
As with `start`, you may specify it in IETF, ISO8601, or UNIX timestamp format.
|
||||
|
||||
**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.
|
||||
For more information on controlling this behavior, see the [eventClick](../clicking_hovering/eventClick) callback.
|
||||
|
||||
**className**: String/Array (optional)
|
||||
: A CSS class (or array of classes) that will be attached to this event's element.
|
||||
|
||||
**editable**: `true` or `false` (optional)
|
||||
: Overrides the master [editable]() option for this single event.
|
||||
|
||||
**source**: Array/String/Function (automatically populated)
|
||||
: A reference to the event source (as specified in `events` or `eventSources`)
|
||||
that this event came from.
|
||||
|
||||
Do not worry about populating this value, FullCalendar will do this automatically.
|
||||
|
||||
|
||||
In addition to the fields above, you may also include your own non-standard fields
|
||||
in each Event Object. FullCalendar will not modify or delete these fields.
|
||||
For example, developers often include a `description` field for use in callbacks such
|
||||
as [eventRender](../event_rendering/eventRender).
|
||||
|
||||
<div class='version-info' markdown='1'>
|
||||
Prior to version 1.3, the *allDay* property did not exist. *showTime* was used instead,
|
||||
and was set to *true* to guarantee that an event's time was shown.
|
||||
|
||||
The *className* and *source* properties did not exist prior to version 1.2.
|
||||
</div>
|
||||
|
||||
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
addEventSource *1.2*
|
||||
====================
|
||||
|
||||
Dynamically adds an event source.
|
||||
|
||||
<div class='spec' markdown='1'>
|
||||
.fullCalendar( 'addEventSource', *source* )
|
||||
</div>
|
||||
|
||||
Source may be an Array/URL/Function just as in the `events` option.
|
||||
Events will be immediately fetched from this source and placed on the calendar.
|
||||
@@ -0,0 +1,9 @@
|
||||
|
||||
allDayDefault *1.3.1*
|
||||
=====================
|
||||
|
||||
Determines the default value for each [Event Object]()'s `allDay` property, when it is unspecified.
|
||||
|
||||
<div class='spec' markdown='1'>
|
||||
Boolean, *default*: `true`
|
||||
</div>
|
||||
@@ -0,0 +1,11 @@
|
||||
|
||||
cacheParam *1.1*
|
||||
================
|
||||
|
||||
A GET parameter of this name will be inserted into each JSON feed's URL to prevent caching.
|
||||
|
||||
<div class='spec' markdown='1'>
|
||||
String, *default*: `'_'`
|
||||
</div>
|
||||
|
||||
The value will be the current millisecond time.
|
||||
@@ -0,0 +1,23 @@
|
||||
|
||||
clientEvents *1.3*
|
||||
==================
|
||||
|
||||
Retrieves events that FullCalendar has in memory.
|
||||
|
||||
<div class='spec' markdown='1'>
|
||||
.fullCalendar( 'clientEvents' [, *idOrFilter* ] )
|
||||
</div>
|
||||
|
||||
This method will return an array of [Event Objects](Event_Object) that FullCalendar has stored
|
||||
in client-side memory.
|
||||
|
||||
If `idOrFilter` is omitted, *all* events will be returned.
|
||||
|
||||
If `idOrFilter` is an ID, all events with the same ID will be returned.
|
||||
|
||||
`idOrFilter` may also be a filter function that accepts one [Event Object]()
|
||||
argument and returns `true` if it should be included in the result set.
|
||||
|
||||
<div class='version-info' markdown='1'>
|
||||
In versions 1.2 and 1.2.1, this option was known as *getEventsByID*
|
||||
</div>
|
||||
@@ -0,0 +1,11 @@
|
||||
|
||||
endParam
|
||||
========
|
||||
|
||||
A GET parameter of this name will be inserted into each JSON feed's URL.
|
||||
|
||||
<div class='spec' markdown='1'>
|
||||
String, *default*: `'end'`
|
||||
</div>
|
||||
|
||||
The value of this GET parameter will be a UNIX timestamp denoting the end of the last visible day (exclusive).
|
||||
@@ -0,0 +1,21 @@
|
||||
|
||||
eventSources *1.2*
|
||||
==================
|
||||
|
||||
A way to specify multiple event sources.
|
||||
|
||||
<div class='spec' markdown='1'>
|
||||
Array
|
||||
</div>
|
||||
|
||||
This option is used instead of the `events` option.
|
||||
It can take an Array of Arrays/Functions/URLs (anything that the `events` option would take).
|
||||
|
||||
Here is an example calendar that displays two [JSON feeds](events_json_feed):
|
||||
|
||||
$('#calendar').fullCalendar({
|
||||
eventSources: [
|
||||
'/feed1.php',
|
||||
'/feed2.php'
|
||||
]
|
||||
});
|
||||
@@ -0,0 +1,26 @@
|
||||
|
||||
events (as an array)
|
||||
====================
|
||||
|
||||
An array of [Event Objects](Event_Object) that will be displayed on the calendar.
|
||||
|
||||
Here is an example of how to specify an array of events:
|
||||
|
||||
$('#calendar').fullCalendar({
|
||||
events: [
|
||||
{
|
||||
title : 'event1',
|
||||
start : '2010-01-01'
|
||||
},
|
||||
{
|
||||
title : 'event2',
|
||||
start : '2010-01-05',
|
||||
end : '2010-01-07'
|
||||
},
|
||||
{
|
||||
title : 'event3',
|
||||
start : '2010-01-09 12:30:00',
|
||||
allDay : false // will make the time show
|
||||
}
|
||||
]
|
||||
});
|
||||
@@ -0,0 +1,54 @@
|
||||
|
||||
events (as a function)
|
||||
======================
|
||||
|
||||
A custom function for programmatically generating [Event Objects](Event_Object).
|
||||
|
||||
<div class='spec' markdown='1'>
|
||||
function( *start*, *end*, *callback* ) { }
|
||||
</div>
|
||||
|
||||
FullCalendar will call this function whenever it needs new event data.
|
||||
This is triggered when the user clicks prev/next or switches views.
|
||||
|
||||
This function will be given `start` and `end` parameters, which are
|
||||
Date objects denoting the range the calendar needs events for.
|
||||
|
||||
It will also be given `callback`, a function that must be called when
|
||||
the custom event function has generated its events. It is the event function's
|
||||
responsibility to make sure `callback` is being called with an array of
|
||||
[Event Objects](Event_Object).
|
||||
|
||||
Here is an example showing how to use an event function to fetch events from
|
||||
an XML feed:
|
||||
|
||||
$('#calendar').fullCalendar({
|
||||
events: function(start, end, callback) {
|
||||
$.ajax({
|
||||
url: 'myxmlfeed.php',
|
||||
dataType: 'xml',
|
||||
data: {
|
||||
// our hypothetical feed requires UNIX timestamps
|
||||
start: Math.round(start.getTime() / 1000),
|
||||
end: Math.round(end.getTime() / 1000)
|
||||
},
|
||||
success: function(doc) {
|
||||
|
||||
var events = [];
|
||||
|
||||
$(doc).find('event').each(function() {
|
||||
event.push({
|
||||
title: $(this).attr('title'),
|
||||
start: $(this).attr('start') // will be parsed
|
||||
});
|
||||
});
|
||||
|
||||
callback(events);
|
||||
|
||||
}
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
However, if you have the choice, JSON is a better idea because you can just specify a
|
||||
[feed URL](events_json_feed).
|
||||
@@ -0,0 +1,31 @@
|
||||
|
||||
events (as a json feed)
|
||||
=======================
|
||||
|
||||
A URL of a JSON feed that the calendar will fetch [Event Objects](Event_Object) from.
|
||||
|
||||
FullCalendar will visit the URL whenever it needs new event data.
|
||||
This happens when the user clicks prev/next or changes views.
|
||||
FullCalendar will determine the date-range it needs events for and will
|
||||
pass that information along in GET parameters.
|
||||
|
||||
The GET parameter names will be determined by the [startParam]() and [endParam]() options.
|
||||
(`"start"` and `"end"` by default).
|
||||
|
||||
The value of the parameters will always be UNIX timestamps (seconds since 1970).
|
||||
|
||||
Consider the following script:
|
||||
|
||||
$('#calendar').fullCalendar({
|
||||
events: "/myfeed.php"
|
||||
});
|
||||
|
||||
Here is a URL that might be visited:
|
||||
|
||||
`/myfeed.php?start=1262332800&end=1265011200&_=1263178646`
|
||||
|
||||
The `_` parameter is automatically inserted to prevent the browser from
|
||||
caching the result (see [cacheParam]()).
|
||||
|
||||
If you need to access a feed that is in a different domain, you can use JSONP
|
||||
with a `?` in your URL (see the JSONP discussion in [$.ajax](http://api.jquery.com/jQuery.ajax/)).
|
||||
@@ -0,0 +1,24 @@
|
||||
|
||||
Event Data
|
||||
==========
|
||||
|
||||
<ul>
|
||||
<li class='article'>Event Object</li>
|
||||
<li><a href='events_array'>events</a> <em>(as an array)</em></li>
|
||||
<li><a href='events_json_feed'>events</a> <em>(as a json feed)</em></li>
|
||||
<li><a href='events_function'>events</a> <em>(as a function)</em></li>
|
||||
<li>eventSources</li>
|
||||
<li>allDayDefault</li>
|
||||
<li>startParam</li>
|
||||
<li>endParam</li>
|
||||
<li>cacheParam</li>
|
||||
<li class='callback'><a href='loading'>loading</a> <em>(callback)</em></li>
|
||||
<li class='method'><a href='updateEvent'>updateEvent</a> <em>(method)</em></li>
|
||||
<li class='method'><a href='clientEvents'>clientEvents</a> <em>(method)</em></li>
|
||||
<li class='method'><a href='removeEvents'>removeEvents</a> <em>(method)</em></li>
|
||||
<li class='method'><a href='refetchEvents'>refetchEvents</a> <em>(method)</em></li>
|
||||
<li class='method'><a href='addEventSource'>addEventSource</a> <em>(method)</em></li>
|
||||
<li class='method'><a href='removeEventSource'>removeEventSource</a> <em>(method)</em></li>
|
||||
</ul>
|
||||
|
||||
See also: [renderEvent]() (for adding an event)
|
||||
@@ -0,0 +1,15 @@
|
||||
|
||||
loading
|
||||
=======
|
||||
|
||||
Triggered when event fetching starts/stops.
|
||||
|
||||
<div class='spec' markdown='1'>
|
||||
function( *isLoading*, *view* )
|
||||
</div>
|
||||
|
||||
Triggered with a `true` argument when the calendar begins fetching events via AJAX. Triggered with `false` when done.
|
||||
|
||||
Last argument is the current [View Object](../views/View_Object).
|
||||
|
||||
This function is often used to show/hide a loading indicator.
|
||||
@@ -0,0 +1,13 @@
|
||||
|
||||
refetchEvents *1.3*
|
||||
===================
|
||||
|
||||
Refetches events from all sources and rerenders them on the screen.
|
||||
|
||||
<div class='spec' markdown='1'>
|
||||
.fullCalendar( 'refetchEvents' )
|
||||
</div>
|
||||
|
||||
<div class='version-info' markdown='1'>
|
||||
Prior to version 1.3, the same effect was achieved by the *refresh* method.
|
||||
</div>
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
removeEventSource *1.2*
|
||||
=======================
|
||||
|
||||
Dynamically removes an event source.
|
||||
|
||||
<div class='spec' markdown='1'>
|
||||
.fullCalendar( 'removeEventSource', *source* )
|
||||
</div>
|
||||
|
||||
Source must be a reference to the original Array/URL/Function.
|
||||
Events from the source will immediately be removed from the calendar.
|
||||
@@ -0,0 +1,17 @@
|
||||
|
||||
removeEvents *1.2*
|
||||
==================
|
||||
|
||||
Removes events from the calendar.
|
||||
|
||||
<div class='spec' markdown='1'>
|
||||
.fullCalendar( 'removeEvents' [, *idOrFilter* ] )
|
||||
</div>
|
||||
|
||||
If `idOrFilter` is omitted, *all* events are removed.
|
||||
|
||||
If `idOrFilter` is an ID, all events with the same ID will be removed.
|
||||
|
||||
`idOrFilter` may also be a filter function that accepts one [Event Object]()
|
||||
argument and returns `true` if it should be removed.
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
|
||||
startParam
|
||||
==========
|
||||
|
||||
A GET parameter of this name will be inserted into each JSON feed's URL.
|
||||
|
||||
<div class='spec' markdown='1'>
|
||||
String, *default*: `'start'`
|
||||
</div>
|
||||
|
||||
The value of this GET parameter will be a UNIX timestamp denoting the start of the first visible day (inclusive).
|
||||
@@ -0,0 +1,26 @@
|
||||
|
||||
updateEvent *1.2*
|
||||
=================
|
||||
|
||||
Reports changes to an event and renders them on the calendar.
|
||||
|
||||
<div class='spec' markdown='1'>
|
||||
.fullCalendar( 'updateEvent', *event* )
|
||||
</div>
|
||||
|
||||
`event` must be the original [Event Object]() for an event,
|
||||
**NOT** merely a reconstructed object.
|
||||
The original Event Object can obtained by callbacks such as [eventClick](../clicking_hovering/eventClick),
|
||||
or by the [clientEvents]() method.
|
||||
|
||||
Here is how you might update an event after a click:
|
||||
|
||||
$('#calendar').fullCalendar({
|
||||
eventClick: function(event, element) {
|
||||
|
||||
event.title = "CLICKED!";
|
||||
|
||||
$('#calendar').fullCalendar('updateEvent', event);
|
||||
|
||||
}
|
||||
});
|
||||
Reference in New Issue
Block a user