From ddd7430d11d5bf531d286d286c4b3d0e4efd589a Mon Sep 17 00:00:00 2001 From: Adam Shaw Date: Mon, 5 Jul 2010 16:30:40 -0700 Subject: [PATCH] updates for docs, including selectable/droppable --- dropping/drop.txt | 23 +++++++++++++++++ dropping/dropAccept.txt | 40 ++++++++++++++++++++++++++++ dropping/droppable.txt | 46 +++++++++++++++++++++++++++++++++ dropping/index.txt | 9 +++++++ event_data/lazyFetching.txt | 5 ++++ event_ui/Requirements.txt | 5 ++-- google_calendar.txt | 5 ++++ index.txt | 28 +++++++++++--------- selection/index.txt | 14 ++++++++++ selection/selectHelper.txt | 19 ++++++++++++++ selection/select_callback.txt | 22 ++++++++++++++++ selection/select_method.txt | 9 +++++++ selection/selectable.txt | 25 ++++++++++++++++++ selection/unselectAuto.txt | 11 ++++++++ selection/unselectCancel.txt | 19 ++++++++++++++ selection/unselect_callback.txt | 24 +++++++++++++++++ selection/unselect_method.txt | 9 +++++++ 17 files changed, 298 insertions(+), 15 deletions(-) create mode 100644 dropping/drop.txt create mode 100644 dropping/dropAccept.txt create mode 100644 dropping/droppable.txt create mode 100644 dropping/index.txt create mode 100644 selection/index.txt create mode 100644 selection/selectHelper.txt create mode 100644 selection/select_callback.txt create mode 100644 selection/select_method.txt create mode 100644 selection/selectable.txt create mode 100644 selection/unselectAuto.txt create mode 100644 selection/unselectCancel.txt create mode 100644 selection/unselect_callback.txt create mode 100644 selection/unselect_method.txt diff --git a/dropping/drop.txt b/dropping/drop.txt new file mode 100644 index 0000000..6280b65 --- /dev/null +++ b/dropping/drop.txt @@ -0,0 +1,23 @@ + +drop *1.4.7* +============ + +Called when a valid jQuery UI draggable has been dropped onto the calendar. + +
+function( *date*, *allDay*, *jsEvent*, *ui* ) { } +
+ +`date` holds the JavaScript Date object of where the draggable was dropped. + +`allDay` holds a boolean of whether the draggable was dropped on an all-day cell +(like in month view) or in a slot with a specific time (like in agenda view). + +`jsEvent` holds the primitive JavaScript event, with information like mouse coordinates. + +`ui` holds the jQuery UI information. + +`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). diff --git a/dropping/dropAccept.txt b/dropping/dropAccept.txt new file mode 100644 index 0000000..3b2d3ff --- /dev/null +++ b/dropping/dropAccept.txt @@ -0,0 +1,40 @@ + +dropAccept *1.4.7* +================== + +Provides a way to filter which elements can be dropped onto the calendar. + +
+String/Function, *default*: `"*"` +
+ +By default, after setting a calendar' [droppable]() option to `true`, the calendar +will accept any draggables that are dropped onto the calendar. The `dropAccept` option +allows the calendar be more selective about which elements can/can't be dropped. + +The value of `dropAccept` can be a string [jQuery selector](http://api.jquery.com/category/selectors/). +It can also be a function that accepts the draggable item as a single argument, and returns `true` +if the element can be dropped onto the calendar. + +In the following example, the first draggable (with id `"draggable1"`) can be dropped on the calendar, +while the second draggable (with id `"draggable2"`) cannot: + + ... +
+ +
+
+ ... + +and here is the JavaScript: + + $('#calendar').fullCalendar({ + droppable: true, + dropAccept: '.cool-event', + drop: function() { + alert('dropped!'); + } + }); + + $('#draggable1').draggable(); + $('#draggable2').draggable(); diff --git a/dropping/droppable.txt b/dropping/droppable.txt new file mode 100644 index 0000000..0ddbd56 --- /dev/null +++ b/dropping/droppable.txt @@ -0,0 +1,46 @@ + +droppable *1.4.7* +================= + +Determines if jQuery UI draggables can be dropped onto the calendar. + +
+Boolean, *default*: `false` +
+ +This option operates with jQuery UI draggables. You must [download](http://jqueryui.com/download) +the appropriate jQuery UI files and initialize a [draggable](http://jqueryui.com/demos/draggable/) element. +Additionally, you must set the calendar's `droppable` option to `true`. + +Here is how you might initialize an element that can be dragged onto a calendar: + + $('#my-draggable').draggable({ + revert: true, // immediately snap back to original position + revertDuration: 0 // + }); + + $('#calendar').fullCalendar({ + droppable: true, + drop: function(date, allDay) { + alert("Dropped on " + date + " with allDay=" + allDay); + } + }); + + +How can I use this to add events??? +----------------------------------- + +Good question. It is a common need to have an "external list of events" that can be +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). + +In short, you must call [renderEvent](../event_rendering/renderEvent) yourself +in the [drop]() callback. + +
+Hopefully, this task will become more convenient with future API changes. +
diff --git a/dropping/index.txt b/dropping/index.txt new file mode 100644 index 0000000..f8a2837 --- /dev/null +++ b/dropping/index.txt @@ -0,0 +1,9 @@ + +Dropping External Elements +========================== + + diff --git a/event_data/lazyFetching.txt b/event_data/lazyFetching.txt index ad8f7df..b74510e 100644 --- a/event_data/lazyFetching.txt +++ b/event_data/lazyFetching.txt @@ -16,3 +16,8 @@ The calendar will avoid fetching events because it already has this information When set to `false`, the calendar will fetch events any time the view is switched, or any time the current date changes (for example, as a result of the user clicking prev/next). + +
+Before this option existed, FullCalendar would always do "lazy" event fetching, +as if `lazyFetching` were set to `true`. +
diff --git a/event_ui/Requirements.txt b/event_ui/Requirements.txt index c068487..95353d2 100644 --- a/event_ui/Requirements.txt +++ b/event_ui/Requirements.txt @@ -4,14 +4,13 @@ Requirements for Event Dragging & Resizing Event dragging and resizing requires the following jQuery UI modules: -- jQuery UI core - [Draggable](http://jqueryui.com/demos/draggable/) (the Droppable module is **not** required) - [Resizable](http://jqueryui.com/demos/resizable/) These modules can be conveniently bundled/compressed/downloaded at the jQuery UI [downloads page](http://jqueryui.com/download). -They are also included in the FullCalendar download in the "jquery" directory, -though as uncompressed files. +They are also included in the FullCalendar download in "jquery/jquery-ui-custom.js", +all bundled and compressed into one file. After you have gathered the dependencies, **you still need to enable dragging/resizing** by settings the [editable]() option to `true`. diff --git a/google_calendar.txt b/google_calendar.txt index af5ccc8..fc6868d 100644 --- a/google_calendar.txt +++ b/google_calendar.txt @@ -23,6 +23,11 @@ It can serve as a backend that manages and persistently stores event data 4. In the "Calendar Address" section of the screen, click the XML badge. 5. Your feed's URL will appear. +**Next, you must have all the required js/css files**. This includes the standard fullcalendar.js +and fullcalendar.css, **in addition to gcal.js**: + + + **Now it's time to initialize your calendar in JavaScript.** You will use the `$.fullCalendar.gcalFeed` function with the `events` option, like so: diff --git a/index.txt b/index.txt index 0080fd3..392af34 100644 --- a/index.txt +++ b/index.txt @@ -1,13 +1,17 @@ -- [Basic Usage](usage) -- [Google Calendar](google_calendar) -- [General Display](display) -- [Views](views) -- [Agenda Options](agenda) -- [Current Date](current_date) -- [Text/Time Customization](text) -- [Clicking & Hovering](mouse) -- [Event Data](event_data) -- [Event Rendering](event_rendering) -- [Event Dragging & Resizing](event_ui) -- [Utilities](utilities) + diff --git a/selection/index.txt b/selection/index.txt new file mode 100644 index 0000000..6cb8ffa --- /dev/null +++ b/selection/index.txt @@ -0,0 +1,14 @@ + + +

Selection

+ + diff --git a/selection/selectHelper.txt b/selection/selectHelper.txt new file mode 100644 index 0000000..5aad86e --- /dev/null +++ b/selection/selectHelper.txt @@ -0,0 +1,19 @@ + +selectHelper *1.4.6* +==================== + +Whether to draw a "placeholder" event while the user is dragging. + +
+Boolean/Function, *default*: `false` +
+ +**This option only applies to the agenda views.** + +A value of `true` will draw a "placeholder" event while the user is dragging +(similar to what Google Calendar does for its week and day views). +A value of `false` (the default) will draw the standard highlighting over each cell. + +A function can also be specified for drawing custom elements. +It will be given 2 arguments: the selection's start date and end date (Date objects). +It must return a DOM element that will be used. diff --git a/selection/select_callback.txt b/selection/select_callback.txt new file mode 100644 index 0000000..75025ec --- /dev/null +++ b/selection/select_callback.txt @@ -0,0 +1,22 @@ + +select *1.4.6* +============== + +A callback that will fire after a selection is made. + +
+function( *startDate*, *endDate*, *allDay*, *jsEvent*, *view* ) +
+ +`startDate` is a Date object indicating the beginning of the selection. + +`endDate` is a Date object indicating the end of the selection. It follows +the same rules as the [Event Object](../event_data/Event_Object) for inclusivity/exclusivity: +when `allDay` is `true`, `endDate` *includes* the last day. + +`allDay` is a boolean indicating if entire days were selected (days in month view +or the "all-day" slot in the agenda view) or time slots were selected. + +`jsEvent` holds the primitive JavaScript event with information such as mouse coordinates. +If `select` has been triggered via the [select method](select_method), `jsEvent` will be `undefined`. +(added in version 1.4.7) diff --git a/selection/select_method.txt b/selection/select_method.txt new file mode 100644 index 0000000..4c6f40d --- /dev/null +++ b/selection/select_method.txt @@ -0,0 +1,9 @@ + +select *1.4.6* +============== + +A method for programmatically selecting a period of time. + +
+.fullCalendar( 'select', *startDate*, *endDate*, *allDay* ) +
diff --git a/selection/selectable.txt b/selection/selectable.txt new file mode 100644 index 0000000..6ac2089 --- /dev/null +++ b/selection/selectable.txt @@ -0,0 +1,25 @@ + +selectable *1.4.6* +================== + +Allows a user to highlight multiple days or timeslots by clicking and dragging. + +
+Boolean/[View Option Hash](../views/View_Option_Hash/), *default*: `false` +
+ +To let the user make selections by clicking and dragging, +this option must be set to `true`. + +The [select](select_callback) and [unselect](unselect_callback) callbacks +will be useful for monitoring when selections are made and cleared. + +To learn the ways in which selections can be cleared, read the docs +for the [unselect](unselect_callback) callback. + +To view an example of how to create a new event based on a user's selection +see "examples/selectable.html" in the download, or [visit this page](/js/fullcalendar/examples/selectable.html). + +
+A View Option Hash has been supported since version 1.4.7 +
diff --git a/selection/unselectAuto.txt b/selection/unselectAuto.txt new file mode 100644 index 0000000..fbee78c --- /dev/null +++ b/selection/unselectAuto.txt @@ -0,0 +1,11 @@ + +unselectAuto *1.4.6* +==================== + +Whether clicking elsewhere on the page will cause the current selection to be cleared. + +
+Boolean, *default*: `true` +
+ +This option can only take effect when [selectable]() is set to `true`. diff --git a/selection/unselectCancel.txt b/selection/unselectCancel.txt new file mode 100644 index 0000000..304ce14 --- /dev/null +++ b/selection/unselectCancel.txt @@ -0,0 +1,19 @@ + +unselectCancel *1.4.6* +====================== + +A way to specify elements that will ignore the [unselectAuto]() option. + +
+String, *default*: `''` +
+ +Clicking on elements that match this [jQuery selector](http://api.jquery.com/category/selectors/) will prevent the +current selection from being cleared (due to the [unselectAuto]() option). + +This option is useful if you have a "Create an event" form +that shows up in response to the user making a selection. +When the user clicks on this form, you probably don't want to +the current selection to go away. Thus, you should add a class to your form +such as "my-form", and set the `unselectAuto` option +to `".my-form"`. diff --git a/selection/unselect_callback.txt b/selection/unselect_callback.txt new file mode 100644 index 0000000..ce56fea --- /dev/null +++ b/selection/unselect_callback.txt @@ -0,0 +1,24 @@ + +unselect *1.4.6* +================ + +A callback that will fire when the current selection is cleared. + +
+function( *view*, *jsEvent* ) +
+ +A selection might be cleared for a number of reasons: + +1. The user clicks away from the current selection (doesn't happen when [unselectAuto]() is `false`). + +2. The user makes a *new* selection. The `unselect` callback will be fired before the new selection occurs. + +3. The user moves forward or backward in the current view, or switches to a new view. + +4. The [unselect](unselect_method) method is called through the API. + + +`jsEvent` holds the primitive JavaScript event with information such as mouse coordinates. +If `unselect` has been triggered via the [unselect method](unselect_method), `jsEvent` will be `undefined`. +(added in version 1.4.7) diff --git a/selection/unselect_method.txt b/selection/unselect_method.txt new file mode 100644 index 0000000..181e12f --- /dev/null +++ b/selection/unselect_method.txt @@ -0,0 +1,9 @@ + +unselect *1.4.6* +================ + +A method for programmatically clearing the current selection. + +
+.fullCalendar( 'unselect' ) +