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

Browse source
This commit is contained in:
Adam Shaw 2009-09-13 22:25:49 +00:00
parent 50318c2f1a
commit 1f924d501a
11 changed files with 644 additions and 462 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

63
docs/date-utils.txt Executable file
View file

@ -0,0 +1,63 @@
Date Utilities
==============
formatDate $.fullCalendar.formatDate(date, formatString, options)
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
Special Characters:
'...'
literal text
''
single quote (represented by two single quotes)
(...)
only displays format if one of the enclosed variables is non-zero
``options`` can override any of the Locale Options
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
parseDate $.fullCalendar.parseDate(string)
Parse a string and return 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.

118
docs/events-and-sources.txt Executable file
View file

@ -0,0 +1,118 @@
Feeds and 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.
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) {
// format the result into an array of 'CalEvent' objects
// (not seen here)
// then, pass the 'calevent' array to the callback
callback(calevents);
});
}
**eventSources**: Array
Similar to the ``events`` options, except one may specify *multiple* sources.
For example, one may specify an array of JSON URL's, an array of custom
functions, an array of hardcoded event arrays, or any combination.
**startParam**: String, default:``"start"``
A GET parameter of this name will be inserted into the URL when fetching
events from a JSON script. The value of this GET parameter will be a UNIX
timestamp denoting the start of the first visible day (inclusive).
**endParam**: String, default:``"end"``
A GET parameter of this name will be inserted into the URL when fetching
events from a JSON script. The value of this GET parameter will be a UNIX
timestamp denoting the end of the last visible day (exclusive).
**cacheParam**: String, default:``"_"``
When using a JSON url, a parameter of this name will
automatically be inserted into the URL to prevent the browser from
caching the response. The value will be the current millisecond time.
.. _CalEvents:
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
CalEvent:
**id**: Integer/String
Uniquely identifies the given event. Absolutely essential for multi-day
and repeating events to be dragged and dropped correctly.
**title**: String
The text on an event's element
**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>`.
**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`` property 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.
link to methods...

51
docs/google-calendar.txt Executable file
View file

@ -0,0 +1,51 @@
Google Calendar
===============
To integrate with your Google Calendar, you must first **make your calendar public**:
#. In the Google Calendar interface, locate the "My Calendar" box on the left.
#. Click the arrow next to the calendar you need.
#. A menu will appear. Click "Share this calendar."
#. Check "Make this calendar public."
#. Make sure "Share only my free/busy information" is *unchecked*.
#. Click "Save."
Then, you must obtain your calendar's **XML feed URL**.
#. In the Google Calendar interface, locate the "My Calendar" box on the left
#. Click the arrow next to the calendar you need.
#. A menu will appear. Click "Calendar settings."
#. In the "Calendar Address" section of the screen, click the XML badge.
#. 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::
$('#calendar').fullCalendar({
events: $.fullCalendar.gcalFeed(
"http://www.google.com/calendar/feeds/...", // feed URL
{ className: 'gcal-events' } // optional options
)
});
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``)
See *gcal.html* in the *examples* directory for a complete example.

523
docs/index.txt
View file

@ -1,467 +1,152 @@
Main Usage Usage
========== =====
The following code initializes a FullCalendar within an element of ID 'calendar':: The following code initializes a FullCalendar within an element of ID 'calendar'::
$('#calendar').fullCalendar({ $('#calendar').fullCalendar({
// put your options here // put your options here
}) })
Available Views
.. _GeneralOptions:
General Options
=============== ===============
**year**, **month**: integers **month** - see example
The month that will be displayed when the calendar first loads.
``month`` is zero-based (January is 0, February is 1, etc).
**draggable**: boolean, default:``false`` **basicWeek** - see example
Determines if all events on the calendar can be dragged & dropped. If
``true``, requires `jQuery UI <http://jqueryui.com/>`_ core and draggables.
Can be overridden on a per-event basis with the ``draggable`` property of
each :ref:`CalEvent <CalEvents>`.
**fixedWeeks**: boolean, default:``true`` **basicDay** - see example
If ``true``, the calendar will always be 6 weeks tall. If ``false``, the
calendar's height will vary per month.
**abbrevDayHeadings**: boolean, default:``true``
Whether to display "Sun" versus "Sunday" for days of the week.
**title**: boolean, default:``true`` Basic Display Options
Determines whether a title such as "January 2009" will be displayed at the =====================
top of the calendar.
**titleFormat**: string, default:``"F Y"`` **year, month, date**: Integers
A string defining the format of the title above the calendar. The default The initial year/month/date when the calendar loads.
"F Y" creates strings such as "January 2009". Consult the
:ref:`$.fullCalendar.formatDate <formatDate>` documentation for a full
list of commands.
**buttons**: boolean/hash, default:``true`` ``month`` is 1-based, meaning January=1, February=2, etc
``true`` will display a previous-month, next-month, and "today" button. (different from previous versions)
The "today" button will only be visible for months other than the current.
``false`` will display absolutely no buttons. If ommitted, the calendar starts on the current date.
An object hash can be provided to display only *certain* buttons. The hash **header**: Object, *Default*: ``{ left:'title', center:'', right:'prev,next' }``
can have the following properties:: 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
today: bool/string, following items:
prevYear: bool/string,
prevMonth: bool/string,
nextMonth: bool/string,
nextYear: bool/string
}
A value of ``false`` will not display the button. A value of ``true`` will ``title``
display the button with some default text. A *string* value will display text containing the current date or date-range
the button *and* customize its text.
**showTime**: boolean/ ``"guess"``, default:``"guess"`` ``prev``
Determines if times will be displayed before each event's title. button for moving the calendar back one month/week/day,
``"guess"`` displays times only for events with non-zero start or end times. depending on the current view
**timeFormat**: string, default: ``"gx"`` ``next``
A string defining the format of dislayed event times. The default "gx" button for moving the calendar forward one month/week/day,
creates a string such as "9a". Consult the depending on the current view
:ref:`$.fullCalendar.formatDate <formatDate>`
documentation for a full list of commands.
**eventDragOpacity**: float *a view name...*
The opacity of an event element while it is being dragged (0.0 - 1.0) button that will switch the calendar to any of the
available views
**eventRevertDuration**: integer Using an empty space as a separator instead of a comma will cause
Controls the duration (in milliseconds) of the animation of an event adjacent buttons/text to be separated by a visual gap.
snapping back into place.
Specifying an empty string for left, center, or right will cause
the area to be empty.
**defaultView**: String, *Default*: ``'month'``
The initial view then the calendar loads. Any of the available views.
.. _TriggeredActions: **aspectRatio**: Float, *Default*: ``1.35``
A calendar is a block-level element that fills its entire avaiable width.
The calendar's height, however, is determined by this ratio of width-to-height.
(Hint: larger numbers make smaller heights).
Triggered Actions **weekMode**: String, *Default*: ``'fixed'``
================= Determines the number of weeks displayed in a month view.
Also determines each week's height. Available options:
The following options are *functions* that get executed every time something ``'fixed'``
special happens: The calendar will always be 6 weeks tall.
The aspectRatio will always be maintained.
**monthDisplay**: function(year, month, monthTitle) ``'liquid'``
Triggered once when the calendar loads and every time the The calendar will have either 4, 5, or 6 weeks, depending on the month.
calendar's month is changed. ``month`` is zero-based. ``monthTitle`` The height of the weeks will stretch to fill the available height,
contains the new title of the month (ex: "January 2009") as determined by aspectRatio.
**loading**: function(isLoading) ``'variable'``
Triggered with a ``true`` argument when the calendar begins fetching The calendar will have either 4, 5, or 6 weeks, depending on the month.
events via AJAX. Triggered with ``false`` when done. The aspectRatio will NOT be maintained however. Each week will have
a constant height, meaning the calendar will change height month-to-month.
**resize**: function()
Triggered after the calendar has recovered from a resize (due to the window
being resized).
``this`` is set to the main element Event Editing
=============
**dayClick**: function(dayDate) **editable**: Boolean, *Default*: ``false``
Triggered when the user clicks on a day. ``dayDate`` is a Date object with Whether the events on the calendar can be modified, i.e,
it's time set to 00:00:00. if the events will be draggable and resizable.
This can be overridden on a per-event basis with an event's
editable property.
``this`` is set to the TD element of the clicked day. For dragging, the jQuery UI draggable library is required.
For resizing, the jQuery UI resizable library is required.
Both require the jQuery UI core.
**eventRender**: function(calEvent, element) **disableDragging**: Boolean, *Default*: ``false``
Triggered before an element is rendered for the given :ref:`CalEvent <CalEvents>`. Disables all event dragging, even when events are editable
``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 **disableResizing**: Boolean, *Default*: ``false``
element, such as a `qTip <http://craigsworks.com/projects/qtip/docs/>`_ Disables all event resizing, even when events are editable
tooltip effect.
**eventClick**, **eventMouseover**, **eventMouseout**: function(calEvent, jsEvent) **dragOpacity**: Float, *Default*: ``1.0``
Triggered on click/mouseover/mouseout actions for an event. The opacity of an event when it is being dragged.
``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 **dragRevertDuration**: Float, *Default*: ``500``
The time in milliseconds it takes for an event to revert to its
original position after un unsuccessful drag.
For ``eventClick``, return ``false`` to prevent the browser from going to
the event's URL.
**eventDragStart**, **eventDragStop**: function(calEvent, jsEvent, ui) Time & Date Formatting
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 **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.
Here is the default, showing example outputs for each view::
**eventDrop**: function(calEvent, dayDelta, jsEvent, ui) {
Triggered when dragging stops and the event has moved to a *different* day. month: 'MMMM yyyy', // September 2009
``dayDelta`` holds the number of days the event was moved forward (a positive number) week: "MMM d[ yyyy]{ '&#8212;'[ MMM] d yyyy}", // Sep 7 - 13 2009
or backwards (a negative number). day: 'dddd, MMM d, yyyy' // Tuesday, Sep 8, 2009
}
``dayDelta`` is elegant for dealing with multi-day and repeating events. **columnFormat**: String/Object
If updating a remote database, just add the ``dayDelta`` to the start Determines the text that will be displayed on a view's column headers
and end times of all events with the given ``calEvent.id`` 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.
Here is the default, showing example outputs for each view::
{
month: 'ddd', // Mon
week: 'ddd M/d', // Mon 9/7
day: 'dddd M/d' // Monday 9/7
}
**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.
.. _EventSources: Time-text will only be displayed for event objects that have
allDay equal to false.
Event Feeds and 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.
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) {
// format the result into an array of 'CalEvent' objects
// (not seen here)
// then, pass the 'calevent' array to the callback
callback(calevents);
});
}
**eventSources**: array
Similar to the ``events`` options, except one may specify *multiple* sources.
For example, one may specify an array of JSON URL's, an array of custom
functions, an array of hardcoded event arrays, or any combination.
**startParam**: string, default:``"start"``
A GET parameter of this name will be inserted into the URL when fetching
events from a JSON script. The value of this GET parameter will be a UNIX
timestamp denoting the start of the first visible day (inclusive).
**endParam**: string, default:``"end"``
A GET parameter of this name will be inserted into the URL when fetching
events from a JSON script. The value of this GET parameter will be a UNIX
timestamp denoting the end of the last visible day (exclusive).
**cacheParam**: string, default:``"_"``
When using a JSON url, a parameter of this name will
automatically be inserted into the URL to prevent the browser from
caching the response. The value will be the current millisecond time.
The following methods can be called on a FullCalendar that has already
been initialized:
**.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.
**.fullCalendar(** ``'removeEventSource'``, **source)**
Remove an event source. ``source`` must be the original array/string/function.
.. _CalEvents:
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
CalEvent:
**id**: integer/string,
Uniquely identifies the given event. Absolutely essential for multi-day
and repeating events to be dragged and dropped correctly.
**title**: string,
The text on an event's element
**date**: date
Alias for ``start``
**start**: date
A javascript Date object indicating the date/time an event begins.
Events with ambiguous time-of-day should use 00:00:00.
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. This is
an **exclusive** value!!! **Example:** if an event spans two whole days,
``end`` must be the time 00:00:00 of the *third* day.
If an event has an ambiguous end time, ``end`` should be
set to midnight of the next day. This is implied if ``end`` is omitted.
(For convenience with an :ref:`Event Source <EventSources>`).
IETF and ISO8601 strings can be used with an :ref:`Event Source <EventSources>`.
**draggable**: boolean (optional)
Overrides the master ``draggable`` property for this single event.
**showTime**: boolean/ ``"guess"`` (optional)
Overrides the master ``showTime`` property for this single event.
**className**: string/array (optional)
A CSS class (or array of classes) that will be attached to this event's
element.
**source**: array/string/function (automatic)
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.
The following methods can be called on a FullCalendar that has already been
initialized. These methods get/add/update/remove events on the current month.
For JSON and custom event sources, changes are never *permanent* because they
may be overwritten by a refetch. The developer is responsible for updating
any remote databases.
**.fullCalendar(** ``'addEvent'``, **calEvent)**
Add an event to the current month on-the-fly. ``calEvent`` is an object
containing at least an id, title, and start date.
**.fullCalendar(** ``'updateEvent'``, **calEvent)**
Report modifications to the given :ref:`CalEvent <CalEvents>` and redraw.
``calEvent`` must be the *actual CalEvent object*, as retrieved from a
:ref:`Triggered Action <TriggeredActions>` or ``getEventsById`` (see below).
A set of repeating events will all be affected.
**.fullCalendar(** ``'removeEvent'``, **calEventOrId)**
Remove elements belonging to the given :ref:`CalEvent <CalEvents>`. If the
event is repeating, all occurences of the event will be removed. The
second argument may be a CalEvent's ID, or the CalEvent object itself.
**.fullCalendar(** ``'getEventsById'`` , **eventId)**
Returns a list of :ref:`CalEvents <CalEvents>` with the given ID that are
currently being displayed.
Navigation Methods
==================
The following methods may be called on a FullCalendar that has already been
initialized:
**.fullCalendar(** ``'prevMonth'`` **)**
Visits the previous month.
**.fullCalendar(** ``'nextMonth'`` **)**
Visits the next month.
**.fullCalendar(** ``'gotoMonth'``, **year, month)**
Visits an arbitrary month. ``month`` is zero-based (0 is January, 1 is
February, etc).
**.fullCalendar(** ``'today'`` **)**
Visits the current month.
**.fullCalendar(** ``'prevYear'`` **)**
Moves one year back.
**.fullCalendar(** ``'nextYear'`` **)**
Moves one year ahead.
**.fullCalendar(** ``'refresh'`` **)**
Refetch and redraw the events for the current month.
Locale
======
Use the following options to change the calendar's locale:
**weekStart**: integer, default:``0``
The day-of-week each week begins. 0 = Sunday (default),
1 = Monday (for UK users), 2 = Tuesday, etc.
**rightToLeft**: boolean, default:``false``
Displays the calendar right-to-left (for Arabic and Hebrew)
The following *variables* may be reassigned or modified to globally change the
text for months and days:
**$.fullCalendar.monthNames**
Default: ``['January', 'February', 'March', ...]``
**$.fullCalendar.monthAbbrevs**
Default: ``['Jan', 'Feb', 'Mar', ...]``
**$.fullCalendar.dayNames**
Default: ``['Sunday', 'Monday', 'Tuesday', ...]``
**$.fullCalendar.dayAbbrevs**
Default: ``['Sun', 'Mon', 'Tue', ...]``
Notice these variables are attached to the main **$** jQuery object.
The :ref:`GeneralOptions` ``titleFormat`` and ``timeFormat`` may also be of
interest to those wanting to change locale.
Date Parsing and Formatting
===========================
The following utilities are always available. These typically come in handy
when creating a custom event source:
.. _formatDate:
**$.fullCalendar.formatDate(date, format)**
Format a javascript Date object into a string. ``format`` may contain
one or more of the following commands (similar to PHP's date function):
* **Y** - Examples: 1999 or 2003
* **y** - Examples: 99 or 03
* **F** - January through December
* **M** - Jan through Dec
* **n** - 1 through 12 (month)
* **m** - 01 through 12 (month, leading zeros)
* **a** - am or pm
* **A** - AM or PM
* **x** - a or p
* **X** - A or P
* **g** - 1 through 12 (hour)
* **G** - 0 through 23 (hour, military time)
* **h** - 01 through 12 (hour, leading zeros)
* **H** - 00 through 23 (hour, military time and leading zeros)
* **i** - 00 to 59 (minute, leading zeros)
* **c** - 2009-06-07T05:28:21Z (ISO8601)
**$.fullCalendar.parseDate(string)**
Parse a string and return a javascript Date object. The string may be
in ISO8601 format, IETF format, or a UNIX timestamp.
**$.fullCalendar.parseISO8601(string, ignoreTimezone)**
Parse an ISO8601 string into a javascript Date object.
Notice these functions are attached to the main **$** jQuery object.
Google Calendar
===============
To integrate with your Google Calendar, you must first **make your calendar public**:
#. In the Google Calendar interface, locate the "My Calendar" box on the left.
#. Click the arrow next to the calendar you need.
#. A menu will appear. Click "Share this calendar."
#. Check "Make this calendar public."
#. Make sure "Share only my free/busy information" is *unchecked*.
#. Click "Save."
Then, you must obtain your calendar's **XML feed URL**.
#. In the Google Calendar interface, locate the "My Calendar" box on the left
#. Click the arrow next to the calendar you need.
#. A menu will appear. Click "Calendar settings."
#. In the "Calendar Address" section of the screen, click the XML badge.
#. 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::
$('#calendar').fullCalendar({
events: $.fullCalendar.gcalFeed(
"http://www.google.com/calendar/feeds/...", // feed URL
{ className: 'gcal-events' } // optional options
)
});
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``)
See *gcal.html* in the *examples* directory for a complete example.

34
docs/locale.txt Executable file
View file

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

81
docs/methods.txt Executable file
View file

@ -0,0 +1,81 @@
Methods
=======
The folling are a list of methods that can be called on an FullCalendar-initialized
jQuery object:
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.
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)
moveDate .fullCalendar('moveDate', years, months, days)
Moves the calendar forward/backward an arbitrary amount of time
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.
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('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.
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.
removeEventSource .fullCalendar('removeEventSource', source)
Remove an event source. ``source`` must be a reference to the
original array/string/function.
rerenderEvents .fullCalendar('rerenderEvents')
Rerenders all events on the screen.
refetchEvents .fullCalendar('refetchEvents')
Refetches events from all event sources and rerenders them on the screen.

7
docs/templates/layout.html vendored
View file

@ -3,13 +3,6 @@
<? fullcalendar_docs_nav() ?> <? fullcalendar_docs_nav() ?>
<? begin_content() ?> <? begin_content() ?>
<div id='toc'>
<h1>Table of Contents</h1>
{{ toc }}
</div>
<div class='clear'></div>
{% block body %}{% endblock %} {% block body %}{% endblock %}
<? end_content() ?> <? end_content() ?>

24
docs/theming.txt Executable file
View file

@ -0,0 +1,24 @@
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.
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
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:
{
prev: 'circle-triangle-w',
next: 'circle-triangle-e'
}

121
docs/triggered-actions.txt Executable file
View file

@ -0,0 +1,121 @@
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).
**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.
**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``
**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
===========
The final parameter of every callback is a *view* object. It has the following properties:
**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.
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``).

24
src/main.js
View file

@ -26,7 +26,7 @@ var defaults = {
eventTimeFormat: 'h(:mm)t', eventTimeFormat: 'h(:mm)t',
titleFormat: { titleFormat: {
month: 'MMMM yyyy', month: 'MMMM yyyy',
week: "MMM d[ yyyy]{ '&#8212;' [MMM ]d yyyy}", week: "MMM d[ yyyy]{ '&#8212;'[ MMM] d yyyy}",
day: 'dddd, MMM d, yyyy' day: 'dddd, MMM d, yyyy'
}, },
columnFormat: { columnFormat: {
@ -208,7 +208,7 @@ $.fn.fullCalendar = function(options) {
header.find('h2.fc-header-title').html(view.title); header.find('h2.fc-header-title').html(view.title);
} }
view.eventsDirty = false; view.eventsDirty = false;
view.trigger('viewDisplay', _element, date); view.trigger('viewDisplay', _element);
} }
function eventsDirtyExcept(exceptView) { function eventsDirtyExcept(exceptView) {
@ -294,14 +294,14 @@ $.fn.fullCalendar = function(options) {
var loadingLevel = 0; var loadingLevel = 0;
function pushLoading() { function pushLoading() {
if (!loadingLevel++ && options.loading) { if (!loadingLevel++) {
options.loading(true); view.trigger('loading', _element, true);
} }
} }
function popLoading() { function popLoading() {
if (!--loadingLevel && options.loading) { if (!--loadingLevel) {
options.loading(false); view.trigger('loading', _element, false);
} }
} }
@ -329,6 +329,12 @@ $.fn.fullCalendar = function(options) {
render(); render();
}, },
gotoDate: function() {
},
moveDate: function() {
},
// //
// Event Rendering // Event Rendering
// //
@ -384,6 +390,9 @@ $.fn.fullCalendar = function(options) {
} }
}, },
rerender: function() {
},
clientEventsByID: eventsByID, clientEventsByID: eventsByID,
removeEvents: removeEvents, removeEvents: removeEvents,
@ -407,6 +416,9 @@ $.fn.fullCalendar = function(options) {
return e.source != source; return e.source != source;
}); });
eventsChanged(); eventsChanged();
},
refetch: function() {
} }
}; };

2
src/view.js
View file

@ -28,7 +28,7 @@ var viewMethods = {
trigger: function(name, thisObj) { trigger: function(name, thisObj) {
if (this.options[name]) { if (this.options[name]) {
return this.options[name].apply(thisObj, Array.prototype.slice.call(arguments, 2).concat([this])); return this.options[name].apply(thisObj || this, Array.prototype.slice.call(arguments, 2).concat([this]));
} }
}, },