fullcalendar/docs/index.txt

Usage
=====

The following code initializes a FullCalendar within an element::

	$('#calendar').fullCalendar({
		
		// put your options here
		
	})
	
.. _BasicOptions:

Basic Options
=============

**year, month, date**: Integers
	The initial year/month/date when the calendar loads.
	``month`` is 0-based, meaning January=0, February=1, etc.
	If ommitted, the calendar starts on the current date.
	
**defaultView**: String, *Default*: ``'month'``
	The initial view when the calendar loads. Any of the :ref:`available-views`.

**header**: Object/``false``, *Default*: ``{ left:'title', center:'', right:'today 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
		
		``next``
			button for moving the calendar forward one month/week/day
			
		``prevYear``
			button for moving the calendar back on year
			
		``nextYear``
			button for moving the calendar forward one year
			
		``today``
			button for moving the calendar to the current month/week/day
			
		*a blank space*
			visual gap between buttons/text
		
		*a view name*
			button that will switch the calendar to any of the
			:ref:`available-views`
	
	Specifying an empty string for a property will cause it display no text/buttons.
	
**buttonText**: Object
	Text that will be displayed on buttons of the header. Default::
	
		{
			prev: ' ◄ ',      // left triangle
			next: ' ► ',      // right triangle
			prevYear: '&nbsp;&lt;&lt;&nbsp;', // <<
			nextYear: '&nbsp;&gt;&gt;&nbsp;', // >>
			today: 'today',
			month: 'month',
			week: 'week',
			day: 'day'
		}

**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).
	
**height**: Integer
	Will make the entire calendar (including header) a pixel height.
	You may change this after initialization with :ref:`Option Setters<option-getters-setters>`.
	
**contentHeight**: Integer
	Will make the calendar's content area a pixel height.
	You may change this after initialization with :ref:`Option Setters<option-getters-setters>`.
	
.. _allDayDefault:

**allDayDefault**: Boolean, *Default*: ``true``
	Determines the default value for each :ref:`CalEvent's <CalEvent>` ``allDay`` property,
	when it is unspecified.
	
**weekends**: Boolean, *Default*: ``true``
	Whether to include Saturday/Sunday columns in any of the views.

**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's height will change month-to-month.
	
**allDaySlot**: Boolean, *Default*: ``true``
	In the agenda views, determines if the "all-day" slot is displayed at the top
	of the calendar. When hidden with ``false``, all-day events will not be displayed
	in agenda views.
	
**allDayText**: String, *Default*: ``'all-day'``
	In the agenda views, the text titling the "all-day" slot at the top of the calendar.
	
**firstHour**: Integer, *Default*: 6
	In the agenda views, determines the first hour that will be visible in the
	scroll pane. Values must be from 0-23, where 0=midnight, 1=1am, etc.
	
**slotMinutes**: Integer, *Default*: 30
	In the agenda views, the frequency for displaying time slots, in minutes.
	
**defaultEventMinutes**: Integer, *Default*: 120
	In the agenda views, when a :ref:`CalEvent <CalEvent>` has an unspecified end date,
	determines the length (in minutes) the event appears to be.
	
**minTime**: Integer/String, *Default*: ``0``
	In the agenda views, determines the first hour/time that will be displayed, even when
	the scollbars have been scrolled all the way up. This can be a number like ``5`` (which
	means 5am), a string like ``'5:30'`` (which means 5:30am) or a string like ``'5:30am'``.
	
**maxTime**: Integer/String, *Default*: ``24``
	In the agenda views, determines the last hour/time (exclusively) that will be displayed, even when
	the scrollbars have been scrolled all the way down. This can be a number like ``22`` (which
	means 10pm), a string like ``'22:30'`` (which means 10:30pm) or a string like ``'10:30pm'``.
	
	
Event Editing
=============

**editable**: Boolean, *Default*: ``false``
	Determines whether the events on the calendar can be modified, i.e,
	if the events will be *draggable* and *resizable*.
	This can be overridden on a per-event basis with a :ref:`CalEvent's <CalEvent>`
	``editable`` property.
	
	For dragging, the `jQuery UI draggable <http://jqueryui.com/demos/draggable/>`_ library is required.
	
	For resizing, the `jQuery UI resizable <http://jqueryui.com/demos/resizable/>`_ library is required.
	
**disableDragging**: Boolean, *Default*: ``false``
	Disables all event dragging, even when events are editable.

**disableResizing**: Boolean, *Default*: ``false``
	Disables all event resizing, even when events are editable.

**dragRevertDuration**: Float, *Default*: ``500``
	The time in milliseconds it takes for an event to revert to its
	original position after an unsuccessful drag.
	
**dragOpacity**: Float
	The opacity of an event when it is being dragged. Values range
	from 0.0 to 1.0.
	
	Specify a single number to affect all views, or a
	:ref:`ViewHash` to target specific views. Here is the default
	(a View Hash)::
	
		{	
			// for agendaWeek and agendaDay
			agenda: .5,
			
			// for all other views
			'': 1.0
		}
	
	
Time & Date Formatting
======================

**titleFormat**: String/Object
	Determines the text that will be displayed in the header's title
	using the :ref:`formatDates <formatDates>` format.
	
	A single string will set the title format for *all* views.
	A :ref:`ViewHash` may be provided to target specific views.
	Here is the default (a View Hash), showing example output::
	
		{
			month: 'MMMM yyyy',                            // September 2009
			week: "MMM d[ yyyy]{ '&#8212;'[ MMM] d yyyy}", // Sep 7 - 13 2009
			day: 'dddd, MMM d, yyyy'                       // Tuesday, Sep 8, 2009
		}

**columnFormat**: String/Object
	Determines the text that will be displayed on the calendar's column headings
	using the :ref:`formatDates <formatDates>` format.
	
	A single string will set the title format for *all* views.
	A :ref:`ViewHash` may be provided to target specific views.
	Here is the default (a View Hash), showing example output::
	
		{
			month: 'ddd',    // Mon
			week: 'ddd M/d', // Mon 9/7
			day: 'dddd M/d'  // Monday 9/7
		}

**timeFormat**: String/Object
	Determines the time-text that will be displayed on an event
	using the :ref:`formatDates <formatDates>` format.
	
	Time-text will only be displayed for :ref:`CalEvents <CalEvent>`
	that have ``allDay`` equal to ``false``.
	
	A single string will change the time-text for applicable events in *all* views.
	A :ref:`ViewHash` may be provided to target specific views.
	Here is the default (a View Hash), showing example output::
	
		{	
			// for agendaWeek and agendaDay
			agenda: 'h:mm{ - h:mm}', // 5:00 - 6:30
			
			// for all other views
			'': 'h(:mm)t'            // 7p
		}
	
**axisFormat**: String, *Default*: ``h(:mm)tt``
	Determines the time-text that will be displayed on the left vertical axis
	of the agenda views.
	
	
.. _available-views:
	
Available Views
===============

**month** - `see example <../../media/fullcalendar-views/month.html>`_

**basicWeek** - `see example <../../media/fullcalendar-views/basicWeek.html>`_

**basicDay** - `see example <../../media/fullcalendar-views/basicDay.html>`_

**agendaWeek** - `see example <../../media/fullcalendar-views/agendaWeek.html>`_

**agendaDay** - `see example <../../media/fullcalendar-views/agendaDay.html>`_


.. _ViewHash:

View Hash
=========

A "View Hash" is an object that specifies options for specific calendar views.
It can contain any of the following properties::

	{
		month:      // month view
		week:       // basicWeek & agendaWeek views
		day:        // basicDay & agendaDay views
		
		agenda:     // agendaDay & agendaWeek views
		agendaDay:  // agendaDay view
		agendaWeek: // agendaWeek view
		
		basic:      // basicWeek & basicDay views
		basicWeek:  // basicWeek view
		basicDay:   // basicDay view
		
		'':         // (an empty string) when no other properties match
	}
	
Currently the only options that support View Hashes are
``dragOpacity``, ``titleFormat``, ``columnFormat``, and ``timeFormat``.