Skip to content

Home

Jump to bottom
themouette edited this page Jan 3, 2011 · 11 revisions

Fork information

This is a forked repository. Have a look at
robmonie’s jquery-week-calendar wiki
for more information.

Important information

This plugin is still in alpha version.
Once everything will be fixed and performances will be improved, i’ll upgrade the version number (2.0 ?) and package a download.

This version is backward compatible with the original, but if you want to take advantage of it, have look at what’s new in upgrade from rob's version

Full documentation is available in Script options and Public methods

jQuery Week Calendar

The jquery-week-calendar plugin provides a simple and flexible way of including a weekly calendar in your application. It is built on top of jquery and jquery ui and is inspired by other online weekly calendars such as google calendar. If you require a monthly calendar view, I highly recommend checking out the FullCalendar plugin by Adam Shaw.

To have an overview, do not hesitate to check the demos

Requirements

Week calendar relies on jQuery 1.4 and jQuery-ui 1.8

Calendar features at a glance

  • Display of calendar events within a weekly grid
  • Calendar events can be supplied as an array, url or function returning json
  • Calendar events can be dragged, dropped and resized
  • Lots of callbacks for customizing the way events are rendered plus callbacks for drag, drop, resize, mouseover, click etc
  • Automatically scrolls to current time
  • Freebusy management
  • multi-user management
  • Extend the core calendar event, users and free busys data structure with your own data
  • Highly configurable, enabling variable timeslots, readonly calendars, display of partial days, custom date formatting, direct manipulation of individual events for create, update, delete of events and much more.

The design of the week-calendar plugin is not meant to be a total solution for managing weekly events as this would have limited it’s scope. For example it doesn’t impose a user interface approach for editing and updating calendar events. By providing the base weekly calendar api that is extensible, you will be able to create a much richer domain on top of the basic functionality. To help you achieve this, the calendar has plenty of hooks that make it quite simple to add this stuff in.

Current Version

No official release is available for download, for now it is experimental so don’t hesitate to report bugs

Getting Started

Firstly download the code from google code. The zip contains an example, the source js and css. Note that the example calendar references jquery and jquery-ui from the google cdn. These are not included in the download.

Once you have the code, getting started is as simple as calling the plugin on a container element:

$(“#calendar”).weekCalendar();

This will display the weekly calendar but in order to display some calendar events, we need to add them. Events can be supplied via an array of CalEvent objects which are described below. What’s probably more useful would be to supply a url or function that calls back to the calendar after fetching some json data. To keep it simple though, for this example we’ll simply use a json object to demonstrate:

$(document).ready(function() {
  $('#calendar').weekCalendar({
    events:[{"id":10182,
      "start":"2010-06-16T12:15:00.000+02:00",
      "end":"2010-06-16T13:15:00.000+02:00",
      "title":"Lunch with Mike"
    }, {
      "id":10182,
      "start":"2010-06-16T14:00:00.000+02:00",
      "end":"2010-06-16T15:00:00.000+02:00",
      "title":"Dev Meeting"
    }],
    freebusys: [
      {"start":"2010-06-16T12:15:00.000+02:00","end":"2010-06-16T13:15:00.000+02:00","free":false},
      {"start":"2010-06-16T14:00:00.000+02:00","end":"2010-06-16T15:00:00.000+02:00","free":false}
    ]
  });
});

Calendar Events Data Structure

As described in the calendar options section above, calendar data can be supplied in a number of ways. The simplest is to supply an array of calendar events. Calendar events have the following format

  • id – [integer] – id of the calendar event
  • title – [string] – The title for display in the calendar
  • start – [date, ISO8601 String, IETF String or timestamp] – the start date / time of the event.
  • end – [date, ISO8601 String, IETF String or timestamp] – the end date / time of the event.

You may also choose to return calendar data in another format where the top level data object contains an events array and an optional ‘options’ property. The options property is very useful for allowing you to override specific calendar options on a per data-set basis. This adds extra flexibility but it also requires a re-rendering of the calendar if any options have changed so it can introduce a slightly less snappy experience for the user when they navigate calendar weeks or switch calendar data in other ways. The calendar does not discriminate between different options at this stage so be careful what you return in the ‘options’ property. Obviously this feature is better suited to some options than others.

data = {
  options : {
    timeslotsPerHour : 3
  },
  events : [ ... ]
}

Calendar events can contain any other data you may need. This can be useful when passed to any of the event callbacks for determining things such as whether an event should be draggable, or whether any additional classes should be added to the element. For example you may want to add a ‘readonly’ property to a calendar event in order to then use that property to prevent dragging, dropping, resizing and editing of the event.

CalEvent date formats

Dates for calEvents can be supplied as native date objects or as strings or numbers where appropriate in any of the following formats:

  • ISO8601 – eg. 2009-05-03T14:00:00.000+10:00
  • MILLIS – timestamp

Retrieving Calendar Events via a function

There is often a case for providing your own implementation for fetching data remotely rather than simply providing a url. Maybe you need to use an existing service that returns the calendar events in a different format or they aren’t at the root node of the response object. This is simple to do using $.getJson. For example:

data: function(start, end, callback) {
  $.getJSON("calendarevents.json", {
     start: start.getTime(),
     end: end.getTime()
   },  function(result) {
     callback(result);
   });
}

Browser Compatibility

I intend to support the following browsers. IE6 will almost certainly never be supported. Some may complain, but this me doing my minuscule part to help eradicate it from the world. Also I don’t have the need or the time to support it. Sorry.

  • Firefox 3.x (may also work in 2)
  • Safari 3.1 +
  • IE7+
  • Google Chrome

Look & Feel

The skin provided has been left intentionally basic but can be extended very simply. The recommended approach would be to add your own stylesheet that overrides colors etc as required rather than editing the style sheet itself. This makes upgrades a simpler task.

I have entertained the thought of making the calendar jquery-ui theme compatible but I don’t think the design elements in the calendar completely fit with those provided by the theme builder so probably wouldn’t work out.

Support & Feedback

There is a google group for all your questions and answers.

contributors are welcome too.

Known Issues / Limitations & General Status

…

Thanks

Thanks to all of you who help by providing bug reports, feature requests and patches.

Clone this wiki locally