fullcalendar/docs/index.txt

.. highlight:: javascript

Usage
=====

.. code-block:: javascript

   $('#myCalendar').fullCalendar({
      // initializes a calendar
      // see options, data provider, and triggered events below
   });
   
   $('#myCalendar').fullCalendar('nextMonth');    // move ahead one month
   
   $('#myCalendar').fullCalendar('currentMonth'); // go to current month
   
   $('#myCalendar').fullCalendar('prevMonth');    // move back one month
   
   $('#myCalendar').fullCalendar('gotoMonth', year, month);
      // go to an arbitrary month. 'month' is zero-based
      
   $('#myCalender').fullCalendar('refresh');
      // re-fetch events for the current month
      
   
Options
=======

   **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 <http://jqueryui.com/>`_ core and draggables.
      Can be overridden on a per-event basis with the ``draggable`` property of
      each :ref:`CalEvent <CalEvent>` object.
   
   **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.
   
   **buttons**: boolean/hash, default:``true``
      Determines whether navigation buttons will be displayed at the top of the
      calendar. A hash with keys 'today', 'prev', and 'next' will determine if
      each individual button is displayed. Strings can be provided to change
      each button's text.
      
   **showTime**: boolean/ ``"guess"``, default:``"guess"``
      Determines if times such as "8a" or "1p" will be displayed before each
      event's title. ``"guess"`` displays times only for events with non-zero
      start or end times.
   
   **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.
      

.. _EventDataProvider:
      
Event Data Provider
===================
      
   **events**: array/string/function
      An array of :ref:`CalEvent` can be used to hardcode events into the
      calendar.
      
      Or, a URL can be provided. This URL should return JSON for an array of
      :ref:`CalEvent`. GET parameters, determined by the ``startParam`` and
      ``endParam`` options, will be inserted into the URL. These parameters
      indicate the UNIX timestamp of the start of the first visible day
      (inclusive) and the end of the last visible day (exclusive).
      
      Or, a function can be provided for custom fetching. The function is
      queried every time event data is needed. The function is passed a ``start``
      Date object, an ``end`` Date object, and a function to be called when
      fetching is complete. Here is the general form::
      
         events: function(start, end, callback) {
         
            // 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);
               
               });
            
         }
         
   **startParam**: string, default:``"start"``
      A GET parameter of this name will be inserted into the URL when fetching
      events from a JSON script (when ``event`` is a URL string). 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 (when ``event`` is a URL string). The value
      of this GET parameter will be a UNIX timestamp denoting the end of the
      last visible day (exclusive).
         
      
.. _TriggeredEvents:
      
Triggered Events
================
   
   **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.
      
   **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 ``calEvent``.
      ``element`` is the jQuery element that will be used by default. You can modify
      this element or return a brand new element that will be used instead.
      
   **eventClick**, **eventMouseover**, **eventMouseout**: function(calEvent, domEvent)
      Triggered on click/mouseover/mouseout actions for an event.
      ``calEvent`` holds that event's information (date, title, etc).
      ``domEvent`` holds the native DOM event (with information about click position, etc).
      
      ``this`` is set to the event's TABLE element
      
      For ``eventClick``, return ``false`` to prevent the browser from going to
      calEvent's URL.
      
   **eventDragStart**, **eventDragStop**: function(calEvent, domEvent, 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).
      ``domEvent`` holds the native DOM event (with information about click position, etc).
      ``ui`` holds the jQuery UI object.
      
      ``this`` is set to the event's TABLE element
      
   **eventDrop**: function(calEvent, dayDelta, domEvent, 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``
      
      
.. _CalEvent:

CalEvent Objects
================

A ``CalEvent`` is a data structure that frequents FullCalendar's API. It is
used when a custom event-fetcher needs to report to the :ref:`EventDataProvider`.
It is also used in various :ref:`TriggeredEvents`. 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.
      
      When reporting to the :ref:`EventDataProvider`, 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
      (exclusively). 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 the :ref:`EventDataProvider`).
      
      IETF and ISO8601 strings can be used for the :ref:`EventDataProvider`.
      
   **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.
      
When giving events to the :ref:`EventDataProvider`, one can include other
properties beyond the ones listed. This is useful if you want to earmark your
events with additional data to be retrieved later during a
:ref:`Triggered Event <TriggeredEvents>`.


Extras
======

FullCalendar provides some extra date utilities\:

   **$.parseISO8601(string, ignoreTimezone)**
      Parses an ISO8601 string and returns a ``Date`` object
      
   **$.ISO8601String(date)**
      Takes a ``Date`` object and returns an ISO8601 string