About this tutorial

After using Dojo for some time and looking for a calendar widget I gave up and started coding one myself. I had several goals with this widget: Using any back-end database for the entries, time zone changes, localized (internationalization i18n) and being able to drag entries to other dates.

This tutorial gives you all the code and files to get this calendar up and running on your server.

Fig. 1

Prerequisites

This tutorial is written for JavaScript programmers whose skills are at a medium to expert level. You should also have an intermediate knowledge of Dojo Toolkit HTML widgets.

The code I show here is only tested on:

Servers: Windows and Linux. The code here runs on a Linux server.
Clients: I’ve tested Firefox 2.x on Windows and Linux and IE 6 and 7 on Windows.

Please don’t bug me if the code won’t work on anything else. I know there are many Mac users out there, but I don’t have one. If you will buy me one I’ll be happy to test on that platform as well. As for browsers, the two browsers mentioned above is what 99% of my clients/friends use so I stick with them. If it crashes your server/client, don’t blame me. You download and try this code on your own terms/risks. If you have any suggestions on to how make it work for any other browsers, please feel free to leave a comment.

I had a few goals that I wanted to accomplish:

• Using standard Dojo Widget authoring techniques.
• The calendar entries could reside on ANY database backend.
• Time zone sensitive
• Internationalization (i18n)

Getting started

First you download the files needed for the Calendar to work. These files are zipped and should be extracted on your server.

• Dojo Toolkit - 0.4.1 or later.
• MyWidgets - This is the folder with all the code for the Calendar widget. Should be extracted next/parallel to the dojo folder.
• Calendar File - The HTML file. If you don’t want to code yourself. Located in a folder called calendar.

Then in normal Dojo widget way we add the JavaScript and the HTML to show the widget.

In the header of our html page we add:
<script type="text/javascript" src="../dojo/dojo.js"></script>
<script type="text/javascript">
dojo.require("mywidgets.widget.Calendar");

And then in our body we add:
<div style="width:800px; height:400px; background-color:#cccccc; overflow:auto;">
<div id="dojoCalendar" dojoType="mywidgets:calendar"></div>
</div>

The outer div here is only for sizing the actual Calendar. It also adds a background color, so you can choose any color you want for your site.

Save the file as index.html on your server in a folder called “calendar”. The calendar folder should be next/parallel to the “dojo” and the “mywidgets” folder.
Browse to the calendar folder and you should see something similar to Fig 1 above. If your machine is using another Regional and Language option than English you will see all month- and day names in your language. This is done by the i18n (internationalization) Dojo code build into the Calendar widget.

Show some Calendar entries

I wanted this widget to be totally separated from all back-end code (the actual calendar entries) but I still (obviously) needed a way of showing the calendar entries in the calendar. We do this by creating an object (JSON) that I pass in to the widget. This object looks like this:


entries: {
"id1": (String - Unique identifier of event) {
starttime: "2006-12-30T08:05:00-06:00", (String - Formatted according to RFC 3339. See dojo.date.serialize)
endtime: "2006-12-30T10:05:00-06:00", (String - Formatted according to RFC 3339. See dojo.date.serialize)
allday: false, (Boolean - Is event an all day event)
repeated: false, (Boolean - Is event repeated)
title: "Title 1", (String - Event title)
url: "http://yourdomain.com/events/thisevent", (String - Event URL (if any))
body: "This is the body", (String - Event body text (if any))
attributes: {Location:"Location 1",Chair:"John Doe"}, (Object - All attributes you want in name value pairs)
type: ["meeting","reminder"] (Array - Event/Icon types you want for this event. See “eventtypes”)
}
}

This is how the object needs to be structured if you use your own back-end database. So how do we pass this object into the Calendar widget?
Add the following code at the top of our HTML file, right after: dojo.require("mywidgets.widget.Calendar");.

dojo.addOnLoad(init);
var oCalendar;

function init(){
oCalendar = dojo.widget.byId("dojoCalendar");
oCalendar.onValueChanged = widgetValueChanged;
widgetValueChanged(new Date());
}

function widgetValueChanged(dateObj){

}

The code dojo.addOnLoad(init); is Dojo’s way of telling the browser that when everything is loaded on the page call this script. So we call the function init. In this function we set the global variable oCalendar to the widget object “dojoCalendar”.

We also set the onValueChanged function to be called by a function called “widgetValueChanged”. We need to pass a date into that function. The Calendar widget code passes that date into this function when we change date in the Calendar, by moving to another month for instance.

The function “widgetValueChanged” is where we would call script to query our database for calendar entries for this particular month. I will give examples on doing this in part 2 of this posting. The query should always return all entries for a whole month.

I have created some simple code here that create 3 entries. On the 1st, 15th and the 28th for any month you select.

function widgetValueChanged(dateObj){
dojo.require("dojo.date.serialize");
var d1s = new Date(dateObj);
d1s.setDate(1);
d1s.setHours(14,0,0,0);
var d1e = new Date(dateObj);
d1e.setDate(1);
d1e.setHours(14,30,0,0);
var d15s = new Date(dateObj);
d15s.setDate(15);
var d15e = new Date(dateObj);
d15e.setDate(15);
var d28s = new Date(dateObj);
d28s.setDate(28);
d28s.setHours(16,40,0,0);
var d28e = new Date(dateObj);
d28e.setDate(28);
d28e.setHours(18,30,0,0);
var entries = {
"id1": {
starttime: dojo.date.toRfc3339(d1s),
endtime: dojo.date.toRfc3339(d1e),
allday: false,
repeated: false,
title: "Title 1",
url: "",
body: "This is the body of entry with id: id1 and title: Title 1",
attributes: {
Location: "My Galactic Headquarters",
Chair: "John Doe"
},
type: ["meeting"]
},
“id2″: {
starttime: dojo.date.toRfc3339(d15s),
endtime: dojo.date.toRfc3339(d15e),
allday: true,
repeated: false,
title: “Title 2″,
url: “”,
body: “This is the body of entry with id: id2 and title: Title 2″,
attributes: {
Location: “Somewhere”
},
type: ["appointment","super"]
},
“id3″: {
starttime: dojo.date.toRfc3339(d28s),
endtime: dojo.date.toRfc3339(d28e),
allday: false,
repeated: false,
title: “Title 3″,
url: “”,
body: “This is the body of entry with id: id3 and title: Title 3″,
attributes: “”,
type: ["reminder"]
}
}
oCalendar.setCalendarEntries(entries);
}

All we do here is set 3 dates and time for start- and end-time. The first line adds the Dojo functionality to create RFC 3339 strings out of a date. The last line of the code pass the object in to the Calendar widget. As I mentioned earlier I will give you code examples of passing real entries into the Calendar in part 2 of this posting.

Fig. 2

If you go to your HTML page now you will see the 3 entries on any month you go to. Hover over the title and you will see more data about the entry including icons, start- and end time (not the 15th, it is an all-day event), and any other attributes you passed in. This is done by a Dojo widget called Tooltip that I added into the code. See Fig. 2

Time zones

One of the goals I wanted to achieve with this calendar was that it would handle timezones. The nice feature with Dojo dates are that they are timezone sensitive. That means that when you pass in a date in the Rfc3339 format (2007-03-11T10:05:00-06:00) that includes a timezone value it will convert the entry into the timezone your computer is set to. This is great most of the time but if you are like me and travel over timezones all the time I want to be able to show the entry times in the zone I’m in at the moment.

I didn’t add all the timezones and their offset from UTC into the Calendar widget code itself for a couple of reasons. First, there are many timezone code examples out there and you might have one that is better than mine. Second, you might not want this feature and instead always show the times in the end-user’s timezone. Timezones are a strange chapter since many countries actually change dates from year to year when daylight savings time go in- and out of effect. Just look at what Australia and USA have done just recently. If you see that any location is wrong or missing in my Timezones widget please leave a comment to this posting and I will change it as soon as I can.

As part of the code you have downloaded, inside the “mywidgets” folder is a widget called Timezones. This widget holds all timezones that I had on file. It is updated with the latest USA daylight savings dates. Below you can see the first 5 locations in that file. Feel free to explore the Timezones widget.

mywidgets.widget.timezones = [
{name:"International Date Line West", sn:"Dateline", offset:-720, dst:0, standard:0},
{name:"Midway Island, Samoa", sn:"Samoa", offset:-660, dst:0, standard:0},
{name:"Hawaii", sn:"Hawaiian", offset:-600, dst:0, standard:0},
{name:"Alaska", sn:"Alaskan", offset:-540, dst:"3,-1,1", standard:"10,-1,1"},
{name:"Pacific Time (US & Canada); Tijuana", sn:"Pacific", offset:-480, dst:"3,-1,1", standard:"10,-1,1"}
]

If you don’t use my Timezone widget but your own code you need to pass in the different locations this way. As you can see we have an array of objects. Each location is an object with with name value pairs. They are:

• name: The name of your timezone location. Usually all the locations this zone apply to.
• sn: Short name of location
• offset: The offset in minutes from UTC
• dst: The date daylight savings go into effect. (Month, Number of day (-1 indicate last), Day (starting with Sunday as 1)). If no DST specify a 0 (zero)
• standard: The date that standard time go into effect. Same attributes as dst.

To pass this into the Calendar widget we have to add some code to our HTML. Don’t worry it’s only a couple of lines.
After our dojo.require("mywidgets.widget.Calendar"); we add another line that says:
dojo.require("mywidgets.widget.Timezones");

And in our “init” function we add:
oCalendar.setTimeZones(mywidgets.widget.timezones);

The “init” function will now look like this, with the new line in bold:

function init(){
oCalendar = dojo.widget.byId("dojoCalendar");
oCalendar.setTimeZones(mywidgets.widget.timezones);
oCalendar.onValueChanged = widgetValueChanged;
widgetValueChanged(new Date());
}

What did we add? If you go to your HTML page now and refresh you will see a new icon at the top of the Calendar that looks like a clock. Click on it and you will see a modal floating window with all timezone locations that are in the Timezone widget. See Fig. 3.

Fig. 3

The selected time zone you see is “Default” which means you don’t have any time zone selected and all entry times are in your computer’s time. Select another time zone and you will see that the modal floating window automatically closes and all entry times are reflected by the new time zone selected. If you select a time zone way before or after yours you will see that the entries even change date they are on. If you select a time zone that differs not just by hours, but also by minutes, like Kathmandu you will see that the entry times are reflected as well. This does not reflect all-day events, they should never be moved.

More on Time zones

This is nice but when you change a timezone we might want this change to “stick” so when we come back to the Calendar our selected time zone will still be selected. So we need to save a cookie with the selected time zone. Time to add 2 lines of code to the “init” function again.

function init(){
oCalendar = dojo.widget.byId("dojoCalendar");
oCalendar.setTimeZones(mywidgets.widget.timezones);
oCalendar.selectedtimezone = dojo.io.cookie.getObjectCookie(”DCTZ”);
oCalendar.onSetTimeZone = widgetTimeZoneChanged;
oCalendar.onValueChanged = widgetValueChanged;
widgetValueChanged(new Date());
}

We also add another function to our code, “widgetValueChanged”.

function widgetTimeZoneChanged(){
if(oCalendar.selectedtimezone == ""){
dojo.io.cookie.deleteCookie("DCTZ");
}else{
dojo.io.cookie.setObjectCookie("DCTZ",oCalendar.selectedtimezone,3650);
}
}

The dojo.io.cookie code above is part of Dojo and as you can see they have built in functions for passing objects to create and/or get cookies. Now we can select a time zone in our Calendar, close our browser windows, come back and the same time zone is still selected.

Changing date for a calendar entry

What if I want to move an entry to another date? Well, there is code for that built in as well. Add 2 more lines of code to our “init” function.

function init(){
oCalendar = dojo.widget.byId("dojoCalendar");
oCalendar.setTimeZones(mywidgets.widget.timezones);
oCalendar.selectedtimezone = dojo.io.cookie.getObjectCookie("DCTZ");
oCalendar.onSetTimeZone = widgetTimeZoneChanged;
oCalendar.changeEventTimes = true;
oCalendar.onEventChanged = widgetEventChanged;
oCalendar.onValueChanged = widgetValueChanged;
widgetValueChanged(new Date());
}

Add another function called “widgetEventChanged”.

function widgetEventChanged(eventId,eventObject){
var sReturn = "id " + eventId + "=\n";
for(var i in eventObject){
if(typeof(eventObject[i]) != “object”){
sReturn += i + ” = ” + eventObject[i] + “\n”;
}else{
oChildObject = eventObject[i];
var sChildReturn = “”;
var iNum = 0;
for(var j in oChildObject){
if(iNum > 0){
sChildReturn += “, “;
}
sChildReturn += j + “: ” + oChildObject[j];
iNum++;
}
sReturn += i + ” = ” + sChildReturn + “\n”;
}
}
alert(sReturn);
oCalendar.refreshScreen();
}

Now browse to our HTML page and refresh. If you hover over the time of an event you now see that you can drag and drop the event to another day. When you drag an entry to another day you must be sure to see the line before you drop it. (See Fig. 4) After you dropped it a modal floating window will appear with the new date shown at the top and a Time picker for you to select a new start- and end time. (See Fig. 5)

Fig. 4

Fig. 5

Click OK in the modal “Change” floating window to accept your times. Now you will see an alert with all the meta data of the entry with it’s new date and times. After you click OK in the alert the entry goes back to it’s date and time. This is obviously not what we want to happen but a good indication that we get what we want back. The alert comes from the “widgetEventChanged” function we just added to our code. We will change this function in part 2 of this tutorial to save to our back-end database instead.

Adding a new Calendar entry

I also wanted to add the capability to add a new entry. Let’s add a couple of lines to our “init” function again.

function init(){
oCalendar = dojo.widget.byId("dojoCalendar");
oCalendar.setTimeZones(mywidgets.widget.timezones);
oCalendar.selectedtimezone = dojo.io.cookie.getObjectCookie("DCTZ");
oCalendar.onSetTimeZone = widgetTimeZoneChanged;
oCalendar.changeEventTimes = true;
oCalendar.onEventChanged = widgetEventChanged;
oCalendar.setAbleToCreateNew(true);
oCalendar.onNewEntry = widgetNewEntry;
oCalendar.onValueChanged = widgetValueChanged;
widgetValueChanged(new Date());
}

Add a new function called “widgetNewEntry”.

function widgetNewEntry(eventObject){
var sReturn = "";
for(var i in eventObject){
if(typeof(eventObject[i]) != “object”){
sReturn += i + ” = ” + eventObject[i] + “\n”;
}else{
oChildObject = eventObject[i];
var sChildReturn = “”;
var iNum = 0;
for(var j in oChildObject){
if(iNum > 0){
sChildReturn += “, “;
}
sChildReturn += j + “: ” + oChildObject[j];
iNum++;
}
sReturn += i + ” = ” + sChildReturn + “\n”;
}
}
alert(sReturn);
//Call script to add to back-end db
oCalendar.refreshScreen();
}

Now go to our HTML page again and refresh. You now see another icon appear at the top of our Calendar. Click on the icon and we will see a new modal window for creating a New Entry. (See Fig. 6)

Fig. 6

Fill in the “Subject” and click OK. We get an alert with the object values we wrote in the fields.
As you can see in our code, the “widgetNewEntry” functions is very much like the “widgetEventChanged” function we added earlier. It simply alerts us with the object values it received. The new entry never get added to our calendar. The “oCalendar.refreshScreen()” call at the end of both the “widgetEventChanged” and the “widgetNewEntry” functions causes the Calendar to widget make a new call to our “widgetValueChanged” function. That function actually creates the same 3 entries every time so we never get our new entries. We need to update the back-end database for them to appear. Come back for part 2 of this tutorial.

In this first version of this Calendar widget I have made life simple by not being able to create multi-day or repeated entries. When I get some time and/or if somebody will help me with some code feel free to leave a comment/response below.

What else can we do

We can go back and forward one month, week or day by clicking on the arrows in the upper left- or right corners. If we click on the month name at the top of our Calendar we get a drop-down with all the months, so that we can quickly go to the month we want. (See Fig. 7) Clicking on the year will give us a drop-down with the previous two and the next ten years. If you want to go back to today’s date you can always click that icon.

Fig. 7

We can also change the default Calendar type. Add an attribute to the HTML of the widget with your preference. Default is “month”, but you can select “week” or “day” instead.

<div id="dojoCalendar" dojoType="mywidgets:calendar" calendarType=”week”></div>

Closing

I’m working on part 2 of this tutorial, where I will give code examples of how to update the back-end database using Ajax. Check back soon. I know there are many of you out there who would want to see other features in this Calendar widget. I would love to hear them. Leave a comment below.

This was my first attempt of creating a Dojo widget, and a tutorial for that matter, so please be gentle with your comments. I would really like to hear your input on the layout and/or code, whichever is your game.

 Print This Post
Thank you for reading this post. You can now Read Comments (66) or Leave A Trackback.