diff --git a/display/buttonIcons.txt b/display/buttonIcons.txt index 7053a24..fb6d371 100644 --- a/display/buttonIcons.txt +++ b/display/buttonIcons.txt @@ -20,3 +20,6 @@ The icon strings determine the CSS class that will be used on the button. For ex string `'circle-triangle-w'` will result in the class `'ui-icon-triangle-w'`. If a button does not have an entry, it falls back to using [buttonText](../text/buttonText). + +If you are using a jQuery UI theme and would prefer not to display any icons and would rather +use `buttonText` instead, you can set the `buttonIcons` option to `false`. diff --git a/dropping/drop.txt b/dropping/drop.txt index 6280b65..ccb10d4 100644 --- a/dropping/drop.txt +++ b/dropping/drop.txt @@ -20,4 +20,4 @@ function( *date*, *allDay*, *jsEvent*, *ui* ) { } `this` holds the DOM element that has been dropped. To see this callback function in action, view the [droppable]() article or look at -[this example](/js/fullcalendar/examples/external-dragging.html). +[this example](/js/fullcalendar/demos/external-dragging.html). diff --git a/dropping/droppable.txt b/dropping/droppable.txt index 0ddbd56..f0ef48b 100644 --- a/dropping/droppable.txt +++ b/dropping/droppable.txt @@ -36,7 +36,7 @@ dragged onto the calendar. While the `droppable` option deals with generic jQuery UI draggables and is not specifically tailored to adding events, it is possible to achieve this with a few lines of code. Follow the **external-dragging.html** example in FullCalendar's download. You can also -view the [example online](/js/fullcalendar/examples/external-dragging.html). +view the [example online](/js/fullcalendar-1.5.2/demos/external-dragging.html). In short, you must call [renderEvent](../event_rendering/renderEvent) yourself in the [drop]() callback. diff --git a/event_data/Event_Object.txt b/event_data/Event_Object.txt index d66dc24..41bb91f 100644 --- a/event_data/Event_Object.txt +++ b/event_data/Event_Object.txt @@ -2,65 +2,183 @@ Event Object ============ -A standard object that FullCalendar uses to store information about a calendar event. +A standard JavaScript object that FullCalendar uses to store information about a calendar event. +Here are its properties: -An Event Object has a number of properties. When passing new Event Objects to -`events` and `eventSources`, only the `title` and `start` properties are required. -Here is the full list of properties: -**id**: String/Integer (optional) -: Uniquely identifies the given event. Different instances of repeating events should all have the same `id`. - -**title**: String -: The text on an event's element + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+id + +String/Integer. Optional -**allDay**: `true` or `false` (optional) -: Whether an event occurs at a specific time-of-day. This property affects whether an event's time is shown. - Also, in the agenda views, determines if it is displayed in the "all-day" section. - - **Don't include quotes** around your `true`/`false`. This value is not a string! - - When specifying Event Objects for `events` or `eventSources`, - omitting this property will make it inherit from - [allDayDefault](), which is normally `false`. - -**start**: Date -: A JavaScript Date object indicating the date/time an event begins. +Uniquely identifies the given event. Different instances of repeating events should all have the same `id`. +
+title + +String. *Required*. - When specifying Event Objects for `events` or `eventSources`, - you may specify 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 a UNIX timestamp. - -**end**: Date (optional) -: A Javascript Date object indicating the date/time an event ends. - As with `start`, you may specify it in IETF, ISO8601, or UNIX timestamp format. - - **If an event is all-day**... +The text on an event's element +
+allDay + +`true` or `false`. Optional. - the end date is inclusive. This means an event with `start` Nov 10 and - `end` Nov 12 will span 3 days on the calendar. +Whether an event occurs at a specific time-of-day. This property affects whether an event's time is shown. +Also, in the agenda views, determines if it is displayed in the "all-day" section. - **If an event is NOT all-day**... +**Don't include quotes** around your `true`/`false`. This value is not a string! - the end date is exclusive. This is only a gotcha when your `end` has time 00:00. - It means your event ends on midnight, and it will not span through the next day. - -**url**: String (optional) -: A URL that will be visited when this event is clicked by the user. - For more information on controlling this behavior, see the [eventClick](../mouse/eventClick) callback. - -**className**: String/Array (optional) -: A CSS class (or array of classes) that will be attached to this event's element. +When specifying Event Objects for `events` or `eventSources`, +omitting this property will make it inherit from +[allDayDefault](), which is normally `true`. +
+start + +Date. *Required*. -**editable**: `true` or `false` (optional) -: Overrides the master [editable](../event_ui/editable) option for this single event. +The date/time an event begins. -**source**: Array/String/Function (automatically populated) -: A reference to the event source (as specified in `events` or `eventSources`) - that this event came from. - - Do not worry about populating this value, FullCalendar will do this automatically. - +When specifying Event Objects for `events` or `eventSources`, +you may specify 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 a UNIX timestamp. +
+end + +Date. Optional. + +The date/time an event ends. + +As with `start`, you may specify it in IETF, ISO8601, or UNIX timestamp format. + +**If an event is all-day**... + +the end date is inclusive. This means an event with `start` Nov 10 and +`end` Nov 12 will span 3 days on the calendar. + +**If an event is NOT all-day**... + +the end date is exclusive. This is only a gotcha when your `end` has time 00:00. +It means your event ends on midnight, and it will not span through the next day. +
+url + +String. Optional. + +A URL that will be visited when this event is clicked by the user. +For more information on controlling this behavior, see the [eventClick](../mouse/eventClick) callback. +
+className + +String/Array. Optional. + +A CSS class (or array of classes) that will be attached to this event's element. +
+editable + +`true` or `false`. Optional. + +Overrides the master [editable](../event_ui/editable) option for this single event. +
+source + +[Event Source Object](). Automatically populated. + +A reference to the event source that this event came from. +
+New options have been added in version 1.5 to change an event's colors: +
+color + +Sets an event's background *and* border color just like +the calendar-wide [eventColor](../event_rendering/eventColor) option. +
+backgroundColor + +Sets an event's background color just like +the calendar-wide [eventBackgroundColor](../event_rendering/eventBackgroundColor) option. +
+borderColor + +Sets an event's border color just like the +the calendar-wide [eventBorderColor](../event_rendering/eventBorderColor) option. +
+textColor + +Sets an event's text color just like +the calendar-wide [eventTextColor](../event_rendering/eventTextColor) option. +
+ + +Non-standard Fields +------------------- In addition to the fields above, you may also include your own non-standard fields in each Event Object. FullCalendar will not modify or delete these fields. diff --git a/event_data/Event_Source_Object.txt b/event_data/Event_Source_Object.txt new file mode 100644 index 0000000..35eed1c --- /dev/null +++ b/event_data/Event_Source_Object.txt @@ -0,0 +1,131 @@ + +Event Source Object +=================== + +An "event source" is anything that provides FullCalendar with data about +events. It can be a simple array, +an event-generating function that you define, +a URL to a json feed, +or a Google Calendar feed. + +Since version 1.5, Event Objects can have "options" associated with them. +However, before you can start specifying options, you must write an Event Object in its +*extended form*. It must be a traditional JavaScript object with properties. +Here are the extended forms for each type of Event Source: + +Array of events: + + { + events: [ + { + title: 'Event1', + start: '2011-04-04' + }, + { + title: 'Event2', + start: '2011-05-05' + } + // etc... + ], + color: 'yellow', // an option! + textColor: 'black' // an option! + } + +Event-generating function: + + { + events: function(start, end, callback) { + // ... + }, + color: 'yellow', // an option! + textColor: 'black' // an option! + } + +JSON feed: + + { + url: '/myfeed.php', + color: 'yellow', // an option! + textColor: 'black' // an option! + } + +Google Calendar feed: + + { + url: 'http://www.google.com/your_feed_url/', + color: 'yellow', // an option! + textColor: 'black' // an option! + } + +Event Source Options +-------------------- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+color + +Sets every Event Object's `color` for this source. +
+backgroundColor + +Sets every Event Object's `backgroundColor` for this source. +
+borderColor + +Sets every Event Object's `borderColor` for this source. +
+textColor + +Sets every Event Object's `textColor` for this source. +
+className + +Sets every Event Object's `className` for this source. +
+editable + +Sets every Event Object's `editable` for this source. +
+allDayDefault + +Sets the [allDayDefault]() option, but only for this source. +
+ignoreTimezone + +Sets the [ignoreTimezone]() option, but only for this source. +
+ +**For JSON feeds**, [there are additional options you can set](events_json_feed#options). + diff --git a/event_data/eventSources.txt b/event_data/eventSources.txt index 09713ab..475e184 100644 --- a/event_data/eventSources.txt +++ b/event_data/eventSources.txt @@ -9,7 +9,10 @@ Array This option is used instead of the `events` option. -It can take an Array of Arrays/Functions/URLs (anything that the `events` option would take). + +You can put any number of [event arrays](events_array), [functions](events_function), +[JSON feed URLs](events_json_feed), or full-out [Event Source Objects](Event_Source_Object) +into the `eventSources` array. Here is an example calendar that displays two [JSON feeds](events_json_feed): @@ -19,14 +22,3 @@ Here is an example calendar that displays two [JSON feeds](events_json_feed): '/feed2.php' ] }); - -Here is how you would display two Google Calendars: - - $('#calendar').fullCalendar({ - eventSources: [ - $.fullCalendar.gcalFeed("http://www.google.com/feed1"), - $.fullCalendar.gcalFeed("http://www.google.com/feed2") - ] - }); - -More info on displaying Google Calendars can be found [here](../google_calendar). diff --git a/event_data/events_array.txt b/event_data/events_array.txt index 9236006..42c2863 100644 --- a/event_data/events_array.txt +++ b/event_data/events_array.txt @@ -27,3 +27,44 @@ Here is an example of how to specify an array of events: Make sure you do not have a comma after the last event in your array! It will make Internet Explorer choke. + +Extended Form +------------- + +Since version 1.5, you are able to specify [Event Source options](Event_Source_Object#options). +This often comes in handy when you are using the [eventSources]() option to +specify multiple event sources and you want certain options to only apply to certain sources. +However, to do this, you must write things a little differently: + + $('#calendar').fullCalendar({ + + eventSources: [ + + // your event source + { + events: [ // put the array in the `events` property + { + title : 'event1', + start : '2010-01-01' + }, + { + title : 'event2', + start : '2010-01-05', + end : '2010-01-07' + }, + { + title : 'event3', + start : '2010-01-09 12:30:00', + } + ], + color: 'black', // an option! + textColor: 'yellow' // an option! + } + + // any other event sources... + + ] + + }); + +A list of available Event Source options can be found [here](Event_Source_Object#options). diff --git a/event_data/events_function.txt b/event_data/events_function.txt index 8d63ed1..5f8fa85 100644 --- a/event_data/events_function.txt +++ b/event_data/events_function.txt @@ -20,7 +20,7 @@ responsibility to make sure `callback` is being called with an array of [Event Objects](Event_Object). Here is an example showing how to use an event function to fetch events from -an XML feed: +a hypothetical XML feed: $('#calendar').fullCalendar({ events: function(start, end, callback) { @@ -33,16 +33,13 @@ an XML feed: end: Math.round(end.getTime() / 1000) }, success: function(doc) { - var events = []; - $(doc).find('event').each(function() { - event.push({ + events.push({ title: $(this).attr('title'), start: $(this).attr('start') // will be parsed }); }); - callback(events); } }); @@ -51,3 +48,32 @@ an XML feed: However, if you have the choice, JSON is a better idea because you can just specify a [feed URL](events_json_feed). + +Extended Form +------------- + +Since version 1.5, you are able to specify [Event Source options](Event_Source_Object#options). +This often comes in handy when you are using the [eventSources]() option to +specify multiple event sources and you want certain options to only apply to certain sources. +However, to do this, you must write things a little differently: + + $('#calendar').fullCalendar({ + + eventSources: [ + + // your event source + { + events: function(start, end, callback) { + // ... + }, + color: 'yellow', // an option! + textColor: 'black' // an option! + } + + // any other sources... + + ] + + }); + + diff --git a/event_data/events_json_feed.txt b/event_data/events_json_feed.txt index f0753ba..0d7f5dc 100644 --- a/event_data/events_json_feed.txt +++ b/event_data/events_json_feed.txt @@ -17,7 +17,7 @@ The value of the parameters will always be UNIX timestamps (seconds since 1970). Consider the following script: $('#calendar').fullCalendar({ - events: "/myfeed.php" + events: '/myfeed.php' }); Here is a URL that FullCalendar might visit: @@ -25,7 +25,127 @@ Here is a URL that FullCalendar might visit: `/myfeed.php?start=1262332800&end=1265011200&_=1263178646` The `_` parameter is automatically inserted to prevent the browser from -caching the result (see [cacheParam]()). +caching the result ([more below](#caching)). If you need to access a feed that is in a different domain, you can use JSONP with a `?` in your URL (see the JSONP discussion in [$.ajax](http://api.jquery.com/jQuery.ajax/)). + +Extended Form +------------- + +Since version 1.5, you are able to specify [Event Source options](Event_Source_Object#options). +This often comes in handy when you are using the [eventSources]() option to +specify multiple event sources and you want certain options to only apply to certain sources. +However, to do this, you must write things a little differently: + + $('#calendar').fullCalendar({ + + eventSources: [ + + // your event source + { + url: '/myfeed.php', // use the `url` property + color: 'yellow', // an option! + textColor: 'black' // an option! + } + + // any other sources... + + ] + + }); + +A list of general Event Source options can be found [here](Event_Source_Object#options). +However, there are additional options that apply specifically to JSON feeds: + + + + + + + + + + +
+startParam + +Sets the [startParam]() option, but only for this source. +
+endParam + +Sets the [endParam]() option, but only for this source. +
+ +jQuery $.ajax options +--------------------- + +You can also specify any of the [jQuery $.ajax](http://api.jquery.com/jQuery.ajax/) options within the same object! +This allows you to easily pass additional parameters to your feed script, as well as +listen to ajax callbacks: + + $('#calendar').fullCalendar({ + + eventSources: [ + + // your event source + { + url: '/myfeed.php', + type: 'POST', + data: { + custom_param1: 'something', + custom_param2: 'somethingelse' + }, + error: function() { + alert('there was an error while fetching events!'); + }, + color: 'yellow', // a non-ajax option + textColor: 'black' // a non-ajax option + } + + // any other sources... + + ] + + }); + +Here is the same example, but using the single-source `events` option instead: + + $('#calendar').fullCalendar({ + + events: { + url: '/myfeed.php', + type: 'POST', + data: { + custom_param1: 'something', + custom_param2: 'somethingelse' + }, + error: function() { + alert('there was an error while fetching events!'); + }, + color: 'yellow', // a non-ajax option + textColor: 'black' // a non-ajax option + } + + }); + +Caching +------- + + +By default, FullCalendar will insert a `_` parameter into the URL of the request to prevent +the browser from caching the response. +FullCalendar achieves this internally by setting the $.ajax parameter to `false`. + +If you would like to counteract this and prevent the `_` parameter, you can set the `cache` option to `true`: + + + $('#calendar').fullCalendar({ + + events: { + url: '/myfeed.php', + cache: true + } + + }); + diff --git a/event_data/ignoreTimezone.txt b/event_data/ignoreTimezone.txt new file mode 100644 index 0000000..cb4b24a --- /dev/null +++ b/event_data/ignoreTimezone.txt @@ -0,0 +1,18 @@ + +ignoreTimezone *1.4.8* +====================== + +When parsing ISO8601 dates, whether UTC offsets should be ignored +while processing event source data. + +
+Boolean, *default*: `true` +
+ +The default is `true`, which means the UTC offset for all ISO8601 dates will be ignored. +For example, the date `"2008-11-05T08:15:30-05:00"` will be processed as +November 5th, 2008 at 8:15am *in the local offset of the browser*. + +If you are using ISO8601 dates with UTC offsets, chances are you want them +processed. You must set this option to `false`. In the future, the default +for this option will probably be changed to `false`. diff --git a/event_data/index.txt b/event_data/index.txt index f80d3e5..71c1b2f 100644 --- a/event_data/index.txt +++ b/event_data/index.txt @@ -4,14 +4,15 @@ Event Data