From 2841a62e743465f89c2a737fd59b3797ffa5dd59 Mon Sep 17 00:00:00 2001 From: Adam Shaw Date: Mon, 14 Sep 2009 03:36:27 +0000 Subject: [PATCH] more doc changes --- docs/Makefile | 2 +- docs/date-utils.txt | 94 ++++++++-------- docs/events-and-sources.txt | 187 ++++++++++++++++---------------- docs/google-calendar.txt | 8 +- docs/index.txt | 125 +++++++++++---------- docs/locale.txt | 30 ++--- docs/methods.txt | 127 +++++++++++----------- docs/theming.txt | 29 ++--- docs/triggered-actions.txt | 211 ++++++++++++++++++------------------ 9 files changed, 409 insertions(+), 404 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 77fb699..1fee6dd 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -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." diff --git a/docs/date-utils.txt b/docs/date-utils.txt index 1917dde..b970dd6 100755 --- a/docs/date-utils.txt +++ b/docs/date-utils.txt @@ -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` -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. \ No newline at end of file diff --git a/docs/events-and-sources.txt b/docs/events-and-sources.txt index 1b81f04..e971f19 100755 --- a/docs/events-and-sources.txt +++ b/docs/events-and-sources.txt @@ -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 ` can be used to hardcode events into 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) { - 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) { + // 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 `. Here are the properties of a +standardized currency used in :ref:`event-sources`. 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. +**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 `, 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 `. +**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 `, 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 `. - **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. \ No newline at end of file diff --git a/docs/google-calendar.txt b/docs/google-calendar.txt index 64df267..86c8e79 100755 --- a/docs/google-calendar.txt +++ b/docs/google-calendar.txt @@ -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. \ No newline at end of file diff --git a/docs/index.txt b/docs/index.txt index 5040cfd..bb278c2 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -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` 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 ` + ``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 `_ library is required. + + For resizing, the `jQuery UI 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' `' 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]{ '—'[ 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' ` 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' ` 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 `_ + +**basicWeek** - `see example `_ + +**basicDay** - `see example `_ \ No newline at end of file diff --git a/docs/locale.txt b/docs/locale.txt index ce547a0..e1bfbf3 100755 --- a/docs/locale.txt +++ b/docs/locale.txt @@ -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: '◄', - next: '►', + prev: '◄', // left triangle + next: '►', // right triangle today: 'today', month: 'month', week: 'week', diff --git a/docs/methods.txt b/docs/methods.txt index 852e6c9..19c5c30 100755 --- a/docs/methods.txt +++ b/docs/methods.txt @@ -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 `. 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 ` retrieved from a + :ref:`Triggered Action` 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 ` ID, all events with + the same ID will be removed. + + The second argument may also be a filter function that accepts + one :ref:`CalEvent ` argument and returns ``true`` or ``false`` about + whether it should be removed. + +**clientEvents** - .fullCalendar('clientEvents', *[idOrFilter]*) + This method will return :ref:`CalEvents ` 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 ` ID, all events with the + same ID will be returned. + + The second argument may also be a filter function that accepts + one :ref:`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 `. ``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 `. ``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. - \ No newline at end of file +**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/theming.txt b/docs/theming.txt index 871e976..a542da1 100755 --- a/docs/theming.txt +++ b/docs/theming.txt @@ -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 `_. -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' - } \ No newline at end of file + { + 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 index 1bce47c..49e368d 100755 --- a/docs/triggered-actions.txt +++ b/docs/triggered-actions.txt @@ -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 `). - **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 `. - ``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`` +**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 `. + ``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: 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``).