more doc changes

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

View file

@ -35,7 +35,7 @@ html:
arshaw:
mkdir -p build/html build/doctrees
$(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 "Build finished. The HTML pages are in build/html."

View file

@ -2,62 +2,68 @@
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:
s seconds
ss seconds, 2 digits
m minutes
mm minutes, 2 digits
h hours
hh hours, 2 digits
H hours, military time
HH hours, milirary time, 2 digits
d date number
dd date number, 2 digits
ddd date name, short
dddd date name, full
M month number
MM month number, 2 digits
MMM month name, short
MMMM month name, full
yy year, 2 digits
yyyy year, 4 digits
t 'a' or 'p'
tt 'am' or 'pm'
T 'A' or 'P'
TT 'AM' or 'PM'
u ISO8601 format
S 'st', 'nd', 'rd', 'th' for the date
* **s** - seconds
* **ss** - seconds, 2 digits
* **m** - minutes
* **mm** - minutes, 2 digits
* **h** - hours
* **hh** - hours, 2 digits
* **H** - hours, military time
* **HH** - hours, milirary time, 2 digits
* **d** - date number
* **dd** - date number, 2 digits
* **ddd** - date name, short
* **dddd** - date name, full
* **M** - month number
* **MM** - month number, 2 digits
* **MMM** - month name, short
* **MMMM** - month name, full
* **yy** - year, 2 digits
* **yyyy** - year, 4 digits
* **t** - 'a' or 'p'
* **tt** - 'am' or 'pm'
* **T** - 'A' or 'P'
* **TT** - 'AM' or 'PM'
* **u** - ISO8601 format
* **S** - 'st', 'nd', 'rd', 'th' for the date
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``:
{...}
switches to formatting the 2nd date
.. _formatDates:
**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
alternate date in the same regards
``[...]``
only displays the enclosed format if the current date is different from the
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.
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.

View file

@ -1,118 +1,117 @@
Feeds and Sources
=================
.. _event-sources:
Event Sources
=============
The following options determine *how* events get on the calendar:
**events**: Array/String/Function
An array of :ref:`CalEvents <CalEvents>` can be used to hardcode events into 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) {
Or, a URL can be provided. This URL should return JSON for an array of
:ref:`CalEvents <CalEvents>`. 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) {
// 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)
// format the result into an array of 'CalEvent' objects
// (not seen here)
// then, pass the 'calevent' array to the callback
callback(calevents);
});
}
// 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.
**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).
**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).
**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.
**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.
.. _CalEvents:
.. _CalEvent:
CalEvent Objects
================
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
:ref:`Triggered Actions <TriggeredActions>`. Here are the properties of a
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. Absolutely essential for multi-day
and repeating events to be dragged and dropped correctly.
**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
**title**: String
The text on an event's element
**date**: Date
Alias for ``start``
**date**: Date
Alias for ``start``
**start**: Date
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>`.
**start**: Date
A javascript Date object indicating the date/time an event begins.
**allDay**: Boolean (optional, defaults to ``true``)
Determines whether an event's time is displayed (such as 3pm).
``false`` will show the time, ``true`` will not.
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.
**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`` property for this single event.
**end**: Date (optional)
A javascript Date object indicating the date/time an event ends.
If the event is an all-day event, specifies 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 <event-sources>`.
**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.
link to methods...
**allDay**: Boolean (optional, defaults to ``true``)
Determines whether an event's time is displayed (such as 3pm).
``false`` will show the time, ``true`` will not.
**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.

View file

@ -28,10 +28,8 @@ Then, you must obtain your calendar's **XML feed URL**.
#. Your feed's URL will appear.
The API for integrating a Google Calendar feed has changed since
FullCalendar 1.1. The ``$.fullCalendar.gcalFeed`` function now produces
an event source that can be passed to the ``events`` or ``eventSources``
option::
The ``$.fullCalendar.gcalFeed`` function produces an event source that can be
passed to the ``events`` or ``eventSources`` options::
$('#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
* **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.

View file

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

View file

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

View file

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

View file

@ -3,22 +3,23 @@ Theming
=======
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
fullcalendar.css on the current page. You must also enable the ``theme`` option.
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.
Here is the full list of theme-related options:
theme: Boolean (default: false)
Enables/disables use of jQuery UI themes
**theme**: Boolean, *Default*: ``false``
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
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``::
Here is the default value for buttonIcons:
{
prev: 'circle-triangle-w',
next: 'circle-triangle-e'
}
{
prev: 'circle-triangle-w',
next: 'circle-triangle-e'
}

View file

@ -1,121 +1,126 @@
.. _triggered-actions:
Triggered Actions
=================
The following options are *functions* that get executed every time something
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)
Triggered once when the calendar loads and every time the
calendar's view is changed. This includes after the prev or next
button is pressed.
**viewDisplay**: function(*view*)
Triggered once when the calendar loads and every time the
calendar's view is changed. This includes when the prev or next
button is pressed.
**loading**: function(isLoading, view)
Triggered with a ``true`` argument when the calendar begins fetching
events via AJAX. Triggered with ``false`` when done.
**loading**: function(*isLoading, view*)
Triggered with a ``true`` argument when the calendar begins fetching
events via AJAX. Triggered with ``false`` when done.
**windowResize**: function(view)
Triggered after the calendar has recovered from a resize due to 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``
**windowResize**: function(*view*)
Triggered after the calendar's dimensions have been changed due to
the containing window being resized.
**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.
``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*)
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
===========
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 of one of the available views (month, basicWeek, basicDay)
**name**: String
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
Title text that is displayed at the top of the header
(such as "September 2009" or "Sep 7 - 13 2009").
Because this is an *exclusive* value, if the calendar has a
month-view on October 2009, ``end`` will be November 1st.
**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
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.
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``).
In week and day views, this value will always be the same as ``start``.
**visEnd**: Date
The Date of the day *after* the last visible day
(because it is exclusive like ``end``).