SuperSatellite ||

With the release of dotCMS 1.6 came one of the more anticipated new features in recent months, their new “social” calendar system. This calendar represented a noted improvement over the previous event portlet (though the event portlet still exists for some additional functions, like scheduling and managing conferences, etc). This new calendar makes use of a portlet to manage the system in the backend similar to the old event system, and builds out on the front end through a combination of Velocity, .vtl files, and some layout bits. It also creates event entries as content in a structure, so that it can be queried and pulled no different from any other content in the system (note that you might want to make sure that you don’t currently have structures called “Event,” “Building,” or “Facility” already, as it will want to make them if you are upgrading. New installs obviously don’t need to worry about that).

If you want to take a look at the calendar first hand, you can see the example that is up at the demo site, at http://demo.dotcms.org/calendar/. To access the back end, login to the admin console by going to http://demo.dotcms.org/c and plug in the user ID test@dotcms.org and the password test. In there, you’ll see the tab for “Calendar” that you can click on that will take you to a similar, but stripped down looking version of the calendar. I’ll be using the demo’s site front and back end when describing features, and in the video below.

Part of the major improvement with this system is that as opposed to the event portlet, it provides true calendar functionality, whereas the event system provided more of a list view, regardless of how you tackled it. This calendar is very AJAX (Asynchronous Javascript And XML) heavy, and thus can present an accessibility problem by default, but since all calendar events are simply structured content, you can very easily create a standard HTML based variant for users with special screen needs (and really, do you know a calendar that is truly 508 compliant out of the gates in the first place?). Storing events as structured content gives you an extra layer of control over the presentation of those events, control that is unmatched in other calendar systems. The interface itself is fairly smooth and intuitive, without a lot of tricky links, or confusing navigation (I’m look at you, Active Data Calendar). Though fairly simple in terms of usage, the fact that everything just works, and works like it should, carries a high value. And in keeping it simple, it is actually a very powerful little tool.

The calendar itself supports all the traditional types of functionality: Time, date, place, multi-day, all-day, list-week-month views, RSS feeds, detail view and searching. Additionally, you can add events from the front end (if enabled), tag events, filter by tag(s), filter by calendar(s), attach files and images, provide detail popups, and provide automatic integration into Google Maps. Using categories, you can effectively create completely self contained calendars of different events, and one event can exist within multiple calendars simultaneously. All in all, it’s a pretty nice feature set. It will also save you trying to integrate with a third party calendar for your business that would require and supply it’s own login, back end, and functionality challenges. With some CMS (Content Management System)’s, they might have a calendar, but it’s an additional install, plugin, or module that you have to manage. dotCMS includes the calendar out of the box (still free), and if you don’t want to use it, you just don’t display the page in the back end, so there’s no extra labor involved. Other enterprise CMS’s come with built in calendars, but you’ll pay dearly for those packages.

The primary challenge right now is that if you do not load the starter site, or are upgrading from 1.5.x, you don’t have all the front end files (not to be confused with the back end admin portlet for the calendar, which is totally there whether you upgraded or installed fresh and will be in need of no special attention) that you’ll need to display the calendar (this will be changing soon, however, as I understand they plan on bundling all that with the CMS so you’ll have it if you upgrade or don’t use the starter site). What I did to solve this problem was to go to the demo site, and lift all the files out of their /calendar directory. This had one disadvantage: all the files are hardcoded to the /calendar directory. So, what I have done is taken all these files, and modified them so that you can upload them into your system, and they will adapt to wherever you want to put it. Just download this zip file which contains everything needed to display the calendar to your visitors, extract it, and upload it either with the multi file uploader or over WebDav. The only other thing you need to do then is make a page in whatever folder that will be your calendar, let’s just call it index.dot, and place the following code into a piece of web page content that you use on the page:

This will load and fire off all the rest of the Velocity templates. There are two CSS (Cascading Style Sheets) files (grids-min.css and reset-min.css) that are needed because the calendar was designed with Yahoo Grids, and those styles make sure everything lines up properly. A third CSS file (cal-base.css) that is included is the base starter site CSS, and you could remove it as necessary to meet your styling needs, but I included it at the moment for the sake of appearance reproduction. All three CSS files are included in the zip file above already, and you’ll see them referenced in velocity/calendar.vtl. Using the files from the zip file, and the content above, you now have a calendar that you can move to a new directory should the need arise, or should you simply not want it in /calendar. If you move it, just make sure you change the /absolute/path/to in your piece of content to point at the new location of the load-calendar.vtl file. You could even make that portion dynamic if you wanted to, simply by removing the first line from load-calendar.vtl, and adding it to the content, making it:

The only reason I didn’t do that by default was so that way you never have to copy and paste that set() from here (since I can’t “include” a piece of content in the zip file), and to keep the information going into the content item that tells it to make the calendar as simple as possible. Odds are, once you place the calendar, you won’t be moving it around anyway. But this way you don’t have to change all the paths yourself, and you aren’t locked into using /calendar.

Below, I have included a brief overview of the new calendar, so that you can see some of the functionality and how it all comes together.

Download the customized dotCMS social calendar front end files (.zip, 131KB)