This is a jQuery plugin which allows developers to implement an extremely flexible calendar interface with minimal up front development.
The calendar method can be used to create a calendar widget which will allow users to graphically see and optionally edit events. The calendar leaves data implementation up to the developer. Developers can feed event data to the calendar using a standard object notation.
$(function(){
$('#myCalendar').cal();
}
The target element must be a relative or absolute positioned block level element of your choice.
You simply specify a relative or absolutely positioned parent element (a <div /> would be a typical choice), and the plugin will generate the required HTML within that element.
The HTML structure that the plugin generates is relatively complicated, and can vary depending on the setup options you've chosen, but a typical configuration will result in the following basic HTML:
<div class="ui-cal ui-cal-container">
<div class="ui-cal-timeline"><!-- Contains time labels (vertical) --></div>
<div class="ui-cal-dateline"><!-- Contains date labels (horizontal) --></div>
<div class="ui-cal-dateline-fill" />
<div class="ui-cal-wrapper"><!-- Contains 'increment' grid blocks --></div>
</div>
You can also use methods implemeneted by this plugin for formatting dates and times using the built in format method.
$(function(){
$.cal.format( new Date(), 'Y-m-d H:i:s' ); // OR
$.cal.date().format( 'Y-m-d H:i:s' ); // Outputs '1986-04-21 08:00:00' if the current time was 8am on the 21st April 1986.
}
This is the minimum config you'll need to generate a useful, read only calendar (in fact, you can omit the startdate and daystodisplay, but in most cases you'll want control over which dates are being displayed. In this example, we're using a static array of event objects to populate the calendar with events.
$(function(){
$('div.calendar').cal({
startdate : '2011-08-01',
daystodisplay : 5,
events : [
{
uid : 1,
begins : '2011-08-04 10:00:00',
ends : '2011-08-04 11:30:00',
notes : 'Testing...',
color : 'purple'
},
{
uid : 2,
begins : '2011-08-03 11:00:00',
ends : '2011-08-03 13:45:00',
title : 'Test'
}
]
});
});
<div class="calendar"></div>
This syntax allows you to display events from multiple sources in the same calendar layout. This is especially useful when combining events from shared ics feeds, and your own sources.
$(function(){
$('div.calendar').cal({
startdate : '2011-08-01',
daystodisplay : 5,
calendars : [
// Calendar source 1
[
{
uid : '1@cal1',
begins : '2011-08-04 08:00:00',
ends : '2011-08-04 09:30:00',
notes : 'Calendar 1...',
color : 'purple'
}
],
// Calendar source 2
[
{
uid : '1@cal1',
begins : '2011-08-04 10:00:00',
ends : '2011-08-04 11:30:00',
notes : 'Calendar 2...',
color : 'green'
}
]
]
});
});
| Property | Default | Description |
|---|---|---|
| startdate | *current date* | The first date to display on the calendar, defined as either ISO8601 (e.g., '2011-08-01' for first of August 2011) or as a JavaScript date object. |
| daystodisplay | 7 | The number of days in total to display on the calendar. |
| defaultcolor | '#255BA1' | The default color to use for an event, where no other color is given in the event object. |
| maskeventlabel | 'g:i A' | The date mask used to format the start time shown on an event element. When a title is specified on an event object, it is displayed instead of the formatted time. |
| maskeventlabeldelimiter | '' | A string to be used as a delimiter between 'maskeventlabel' and 'maskeventlabelend'. Usually a dash padded with spaces. |
| maskeventlabelend | '' | The date mask used to format the end time shown on an event element. When a title is specified on an event object, it is displayed instead of the formatted time. |
| maskmonthlabel | 'l' | The date mask used to format the week labels shown on the month calendar. |
| maskdatelabel | 'D, jS' | The date mask used to format the date labels shown at the top of the calendar. |
| masktimelabel | {
'00' : 'g:i <\\sp\\a\\n>A<\/\\sp\\a\\n>',
'noon' : '\\N\\O\\O\\N'
} | An object containing the date masks used to format the time labels shown at the left of the calendar. The property names specify where the label is to be used, for example, '00' refers to all labels that fall on the hour, '30' refers to all labels that fall on the half hour. |
| daytimestart | '00:00:00' | Defines the time that the calendar starts drawing the day. E.g., A setting of '08:00:00' would cause the calendar to draw all hours starting from 8 am through to the daytimeend. |
| daytimeend | '24:00:00' | Defines the time that the calendar finishes drawing the day. E.g., A setting of '18:00:00' would cause the calendar to draw all hours starting from daytimestart through to 6 pm. |
| minwidth | 120 | The minimum width in pixels of the each day column. |
| minheight | *calculated* | The minimum height in pixels of each grid row. The default is calculated so that 1 pixel represents 1 minute (i.e., an hour will be 60 pixels). |
| gridincrement | '15 mins' | Defined the spacing of the grid lines. E.g., A setting of '30 mins' would create a grid line for every 30 minute increment. |
| allowmove | false | When set to true, allows the user to drag an event to a new location on the screen. Most useful with the 'eventmove' event. |
| allowresize | false | When set to true, allows the user to drag handles located at the top and bottom of an event to resize. Most useful with the 'eventresize' event. |
| allowselect | false | When set to true, allows the user to select an event by single clicking. Most useful with the 'eventselect' event. |
| allowremove | false | When set to true, displays a (x) icon in the top right of an event, which removes the event when clicked. Most useful with the 'eventremove' event. |
Config data can be passed when you first initialise the object, as shown in the demo above. Additionally, you can use the 'option' method to apply or modify config properties.
Use the php date characters to create your date mask. Be aware when writing your date mask, that any masked characters will need to be double backslashed in the JavaScript source, as demonstrated below. Non masked characters don't need to be escaped.
$(function(){
setInterval(function(){
var time = $.cal.date().format( 'Y-m-d<b\\r />g\\h i\\m s\\s a' );
$('p.output').html( time );
}, 1000 );
});
Most, but not all of the mask characters implemented in PHP are avaialable due to technical limitations with JavaScript dates. When using an incompatible mask character, an error will be printed in the console log.
The masktimelabel object is available as a flexible way of formatting the time labeles that appear to the left of the calendar. The property names specify where the label is to be used, for example, '00' refers to all labels that fall on the hour, '30' refers to all labels that fall on the half hour, and in a special case, 'noon' refers to 12:00 PM specifically.
// Left calendar
$('#div.calendar1').cal({
masktimelabel : {
'00' : 'g:i a'
}
});
// Center calendar
$('#div.calendar2').cal({
masktimelabel : {
'00' : 'g:i a',
'30' : '<\\sp\\a\\n>30<\/\\sp\\a\\n>'
}
});
// Right calendar
$('#div.calendar3').cal({
masktimelabel : {
'00' : 'g:i <\\sp\\a\\n>A<\/\\sp\\a\\n>',
'15' : '<\\sp\\a\\n>15<\/\\sp\\a\\n>',
'30' : '<\\sp\\a\\n>g:30<\/\\sp\\a\\n>',
'45' : '<\\sp\\a\\n>15<\/\\sp\\a\\n>',
'noon' : '\\N\\O\\O\\N'
}
});
The <span /> tags wrap text that we want to show in the lighter grey; this style is defined in jquery.calendar.css.
The gridincrement setting allows you to specify where the grid lines appear on the calendar.
// Left calendar
$('#demo4 div.calendar1').cal({
gridincrement : '30 mins'
});
// Right calendar
$('#demo4 div.calendar2').cal({
gridincrement : '1 hour'
});
| Event | Parameters | Details |
|---|---|---|
| eventmove | String, Object, Collection | Called when the user finishes a drag operation. Recieves the events UID as passed in the original event object, the data object which represents the appointment, and a jQuery collection containing the event element. |
| eventresize | String, Object, Collection | Called when the user finishes a resize operation. Recieves the events UID as passed in the original event object, the data object which represents the appointment, and a jQuery collection containing the event element. |
| eventselect | String, Object, Collection | Called when the user clicks on an event. Recieves the events UID as passed in the original event object, the data object which represents the appointment, and a jQuery collection containing the event element. Return false from the callback function to prevent selection. |
| eventremove | String, Object, Collection | Called when the user clicks on an events remove button. Recieves the events UID as passed in the original event object, the data object which represents the appointment, and a jQuery collection containing the event element. Return false from the callback function to prevent removal. |
| eventeditnotes | String, Object, Collection | Called when the user edits the notes of an event using the inline editing feature. Recieves the events UID as passed in the original event object, the data object which represents the appointment, and a jQuery collection containing the event element. |
In this example, we show how the eventselet event can be used to display details about the selected appointment. We also see how we can prevent selection by returning false in the hanlder function.
Click an event to select.
$('div.calendar').cal({
events : demoevents,
allowselect : true,
eventselect : function( uid, $event ){
if( uid == 1 ){
alert('Sorry, this event cannot be selected.');
return false;
} else {
$('p.output').text( 'You selected event #'+uid );
$('table').html(
'<tr><td>Begins</td><td>'+$event.data('cal').begins.format('g:i a')+'</td></tr>'+
'<tr><td>>Ends</td><td>'+$event.data('cal').ends.format('g:i a')+'</td></tr>'
);
}
}
});
In this example, we show how the eventremove event can be used to perform an action (such as sending of an AJAX request to update the database) when the user clicks the delete button. It also demonstrates that we can prevent the deletion by returning false in the handler function.
$('div.calendar').cal({
events : demoevents,
allowremove : true,
eventremove : function( uid ){
if( uid == 1 ){
alert('Sorry, this event cannot be removed.');
return false;
} else {
$('p.output').text( 'You removed event #'+uid );
}
}
});
| Method | Returns | Description |
|---|---|---|
| .cal( 'option', [ Object ] ) .cal( 'option', [ String, String ] ) | jQuery String | Takes a config object, or config string/value and applies the configuration option to the calendar. |
| .cal( 'version' ) | String | Returns the version number of the currently installed calendar plugin. |
| .cal( 'destroy' ) | jQuery | Removes the calendar from the targeted element, and returns the element to its pre-initialisation state. |
| $.cal.date( [ Date ] ) | Date | Takes a date object, and returns an extended date object. See the associated documentation for more details on the date methods. |
| $.cal.format( [ Date ] ) | String | Takes a date object, and returns a formatted string, according to the passed mask. |
| $.cal.incrementsIn( String, String ) | Number | Takes two strings representing a portion of time, (E.g., '15 mins' or '2 hours' ), and returns the number of times the second increment fits inside the first. For example, $.cal.incrementsIn('1 hour','15 mins') returns 4. |
This plugin has been tested, and verified working in the following browsers with JavaScript enabled.
That doesn't mean it doesn't work in other browsers, it just means we haven't tested it yet!