diff --git a/docs/date-utils.txt b/docs/date-utils.txt new file mode 100755 index 0000000..1917dde --- /dev/null +++ b/docs/date-utils.txt @@ -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. + \ No newline at end of file diff --git a/docs/events-and-sources.txt b/docs/events-and-sources.txt new file mode 100755 index 0000000..1b81f04 --- /dev/null +++ b/docs/events-and-sources.txt @@ -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 ` 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 `. 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 `. 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 `, 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 `. + + **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... diff --git a/docs/google-calendar.txt b/docs/google-calendar.txt new file mode 100755 index 0000000..64df267 --- /dev/null +++ b/docs/google-calendar.txt @@ -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. \ No newline at end of file diff --git a/docs/index.txt b/docs/index.txt index 09f7b37..5040cfd 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -1,467 +1,152 @@ -Main Usage -========== +Usage +===== The following code initializes a FullCalendar within an element of ID 'calendar':: - $('#calendar').fullCalendar({ - - // put your options here - - }) - - - -.. _GeneralOptions: - -General Options + $('#calendar').fullCalendar({ + + // put your options here + + }) + + +Available Views =============== - **year**, **month**: integers - 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`` - Determines if all events on the calendar can be dragged & dropped. If - ``true``, requires `jQuery UI `_ core and draggables. - Can be overridden on a per-event basis with the ``draggable`` property of - each :ref:`CalEvent `. - - **fixedWeeks**: boolean, default:``true`` - 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`` - Determines whether a title such as "January 2009" will be displayed at the - top of the calendar. - - **titleFormat**: string, default:``"F Y"`` - A string defining the format of the title above the calendar. The default - "F Y" creates strings such as "January 2009". Consult the - :ref:`$.fullCalendar.formatDate ` documentation for a full - list of commands. - - **buttons**: boolean/hash, default:``true`` - ``true`` will display a previous-month, next-month, and "today" button. - The "today" button will only be visible for months other than the current. - - ``false`` will display absolutely no buttons. - - An object hash can be provided to display only *certain* buttons. The hash - can have the following properties:: - - { - today: bool/string, - 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 - display the button with some default text. A *string* value will display - the button *and* customize its text. - - **showTime**: boolean/ ``"guess"``, default:``"guess"`` - Determines if times will be displayed before each event's title. - ``"guess"`` displays times only for events with non-zero start or end times. - - **timeFormat**: string, default: ``"gx"`` - A string defining the format of dislayed event times. The default "gx" - creates a string such as "9a". Consult the - :ref:`$.fullCalendar.formatDate ` - documentation for a full list of commands. - - **eventDragOpacity**: float - The opacity of an event element while it is being dragged (0.0 - 1.0) - - **eventRevertDuration**: integer - Controls the duration (in milliseconds) of the animation of an event - snapping back into place. - - - -.. _TriggeredActions: - -Triggered Actions -================= +**month** - see example -The following options are *functions* that get executed every time something -special happens: - - **monthDisplay**: function(year, month, monthTitle) - Triggered once when the calendar loads and every time the - calendar's month is changed. ``month`` is zero-based. ``monthTitle`` - contains the new title of the month (ex: "January 2009") - - **loading**: function(isLoading) - Triggered with a ``true`` argument when the calendar begins fetching - events via AJAX. Triggered with ``false`` when done. - - **resize**: function() - Triggered after the calendar has recovered from a resize (due to the window - being resized). - - ``this`` is set to the main element - - **dayClick**: function(dayDate) - 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) - Triggered before an element is rendered for the given :ref:`CalEvent `. - ``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 `_ - tooltip effect. - - **eventClick**, **eventMouseover**, **eventMouseout**: function(calEvent, jsEvent) - 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) - 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, jsEvent, ui) - 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). - - ``dayDelta`` is elegant for dealing with multi-day and repeating events. - If updating a remote database, just add the ``dayDelta`` to the start - and end times of all events with the given ``calEvent.id`` - +**basicWeek** - see example + +**basicDay** - see example -.. _EventSources: - -Event Feeds and Sources -======================= +Basic Display Options +===================== -The following options determine *how* events get on the calendar: - - **events**: array/string/function - An array of :ref:`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 `. 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: +**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) + + If ommitted, the calendar starts on the current date. -CalEvent Objects -================ +**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: + + ``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 + + ``next`` + button for moving the calendar forward one month/week/day, + depending on the current view + + *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. + + 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. -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 `. Here are the properties of a -CalEvent: +**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). - **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 `, 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 `). - - IETF and ISO8601 strings can be used with an :ref:`Event Source `. - - **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. +**weekMode**: String, *Default*: ``'fixed'`` + Determines the number of weeks displayed in a month view. + Also determines each week's height. Available options: + + ``'fixed'`` + The calendar will always be 6 weeks tall. + 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. + + ``'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. + + +Event Editing +============= - **.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 ` and redraw. - ``calEvent`` must be the *actual CalEvent object*, as retrieved from a - :ref:`Triggered Action ` or ``getEventsById`` (see below). - A set of repeating events will all be affected. - - **.fullCalendar(** ``'removeEvent'``, **calEventOrId)** - Remove elements belonging to the given :ref:`CalEvent `. 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 ` with the given ID that are - currently being displayed. - - - - -Navigation Methods -================== +**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. + + For dragging, the jQuery UI draggable library is required. + For resizing, the jQuery UI resizable library is required. + Both require the jQuery UI core. + +**disableDragging**: Boolean, *Default*: ``false`` + Disables all event dragging, even when events are editable -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 -====== +**disableResizing**: Boolean, *Default*: ``false`` + Disables all event resizing, even when events are editable + +**dragOpacity**: Float, *Default*: ``1.0`` + The opacity of an event when it is being dragged. -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. - - +**dragRevertDuration**: Float, *Default*: ``500`` + The time in milliseconds it takes for an event to revert to its + original position after un unsuccessful drag. + + +Time & Date Formatting +====================== -Date Parsing and 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. + Here is the default, showing example outputs for each view:: + + { + month: 'MMMM yyyy', // September 2009 + week: "MMM d[ yyyy]{ '—'[ MMM] d yyyy}", // Sep 7 - 13 2009 + day: 'dddd, MMM d, yyyy' // Tuesday, Sep 8, 2009 + } -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. +**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. + 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. + + Time-text will only be displayed for event objects that have + allDay equal to false. + \ No newline at end of file diff --git a/docs/locale.txt b/docs/locale.txt new file mode 100755 index 0000000..ce547a0 --- /dev/null +++ b/docs/locale.txt @@ -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: '◄', + next: '►', + today: 'today', + month: 'month', + week: 'week', + day: 'day' + } diff --git a/docs/methods.txt b/docs/methods.txt new file mode 100755 index 0000000..852e6c9 --- /dev/null +++ b/docs/methods.txt @@ -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. + \ No newline at end of file diff --git a/docs/templates/layout.html b/docs/templates/layout.html index f538fca..f29f86b 100644 --- a/docs/templates/layout.html +++ b/docs/templates/layout.html @@ -3,13 +3,6 @@ -
-

Table of Contents

-{{ toc }} -
- -
- {% block body %}{% endblock %} diff --git a/docs/theming.txt b/docs/theming.txt new file mode 100755 index 0000000..871e976 --- /dev/null +++ b/docs/theming.txt @@ -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' + } \ No newline at end of file diff --git a/docs/triggered-actions.txt b/docs/triggered-actions.txt new file mode 100755 index 0000000..1bce47c --- /dev/null +++ b/docs/triggered-actions.txt @@ -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 `. + ``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 `_ + 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``). diff --git a/src/main.js b/src/main.js index 03a1953..851b9a6 100755 --- a/src/main.js +++ b/src/main.js @@ -26,7 +26,7 @@ var defaults = { eventTimeFormat: 'h(:mm)t', titleFormat: { month: 'MMMM yyyy', - week: "MMM d[ yyyy]{ '—' [MMM ]d yyyy}", + week: "MMM d[ yyyy]{ '—'[ MMM] d yyyy}", day: 'dddd, MMM d, yyyy' }, columnFormat: { @@ -208,7 +208,7 @@ $.fn.fullCalendar = function(options) { header.find('h2.fc-header-title').html(view.title); } view.eventsDirty = false; - view.trigger('viewDisplay', _element, date); + view.trigger('viewDisplay', _element); } function eventsDirtyExcept(exceptView) { @@ -294,14 +294,14 @@ $.fn.fullCalendar = function(options) { var loadingLevel = 0; function pushLoading() { - if (!loadingLevel++ && options.loading) { - options.loading(true); + if (!loadingLevel++) { + view.trigger('loading', _element, true); } } function popLoading() { - if (!--loadingLevel && options.loading) { - options.loading(false); + if (!--loadingLevel) { + view.trigger('loading', _element, false); } } @@ -329,6 +329,12 @@ $.fn.fullCalendar = function(options) { render(); }, + gotoDate: function() { + }, + + moveDate: function() { + }, + // // Event Rendering // @@ -384,6 +390,9 @@ $.fn.fullCalendar = function(options) { } }, + rerender: function() { + }, + clientEventsByID: eventsByID, removeEvents: removeEvents, @@ -407,6 +416,9 @@ $.fn.fullCalendar = function(options) { return e.source != source; }); eventsChanged(); + }, + + refetch: function() { } }; diff --git a/src/view.js b/src/view.js index 30e625e..b52580c 100755 --- a/src/view.js +++ b/src/view.js @@ -28,7 +28,7 @@ var viewMethods = { trigger: function(name, thisObj) { 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])); } },