deac/fullcalendar
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

more doc changes

Browse source
This commit is contained in:
Adam Shaw 2009-09-14 03:36:27 +00:00
parent 176193a18c
commit 2841a62e74
9 changed files with 409 additions and 404 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/Makefile
View file

@ -35,7 +35,7 @@ html:
arshaw: arshaw:
mkdir -p build/html build/doctrees mkdir -p build/html build/doctrees
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
cp -r build/html/* /var/www/arshaw/pages/fullcalendar/docs12/ cp -r build/html/* /var/www/arshaw/pages/fullcalendar/docs/
@echo @echo
@echo "Build finished. The HTML pages are in build/html." @echo "Build finished. The HTML pages are in build/html."

94
docs/date-utils.txt
View file

@ -2,62 +2,68 @@
Date Utilities Date Utilities
============== ==============
formatDate $.fullCalendar.formatDate(date, formatString, options) **formatDate** - $.fullCalendar.formatDate(*date, formatString, [options]*)
Format a date into a string value with a specified format.
The format can be combinations of the following: The format can be combinations of the following:
s seconds * **s** - seconds
ss seconds, 2 digits * **ss** - seconds, 2 digits
m minutes * **m** - minutes
mm minutes, 2 digits * **mm** - minutes, 2 digits
h hours * **h** - hours
hh hours, 2 digits * **hh** - hours, 2 digits
H hours, military time * **H** - hours, military time
HH hours, milirary time, 2 digits * **HH** - hours, milirary time, 2 digits
d date number * **d** - date number
dd date number, 2 digits * **dd** - date number, 2 digits
ddd date name, short * **ddd** - date name, short
dddd date name, full * **dddd** - date name, full
M month number * **M** - month number
MM month number, 2 digits * **MM** - month number, 2 digits
MMM month name, short * **MMM** - month name, short
MMMM month name, full * **MMMM** - month name, full
yy year, 2 digits * **yy** - year, 2 digits
yyyy year, 4 digits * **yyyy** - year, 4 digits
t 'a' or 'p' * **t** - 'a' or 'p'
tt 'am' or 'pm' * **tt** - 'am' or 'pm'
T 'A' or 'P' * **T** - 'A' or 'P'
TT 'AM' or 'PM' * **TT** - 'AM' or 'PM'
u ISO8601 format * **u** - ISO8601 format
S 'st', 'nd', 'rd', 'th' for the date * **S** - 'st', 'nd', 'rd', 'th' for the date
Special Characters: Special Characters:
'...' ``'...'``
literal text literal text
'' ``''``
single quote (represented by two single quotes) single quote
(...) ``(...)``
only displays format if one of the enclosed variables is non-zero only displays format if one of the enclosed variables is non-zero
``options`` can override any of the Locale Options *options* can override any of the :ref:`Locale Options<locale>`
formatDates $.fullCalendar.formatDates(date1, date2, formatString, options)
Similar to formatDate, but accepts *two* dates, leveraging the following
special characters in ``formatString``:
{...} .. _formatDates:
switches to formatting the 2nd date
**formatDates** - $.fullCalendar.formatDates(*date1, date2, formatString, [options]*)
Similar to ``formatDate``, but accepts *two* dates, leveraging the following
special characters in *formatString*:
``{...}``
switches to formatting the 2nd date
[...] ``[...]``
only displays format if the current date is different from the only displays the enclosed format if the current date is different from the
alternate date in the same regards alternate date in the same regards
parseDate $.fullCalendar.parseDate(string)
Parse a string and return a javascript Date object. **parseDate** - $.fullCalendar.parseDate(*string*)
Parses a string and returns a javascript Date object.
The string may be in ISO8601 format, IETF format, or a UNIX timestamp. The string may be in ISO8601 format, IETF format, or a UNIX timestamp.
parseISO8601 $.fullCalendar.parseISO8601(string, ignoreTimezone)
Parse an ISO8601 string into a javascript Date object. **parseISO8601** - $.fullCalendar.parseISO8601(*string, [ignoreTimezone]*)
Parses an ISO8601 string into a javascript Date object.

187
docs/events-and-sources.txt
View file

@ -1,118 +1,117 @@
Feeds and Sources .. _event-sources:
=================
Event Sources
=============
The following options determine *how* events get on the calendar: The following options determine *how* events get on the calendar:
**events**: Array/String/Function **events**: Array/String/Function
An array of :ref:`CalEvents <CalEvents>` can be used to hardcode events into the An array of :ref:`CalEvents <CalEvent>` can be used to hardcode events into the
calendar. 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) {
Or, a URL can be provided. This URL should return JSON for an array of // do some asynchronous ajax
:ref:`CalEvents <CalEvents>`. GET parameters, determined by the $.getJSON("/myscript",
``startParam`` and ``endParam`` options, will be inserted into the URL. {
These parameters indicate the UNIX timestamp of the start of the first start: start.getTime(),
visible day (inclusive) and the end of the last visible day (exclusive). end: end.getTime()
},
Or, a function can be provided for custom fetching. The function is function(result) {
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 // format the result into an array of CalEvents
fetching is complete. Here is the general form:: // (not seen here)
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 'CalEvent' objects // then, pass the CalEvent array to the callback
// (not seen here) callback(calevents);
// then, pass the 'calevent' array to the callback });
callback(calevents);
}
});
}
**eventSources**: Array **eventSources**: Array
Similar to the ``events`` options, except one may specify *multiple* sources. 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 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. functions, an array of hardcoded event arrays, or any combination.
**startParam**: String, default:``"start"`` **startParam**: String, *Default*: ``'start'``
A GET parameter of this name will be inserted into the URL when fetching 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 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). timestamp denoting the start of the first visible day (inclusive).
**endParam**: String, default:``"end"`` **endParam**: String, *Default*: ``'end'``
A GET parameter of this name will be inserted into the URL when fetching 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 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). timestamp denoting the end of the last visible day (exclusive).
**cacheParam**: String, default:``"_"`` **cacheParam**: String, *Default*: ``'_'``
When using a JSON url, a parameter of this name will When using a JSON url, a parameter of this name will
automatically be inserted into the URL to prevent the browser from automatically be inserted into the URL to prevent the browser from
caching the response. The value will be the current millisecond time. caching the response. The value will be the current millisecond time.
.. _CalEvents: .. _CalEvent:
CalEvent Objects CalEvent Objects
================ ================
A CalEvent is a data structure that frequents FullCalendar's API. It is the A CalEvent is a data structure that frequents FullCalendar's API. It is the
standardized currency used in :ref:`EventSources`. It is also passed to various standardized currency used in :ref:`event-sources`. It is also passed to various
:ref:`Triggered Actions <TriggeredActions>`. Here are the properties of a :ref:`Triggered Actions <triggered-actions>`. Here are the properties of a
CalEvent: CalEvent:
**id**: Integer/String **id**: Integer/String
Uniquely identifies the given event. Absolutely essential for multi-day Uniquely identifies the given event. Instances of repeating events should
and repeating events to be dragged and dropped correctly. all have the same id.
**title**: String **title**: String
The text on an event's element The text on an event's element
**date**: Date **date**: Date
Alias for ``start`` Alias for ``start``
**start**: Date **start**: Date
A javascript Date object indicating the date/time an event begins. A javascript Date object indicating the date/time an event begins.
In an :ref:`Event Source <EventSources>`, 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.
If the event is an all-day event, specify the inclusive last day
of the event. (This is different from previous versions of FullCalendar).
For example, an all-day event with start on Nov 10 and end on Nov 12
would span 3 days.
As with ``start``, IETF and ISO8601 strings can be used with an
:ref:`Event Source <EventSources>`.
**allDay**: Boolean (optional, defaults to ``true``) In an :ref:`Event Source <event-sources>`, for convenience,
Determines whether an event's time is displayed (such as 3pm). one can also use a string in IETF format (ex: "Wed, 18 Oct 2009 13:00:00 EST"),
``false`` will show the time, ``true`` will not. a string in ISO8601 format (ex: "2009-11-05T13:15:30Z") or an integer
UNIX timestamp.
**className**: String/Array (optional) **end**: Date (optional)
A CSS class (or array of classes) that will be attached to this event's A javascript Date object indicating the date/time an event ends.
element. If the event is an all-day event, specifies the inclusive last day
of the event. (This is different from previous versions of FullCalendar).
**editable**: Boolean (optional)
Overrides the master ``editable`` property for this single event. For example, an all-day event with start on *Nov 10* and end on *Nov 12*
would span *3 days*.
As with ``start``, IETF and ISO8601 strings can be used with an
:ref:`Event Source <event-sources>`.
**source**: Array/String/Function (automatically populated) **allDay**: Boolean (optional, defaults to ``true``)
A reference to the original array, JSON URL, or function the event Determines whether an event's time is displayed (such as 3pm).
came from. Do not worry about populating this value, FullCalendar will ``false`` will show the time, ``true`` will not.
do this automatically.
**className**: String/Array (optional)
A CSS class (or array of classes) that will be attached to this event's
link to methods... 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.

8
docs/google-calendar.txt
View file

@ -28,10 +28,8 @@ Then, you must obtain your calendar's **XML feed URL**.
#. Your feed's URL will appear. #. Your feed's URL will appear.
The API for integrating a Google Calendar feed has changed since The ``$.fullCalendar.gcalFeed`` function produces an event source that can be
FullCalendar 1.1. The ``$.fullCalendar.gcalFeed`` function now produces passed to the ``events`` or ``eventSources`` options::
an event source that can be passed to the ``events`` or ``eventSources``
option::
$('#calendar').fullCalendar({ $('#calendar').fullCalendar({
@ -46,6 +44,6 @@ Here is a list of available options:
* **className** - CSS class to attach to each event from this Google Calendar * **className** - CSS class to attach to each event from this Google Calendar
* **draggable** - whether to allow dragging (default: ``false``) * **editable** - whether to allow dragging/resizing (default: ``false``)
See *gcal.html* in the *examples* directory for a complete example. See *gcal.html* in the *examples* directory for a complete example.

125
docs/index.txt
View file

@ -2,7 +2,7 @@
Usage Usage
===== =====
The following code initializes a FullCalendar within an element of ID 'calendar':: The following code initializes a FullCalendar within an element::
$('#calendar').fullCalendar({ $('#calendar').fullCalendar({
@ -11,58 +11,43 @@ The following code initializes a FullCalendar within an element of ID 'calendar'
}) })
Available Views Basic Options
=============== =============
**month** - see example
**basicWeek** - see example
**basicDay** - see example
Basic Display Options
=====================
**year, month, date**: Integers **year, month, date**: Integers
The initial year/month/date when the calendar loads. The initial year/month/date when the calendar loads.
``month`` is 0-based, meaning January=0, February=1, etc.
``month`` is 1-based, meaning January=1, February=2, etc
(different from previous versions)
If ommitted, the calendar starts on the current date. If ommitted, the calendar starts on the current date.
**header**: Object, *Default*: ``{ left:'title', center:'', right:'prev,next' }`` **header**: Object/``false``, *Default*: ``{ left:'title', center:'', right:'prev,next' }``
Defines the buttons/text at the top of the calendar. Must be an Defines the buttons/text at the top of the calendar.
object with properties left, center, and right. Omitting a property ``false`` will display no header.
will cause it to inherit from the default. An object can be supplied with properties ``left``, ``center``, and ``right``.
These properties contain strings with comma separated values,
Property values contain a comma-separated string with any of the containing any of the following:
following items:
``title`` ``title``
text containing the current date or date-range text containing the current date or date-range
``prev`` ``prev``
button for moving the calendar back one month/week/day, button for moving the calendar back one month/week/day
depending on the current view
``next`` ``next``
button for moving the calendar forward one month/week/day, button for moving the calendar forward one month/week/day
depending on the current view
*a blank space*
visual gap between buttons/text
*a view name...* *a view name*
button that will switch the calendar to any of the button that will switch the calendar to any of the
available views :ref:`available-views`
Using an empty space as a separator instead of a comma will cause
adjacent buttons/text to be separated by a visual gap.
Specifying an empty string for left, center, or right will cause Specifying an empty string for a property will cause it display no text/buttons.
the area to be empty.
To change the text within a button, see the :ref:`buttonText<locale>` option.
**defaultView**: String, *Default*: ``'month'`` **defaultView**: String, *Default*: ``'month'``
The initial view then the calendar loads. Any of the available views. The initial view when the calendar loads. Any of the :ref:`available-views`.
**aspectRatio**: Float, *Default*: ``1.35`` **aspectRatio**: Float, *Default*: ``1.35``
A calendar is a block-level element that fills its entire avaiable width. A calendar is a block-level element that fills its entire avaiable width.
@ -75,44 +60,44 @@ Basic Display Options
``'fixed'`` ``'fixed'``
The calendar will always be 6 weeks tall. The calendar will always be 6 weeks tall.
The aspectRatio will always be maintained. The ``aspectRatio`` will always be maintained.
``'liquid'`` ``'liquid'``
The calendar will have either 4, 5, or 6 weeks, depending on the month. The calendar will have either 4, 5, or 6 weeks, depending on the month.
The height of the weeks will stretch to fill the available height, The height of the weeks will stretch to fill the available height,
as determined by aspectRatio. as determined by ``aspectRatio``.
``'variable'`` ``'variable'``
The calendar will have either 4, 5, or 6 weeks, depending on the month. The calendar will have either 4, 5, or 6 weeks, depending on the month.
The aspectRatio will NOT be maintained however. Each week will have The ``aspectRatio`` will NOT be maintained however. Each week will have
a constant height, meaning the calendar will change height month-to-month. a constant height, meaning the calendar's height will change month-to-month.
Event Editing Event Editing
============= =============
**editable**: Boolean, *Default*: ``false`` **editable**: Boolean, *Default*: ``false``
Whether the events on the calendar can be modified, i.e, Determines whether the events on the calendar can be modified, i.e,
if the events will be draggable and resizable. if the events will be *draggable* and *resizable*.
This can be overridden on a per-event basis with an event's This can be overridden on a per-event basis with a :ref:`CalEvent's <CalEvent>`
editable property. ``editable`` property.
For dragging, the jQuery UI draggable library is required. For dragging, the `jQuery UI draggable <http://jqueryui.com/demos/draggable/>`_ library is required.
For resizing, the jQuery UI resizable library is required.
Both require the jQuery UI core. For resizing, the `jQuery UI resizable <http://jqueryui.com/demos/resizable/>`_ library is required.
**disableDragging**: Boolean, *Default*: ``false`` **disableDragging**: Boolean, *Default*: ``false``
Disables all event dragging, even when events are editable Disables all event dragging, even when events are editable.
**disableResizing**: Boolean, *Default*: ``false`` **disableResizing**: Boolean, *Default*: ``false``
Disables all event resizing, even when events are editable Disables all event resizing, even when events are editable.
**dragOpacity**: Float, *Default*: ``1.0`` **dragOpacity**: Float, *Default*: ``1.0``
The opacity of an event when it is being dragged. The opacity of an event when it is being dragged.
**dragRevertDuration**: Float, *Default*: ``500`` **dragRevertDuration**: Float, *Default*: ``500``
The time in milliseconds it takes for an event to revert to its The time in milliseconds it takes for an event to revert to its
original position after un unsuccessful drag. original position after an unsuccessful drag.
Time & Date Formatting Time & Date Formatting
@ -120,33 +105,45 @@ Time & Date Formatting
**titleFormat**: String/Object **titleFormat**: String/Object
Determines the text that will be displayed in the header's title Determines the text that will be displayed in the header's title
using formatDates' format string. A string will set the title format using :ref:`formatDates' <formatDates>`' format string. A string will set the title format
for ALL views. An object hash will set the format on a per-view basis. for *all* views. An object hash will set the format on a per-view basis.
Here is the default, showing example outputs for each view:: Here is the default, showing example outputs for each view::
{ {
month: 'MMMM yyyy', // September 2009 month: 'MMMM yyyy', // September 2009
week: "MMM d[ yyyy]{ '&#8212;'[ MMM] d yyyy}", // Sep 7 - 13 2009 week: "MMM d[ yyyy]{ '&#8212;'[ MMM] d yyyy}", // Sep 7 - 13 2009
day: 'dddd, MMM d, yyyy' // Tuesday, Sep 8, 2009 day: 'dddd, MMM d, yyyy' // Tuesday, Sep 8, 2009
} }
**columnFormat**: String/Object **columnFormat**: String/Object
Determines the text that will be displayed on a view's column headers Determines the text that will be displayed on a view's column headings
using formatDates' format string. A string will set the column header format using :ref:`formatDates' <formatDates>` format string. A string will set the column header format
for ALL views. An object hash will set the format on a per-view basis. for *all* views. An object hash will set the format on a per-view basis.
Here is the default, showing example outputs for each view:: Here is the default, showing example outputs for each view::
{ {
month: 'ddd', // Mon month: 'ddd', // Mon
week: 'ddd M/d', // Mon 9/7 week: 'ddd M/d', // Mon 9/7
day: 'dddd M/d' // Monday 9/7 day: 'dddd M/d' // Monday 9/7
} }
**timeFormat**: String, Default: ``'h(:mm)t'`` **timeFormat**: String, *Default*: ``'h(:mm)t'``
Determines the time-text that will be displayed on an event Determines the time-text that will be displayed on an event
using formatDates' format string. The default format outputs text using :ref:`formatDates' <formatDates>` format string. The default format outputs text
such as 9a or 5:30p. such as '9a' or '5:30p'.
Time-text will only be displayed for event objects that have Time-text will only be displayed for :ref:`CalEvent` that have
allDay equal to false. ``allDay`` equal to ``false``.
.. _available-views:
Available Views
===============
**month** - `see example <http://google.com/>`_
**basicWeek** - `see example <http://google.com/>`_
**basicDay** - `see example <http://google.com/>`_

30
docs/locale.txt
View file

@ -1,32 +1,34 @@
Locale .. _locale:
=======================================
firstDay Integer default: 0 Locale Options
The day-of-week each week begins. 0 = Sunday (default), ==============
1 = Monday (for UK users), 2 = Tuesday, etc.
**firstDay**: Integer, *Default*: ``0``
The day-of-week each week begins. Sunday=0,
Monday=1 (for UK users), Tuesday=2, etc.
isRTL Boolean default: false **isRTL**: Boolean, *Default*: ``false``
Displays the calendar right-to-left (for languages such as Arabic and Hebrew) Displays the calendar right-to-left (for languages such as Arabic and Hebrew)
monthNames Array default: ['January','February','March'... **monthNames**: Array, *Default*: ``['January','February','March'...``
Full names of months. Full names of months.
monthNamesShort Array default: ['Jan','Feb','Mar'... **monthNamesShort**: Array, *Default*: ``['Jan','Feb','Mar'...``
Abbreviated names of months. Abbreviated names of months.
dayNames Array default: ['Sunday','Monday','Tuesday'... **dayNames**: Array, *Default*: ``['Sunday','Monday','Tuesday'...``
Full names of days-of-week. Full names of days-of-week.
dayNamesShort Array default: ['Sun','Mon','Tue'... **dayNamesShort**: Array, *Default*: ``['Sun','Mon','Tue'...``
Abbreviated names of days-of-week. Abbreviated names of days-of-week.
buttonText **buttonText**: Object
Text that will be displayed on buttons of the header. Default: Text that will be displayed on buttons of the header. Default::
{ {
prev: '&#9668;', prev: '&#9668;', // left triangle
next: '&#9658;', next: '&#9658;', // right triangle
today: 'today', today: 'today',
month: 'month', month: 'month',
week: 'week', week: 'week',

127
docs/methods.txt
View file

@ -2,80 +2,77 @@
Methods Methods
======= =======
The folling are a list of methods that can be called on an FullCalendar-initialized The following are methods that can be called on a FullCalendar-initialized
jQuery object: jQuery object:
prev .fullCalendar('prev') **prev** - .fullCalendar('prev')
Moves the calendar one step back (either by a month, week, or day). Moves the calendar one step back (either by a month, week, or day).
next .fullCalendar('next') **next** - .fullCalendar('next')
Moves the calendar one step forward (either by a month, week, or day). Moves the calendar one step forward (either by a month, week, or day).
today .fullCalendar('today')
Moves the calendar to the current date.
gotoDate .fullCalendar('gotoDate', year, month, date) **today** - .fullCalendar('today')
Moves the calendar to an arbitrary year/month/date. Moves the calendar to the current date.
``month`` is 1-based, meaning January=1, February=2, etc
(different from previous versions of FullCalendar)
moveDate .fullCalendar('moveDate', years, months, days) **gotoDate** - .fullCalendar('gotoDate', *year, [month, [date]]*)
Moves the calendar forward/backward an arbitrary amount of time Moves the calendar to an arbitrary year/month/date.
updateEvent .fullCalendar('renderEvent', calEvent) ``month`` is 0-based, meaning January=0, February=1, etc.
Reports changes to the given calEvent. This will cause the event
to be rerendered on the calendar.
If there are repeating events on the calendar with the
same ID, these events will be changed as well.
``calEvent`` must be an object retrieved from a triggered event
or from clientEvents.
renderEvent .fullCalendar('renderEvent', calEvent, stick) **moveDate** - .fullCalendar('moveDate', *years, [months, [days]]*)
Renders a new event on the calendar. ``calEvent`` must have Moves the calendar forward/backward an arbitrary amount of time.
at least a ``title`` and a ``start``.
By default the event will disappear once the user switches views
or clicks prev/next. However, specifying ``stick`` as ``true``
will cause the event to be permanently fixed to the calendar.
removeEvents .fullCalendar('removeEvent', idOrFilter) **updateEvent** - .fullCalendar('updateEvent', *calEvent*)
If the second argument is omitted, all events are removed. Reports changes about a modified :ref:`CalEvent <CalEvent>`. This will cause the event
to be rerendered on the calendar.
If the second argument is a calEvent ID, all events with If there are repeating events on the calendar with the
the same ID will be removed. same ID, these events will be changed as well.
The second argument may be a filter function that accepts ``calEvent`` must be a :ref:`CalEvent <CalEvent>` retrieved from a
one calEvent argument and returns ``true`` or ``false`` about :ref:`Triggered Action<triggered-actions>` or from the ``clientEvents`` method.
whether is should be removed.
**renderEvent** - .fullCalendar('renderEvent', *calEvent, [stick]*)
clientEvents .fullCalendar('clientEvents', idOrFilter) Renders a new event on the calendar. ``calEvent`` must have
This method will return calEvents that FullCalendar has stored on at least a ``title`` and a ``start``.
the client-side (javascript in the browser).
By default, the event will disappear once the user switches views
If the second argument is omitted, all events will be returned. or clicks prev/next. However, specifying ``stick`` as ``true``
will cause the event to be permanently fixed to the calendar.
If the second argument is a calEvent ID, all events with the
same ID will be returned. **removeEvents** - .fullCalendar('removeEvents', *[idOrFilter]*)
If the second argument is omitted, all events are removed.
The second argument may also be a filter function that accepts If the second argument is a :ref:`CalEvent's <CalEvent>` ID, all events with
one calEvent argument and returns ``true`` or ``false`` about the same ID will be removed.
whether it should be included in the result set.
The second argument may also be a filter function that accepts
one :ref:`CalEvent <CalEvent>` argument and returns ``true`` or ``false`` about
whether it should be removed.
**clientEvents** - .fullCalendar('clientEvents', *[idOrFilter]*)
This method will return :ref:`CalEvents <CalEvent>` that FullCalendar has stored on
the client-side (browser).
If the second argument is omitted, all events will be returned.
If the second argument is a :ref:`CalEvent's <CalEvent>` ID, all events with the
same ID will be returned.
The second argument may also be a filter function that accepts
one :ref:`CalEvent <CalEvent>` argument and returns ``true`` or ``false`` about
whether it should be included in the result set.
addEventSource .fullCalendar('addEventSource', source) **addEventSource** - .fullCalendar('addEventSource', *source*)
Adds an event source. ``source`` may be an array/string/function just as in Adds an :ref:`Event Source <event-sources>`. ``source`` may be an array/string/function just as in
the ``events`` option. Events will be immediately fetched from this source the ``events`` option. Events will be immediately fetched from this source
and placed on the calendar. and placed on the calendar.
removeEventSource .fullCalendar('removeEventSource', source) **removeEventSource** - .fullCalendar('removeEventSource', *source*)
Remove an event source. ``source`` must be a reference to the Removes an :ref:`Event Source <event-sources>`. ``source`` must be a reference to the
original array/string/function. original array/string/function. Events from the source will immediately be
removed from the calendar.
rerenderEvents .fullCalendar('rerenderEvents') **rerenderEvents** - .fullCalendar(``'rerenderEvents'``)
Rerenders all events on the screen. Rerenders all events on the screen.
refetchEvents .fullCalendar('refetchEvents') **refetchEvents** - .fullCalendar(``'refetchEvents'``)
Refetches events from all event sources and rerenders them on the screen. Refetches events from all event sources and rerenders them on the screen.

29
docs/theming.txt
View file

@ -3,22 +3,23 @@ Theming
======= =======
FullCalendar can be used with jQuery UI themes. Themes provide a more stylized FullCalendar can be used with jQuery UI themes. Themes provide a more stylized
look for the calendar and can easily be created using the jQuery UI ThemeRoller. look for the calendar and can easily be created using the
`jQuery UI ThemeRoller <http://jqueryui.com/themeroller/>`_.
In order for themes to work, you must include the theme's CSS file AND In order for themes to work, you must include the theme's CSS file and
fullcalendar.css on the current page. You must also enable the ``theme`` option. *fullcalendar.css* on the current page. You must also enable the ``theme`` option.
Here is the full list of theme-related options: Here is the full list of theme-related options:
theme: Boolean (default: false) **theme**: Boolean, *Default*: ``false``
Enables/disables use of jQuery UI themes Enables/disables use of jQuery UI themes
**buttonIcons**: Object
Determines which icons appear within header buttons. If a button
does not have an entry, it falls back to using ``buttonText``.
buttonIcons: Object Here is the default value for ``buttonIcons``::
Determines which icons appear within header buttons. If a button
does not have an entry, it falls back to using buttonText.
Here is the default value for buttonIcons: {
prev: 'circle-triangle-w',
{ next: 'circle-triangle-e'
prev: 'circle-triangle-w', }
next: 'circle-triangle-e'
}

211
docs/triggered-actions.txt
View file

@ -1,121 +1,126 @@
.. _triggered-actions:
Triggered Actions Triggered Actions
================= =================
The following options are *functions* that get executed every time something The following options are *functions* that get executed every time something
special happens. For every triggered action, a final ``view`` parameter is special happens. For every triggered action, a final ``view`` parameter is
always available (more below). always available (:ref:`more below <view-object>`).
**viewDisplay**: function(view) **viewDisplay**: function(*view*)
Triggered once when the calendar loads and every time the Triggered once when the calendar loads and every time the
calendar's view is changed. This includes after the prev or next calendar's view is changed. This includes when the prev or next
button is pressed. button is pressed.
**loading**: function(isLoading, view) **loading**: function(*isLoading, view*)
Triggered with a ``true`` argument when the calendar begins fetching Triggered with a ``true`` argument when the calendar begins fetching
events via AJAX. Triggered with ``false`` when done. events via AJAX. Triggered with ``false`` when done.
**windowResize**: function(view) **windowResize**: function(*view*)
Triggered after the calendar has recovered from a resize due to the Triggered after the calendar's dimensions have been changed due to
containing window being resized. the containing window being resized.
``this`` is set to the main element
**dayClick**: function(dayDate, view)
Triggered when the user clicks on a day. ``dayDate`` is a Date object with
it's time set to 00:00:00.
``this`` is set to the TD element of the clicked day.
**eventRender**: function(calEvent, element, view)
Triggered before an element is rendered for the given :ref:`CalEvent <CalEvents>`.
``element`` is the jQuery element that will be used by default. You may modify
this element or return a brand new element that will be used instead.
Returning ``false`` will prevent the event from being rendered at all.
This function is great for attaching other jQuery plugins to each event
element, such as a `qTip <http://craigsworks.com/projects/qtip/docs/>`_
tooltip effect.
**eventClick**, **eventMouseover**, **eventMouseout**: function(calEvent, jsEvent, view)
Triggered on click/mouseover/mouseout actions for an event.
``calEvent`` holds that event's information (date, title, etc).
``jsEvent`` holds the native javascript event (with information about click position, etc).
``this`` is set to the event's element
For ``eventClick``, return ``false`` to prevent the browser from going to
the event's URL.
**eventDragStart**, **eventDragStop**: function(calEvent, jsEvent, ui, view)
Triggered before/after an event is dragged (but not necessarily moved to a new day).
``calEvent`` holds that event's information (date, title, etc).
``jsEvent`` holds the native javascript event (with information about click position, etc).
``ui`` holds the jQuery UI object.
``this`` is set to the event's element
**eventDrop**: function(calEvent, dayDelta, minuteDelta, jsEvent, ui, view)
Triggered when dragging stops and the event has moved to a *different* day.
``dayDelta`` holds the number of days the event was moved forward (a positive number)
or backwards (a negative number).
``minuteDelta`` will always be ``0`` and is reserved for a future release
of FullCalendar where there will be an agenda view.
``dayDelta`` and ``minuteDelta`` are elegant for dealing with multi-day and
repeating events. If updating a remote database, just add these values to the
start and end times of all events with the given ``calEvent.id``
**eventResizeStart**, **eventResizeStop**: function(calEvent, jsEvent, ui, view) ``this`` is set to the main element.
Triggered before/after an event is resized (but not necessarily changed).
``calEvent`` holds that event's information (date, title, etc).
``jsEvent`` holds the native javascript event (with information about click position, etc).
``ui`` holds the jQuery UI object.
``this`` is set to the event's element
**eventResized**: function(event, dayDelta, minuteDelta, jsEvent, ui, view)
Triggered when an event is resized and **changed** in duration.
``dayDelta`` holds the number of days the event's end time was moved
forward (a positive number) or backwards (a negative number).
``minuteDelta`` will always be ``0`` and is reserved for a future release
of FullCalendar where there will be an agenda view.
**dayClick**: function(*dayDate, view*)
Triggered when the user clicks on a day. ``dayDate`` is a Date object with
it's time set to 00:00:00.
``this`` is set to the TD element of the clicked day.
**eventRender**: function(*calEvent, element, view*)
Triggered before an element is rendered for the given :ref:`CalEvent <CalEvents>`.
``element`` is the jQuery element that will be used by default. You may modify
this element or return a brand new element that will be used instead.
Returning ``false`` will prevent the event from being rendered at all.
This function is great for attaching other jQuery plugins to each event
element, such as a `qTip <http://craigsworks.com/projects/qtip/docs/>`_
tooltip effect.
**eventClick**, **eventMouseover**, **eventMouseout**: function(*calEvent, jsEvent, view*)
Triggered on click/mouseover/mouseout actions for an event.
``calEvent`` holds that event's information (date, title, etc).
``jsEvent`` holds the native javascript event (with information about click position, etc).
``this`` is set to the event's element
For ``eventClick``, return ``false`` to prevent the browser from going to
the event's URL.
**eventDragStart**, **eventDragStop**: function(*calEvent, jsEvent, ui, view*)
Triggered before/after an event is dragged (but not necessarily moved to a new day).
``calEvent`` holds that event's information (date, title, etc).
``jsEvent`` holds the native javascript event (with information about click position, etc).
``ui`` holds the jQuery UI object.
``this`` is set to the event's element
**eventDrop**: function(*calEvent, dayDelta, minuteDelta, jsEvent, ui, view*)
Triggered when dragging stops and the event has moved to a *different* day.
``dayDelta`` holds the number of days the event was moved forward (a positive number)
or backwards (a negative number).
``minuteDelta`` will always be ``0`` and is reserved for a future release
of FullCalendar where there will be an agenda view.
``dayDelta`` and ``minuteDelta`` are elegant for dealing with multi-day and
repeating events. If updating a remote database, just add these values to the
start and end times of all events with the given ``calEvent.id``
**eventResizeStart**, **eventResizeStop**: function(*calEvent, jsEvent, ui, view*)
Triggered before/after an event is resized (but not necessarily changed).
``calEvent`` holds that event's information (date, title, etc).
``jsEvent`` holds the native javascript event (with information about click position, etc).
``ui`` holds the jQuery UI object.
``this`` is set to the event's element
**eventResized**: function(*event, dayDelta, minuteDelta, jsEvent, ui, view*)
Triggered when an event is resized and *changed in duration*.
``dayDelta`` holds the number of days the event's end time was moved
forward (a positive number) or backwards (a negative number).
``minuteDelta`` will always be ``0`` and is reserved for a future release
of FullCalendar where there will be an agenda view.
.. _view-object:
View Object View Object
=========== ===========
The final parameter of every callback is a *view* object. It has the following properties: The final parameter of every triggered action is a *view* object. It contains information about the
current view (whether month/basicWeek/basicDay) and contains the following properties:
**name**: String **name**: String
Name of one of the available views (month, basicWeek, basicDay) Name of one of the available views (month, basicWeek, basicDay)
**title**: String
Title text that is displayed at the top of the header
(such as "September 2009" or "Sep 7 - 13 2009").
**start**: Date
The Date of the first day of the month/week.
If day-view, the Date of the single day.
**end**: Date
The Date of the day *after* the last day of the month/week.
If day-view, the Date *after* the single day.
**title**: String Because this is an *exclusive* value, if the calendar has a
Title text that is displayed at the top of the header month-view on October 2009, ``end`` will be November 1st.
(such as "September 2009" or "Sep 7 - 13 2009").
**visStart**: Date
The Date of the first *visible* day of the view. In month-view,
this value is often before the 1st day of the month, because most
months do not begin on a Monday.
**start**: Date In week and day views, this value will always be the same as ``start``.
The Date of the first day of the month/week.
If day-view, the Date of the single day. **visEnd**: Date
The Date of the day *after* the last visible day
**end**: Date (because it is exclusive like ``end``).
The Date of the day **after** the last day of the month/week.
If day-view, the Date **after** the single day.
Because this is an **exclusive** value, if the calendar has a
month-view on October 2009, ``end`` will be November 1st.
**visStart**:
The Date of the first **visible** day of the view. In month-view,
this value is often before the 1st day of the month, because most
months do not begin on a Monday.
In week and day views, this value will always be the same as ``start``.
**visEnd**:
The Date of the day **after** the last visible day
(because it is exclusive like ``end``).