fullcalendar/docs/index.txt

282 lines
9.1 KiB
Plaintext

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``.