Calendaring with Plone 3 for Education

Erik Rose

December 2009

(For more resources on Plone, see here.)

The techniques in this article are applicable in many organizational schemes. We present one common arrangement as an example: a top-level folder where visitors can browse the highest-profile events on the site.

Show events on a calendar

Plone's out-of-the-box Events folder provides a basic way to find events: it displays them in a chronological list broken into pages of 20 each. While fine for simple cases, this is cumbersome for visitors who want to look at events for a certain future date. Part of our goal is to set up a monthly calendar to make this common case easy:

Plone 3 for Education

Our first step toward the monthly calendar is to replace Plone's stock Events folder. Out of the box, it holds individual events along with a summarizing collection that acts as its front page. If you don't need a drill-down way of browsing your events by subject—for example, if you have so few that they all fit comfortably on a calendar like the above—you can leave the default Events folder in place. Otherwise, follow the instructions below to replace it with a standalone collection; this will interact better with Plone's navigation portlet, which we will use to implement the drilldown browsing. If you choose to stick with the stock Events folder, you may still wish to adjust the criteria of its inner collection as described in the following:

  1. First, delete the Events folder.
  2. Replace it with a new collection called "Events". Give it an Item Type criterion, and tell it to pull in everything of the type Event.

    Plone 3 for Education

    The original Events collection had a Start Date criterion to keep past events off the page. We won't need that, since the calendar view we are about to apply keeps past events tucked away implicitly—and we do want the ability to see old events when we navigate to previous months.

    The original collection also had a State criterion that limited it to showing published events. If you need only to hide unpublished events from visitors, then you can dispense with this: the internal search routines used by the collection will naturally show only what the current user has permission to see.

    Preventing a common contributor error
    Often, a less proficient contributor will add an event, see it on his or her own calendar, and move on, neglecting to publish it. Adding the State criterion can serve as a reminder, preventing the event from appearing until properly published. The downside is that it makes the calendar useless for intranets: Events that aren't publicly visible will never show up. But if you have no non-public events to list, consider recreating the State criterion.

  3. If you never want to show access-controlled events on the main calendar add a State criterion limiting the collection to published items.

The Events collection is finished. Next, we apply a monthly calendar view to our data.

Meet Plone4Artists Calendar

Plone's built-in event listings are rather basic. We need to do special tricks with collections and default views just to sort them in chronological order. At best, this is several extra clicks, and, at worst, it can confuse your less technical content contributors. A third-party product called Plone4Artists Calendar makes this easy and gives us several other capabilities to boot.

Plone4Artists Calendar is the current frontrunner in the Plone calendaring space. It provides...

  • Daily, weekly, monthly, and a few other calendar-like views for folders and collections
  • Rudimentary recurring event support
  • Hooks for pulling events from other systems in realtime, with a bit of coding

Don't let the name "Plone4Artists" put you off if you aren't an artist; though the Plone4Artists suite of products came out of a project to provide artist community web sites, there's nothing particularly artist-centric about them. In fact, there has been discussion about renaming them.

The runner up: CalendarX
The other Plone calendar worth considering is CalendarX, whose most recent release at the time of this writing is 0.9.1. 0.9.0 was the first update to the product since since 2005 and represents a major refit. Its ancient data-modeling internals were replaced with a modern Archetypes implementation, and one no longer needed to venture into the ZMI to do simple configuration. Speaking of configuration, CalendarX exposes a lot of it: 6 tabs packed with options for tweaking calendar format, event display, widgets, and more. There are 57 options alone regarding its CSS cosmetics. If you need a specific look and aren't comfortable writing your own CSS or template code, CalendarX may be the ticket.
However, be warned that CalendarX has a history of being sporadically maintained. It lacked Plone 3 compatibility for a long time, and compatibility work began only when a group of stranded Plone 2.5 users at Pennsylvania State University put a week of development work toward it. Its internals still hold a lot of legacy that may prove difficult to maintain as Plone evolves.
Plone4Artists Calendar, on the other hand, is a simpler product—both inside and outside and with all the good and bad that entails—and the winds of further community effort are blowing in its direction. Its maintainable design and the willingness of developers to work on it make it the solution least likely to leave you stranded; this is why it is our recommendation in this article.

Install Plone4Artists Calendar

Before we can make use of its views, we need to install the product—actually, two products and several supporting packages. Weave these directives into the proper sections of your buildout.cfg...

...other directives...
eggs =
...other eggs here...
...other directives...
zcml =
...other ZCML listings here...
# Plone4Artists Calendar doesn't support Plone 3.3's
auto-ZCMLloading as of 2.0a2.
recipe = plone.recipe.distros
urls =
calendaring-0-4-0.tgz buildout, restart Zope/Plone, and install the Plone4ArtistsCalendar (p4a.plonecalendar) and Recurring Events (p4a.ploneevent) products in Site SetupAdd-on Products.

Now that everything is installed, we apply a monthly calendar view to the Events collection:

  1. Navigate back to the Events collection, and choose Calendar from the new Sub-types menu.
  2. If it isn't already selected, choose Month view from the Display menu.

Presto—we have a monthly calendar showing every event on our site.

(For more resources on Plone, see here.)

Exclude trivia from the site-wide calendar

Of course, we don't really want every event; for any but the smallest sites, this would quickly crowd the calendar to uselessness. We would like to limit the site-wide calendar to the most noteworthy events, omitting specialty items like assignments that apply to only one in a hundred people. (For that matter, typical visitors won't think of assignments as "events" at all and would be surprised to see them on the calendar.) There are several ways to indicate an event's noteworthiness without resorting to much coding:

  • Copy the Event type to make a new but identical type called something like "Site-Wide Event", either by writing a product or by simply copying and pasting within the portal_types tool, accessed through Site SetupZope Management Interface. Have the Events collection find only instances of the new type. When considering this approach, note that an Events portlet will show only events of the original type. A partial workaround is to use a Collection portlet instead.
  • Assign certain folders in the site to hold noteworthy events, then gather them with a collection: a Location in site criterion easily brings together the contents of multiple folders.
  • Apply a single keyword, such as "Site-Wide Event", to worthy events. Have the Events collection pull in only events tagged with that keyword.
  • Promote many keywords to the site-wide calendar. Whether you can get away with this depends on your information architecture and the size of your organization. However, if your keywords are used for anything other than contrived purposes like this, your content contributors will likely run into places where one of the promoted keywords is semantically appropriate while showing the event on the site-wide calendar isn't.

Choose one of the above filtering approaches based on the needs of your site, and add a criterion to your Events collection to match. If in doubt, use the "Site-Wide Event"–keyword approach.

Build a browsable hierarchy with collections

Even with the earlier pruning, a large school may still have too many events to comfortably view. For example, finding the next few months' varsity football games could be tricky when they're mixed in with all the other sporting events. To make this easier, we build a tree of collections so visitors can drill level-by-level into your taxonomy, homing in on their goal. As they descend, the monthly calendar view continually pares itself down until they reach a number of events they can comfortably comb through:

Plone 3 for Education

To add one of these drill-down categories, follow these steps:

  1. Add a collection inside the Events collection, called, for example, "Sports". Turn on Inherit Criteria so this collection becomes a paring down of the one containing it. Save.
  2. To make the monthly calendar view persist while visitors drill, choose Calendar from the new collection's Sub-types menu.
  3. Add a Categories criterion to the collection to narrow the selection of events. The figure below shows one way to fake a hierarchy of keywords: the Sports collection displays events tagged with any of the two sports-related keywords.

    Plone 3 for Education

Continue adding second-level and lower sub-collections until the lowest ones all show a manageable number of events.

Separating security from information architecture
Note that the actual location of events in the site is independent of where they are presented to the user. This has important security implications: you can use Plone's location-based access control—setting per-folder roles using the Sharing tab—without having to give anyone total write access to an all-encompassing Sports folder. This lets you treat security according to your organization's administrative structure while insulating site visitors from it.

Embracing local security
A common error made by new Plone administrators is to assign a lot of privileges through the checkboxes in the Users and Groups Administration control panel. In practice, these should hardly be used at all. Though prominently placed, they grant privileges across the entire site, and not many people need such power. We recommend using them only to give Manager rights to the sort of people who have root access to the web server: a small cadre of trusted webmasters and sysadmins.
Instead, assign most permissions through the Sharing tabs on individual folders. And, when information architecture doesn't specify otherwise, structure your folder hierarchy to take advantage of the fact that items inherit the permissions settings of their containers. Where information architecture does conflict with this, there is an easy solution: just turn off the Sharing tab's Inherit Permissions checkbox and start your role assignments from a blank slate.

Reorder subfolders the hard (but only) way

Controlling the order in which a collection's subfolders appear is often desirable—for example, to maintain alphabetization—but there is no obvious way: subfolders always appear in order of their creation, and there are no reordering controls on the Subfolders tab. However, changing the order is possible, if somewhat tedious. First, visit the Zope Management Interface at the level of the outer collection; for example, visit to reorder the subfolders of the top-level Events collection. Next, select an item or items you would like to move lower in the ordering, cut them, and paste them. Return to a Plone view of the collection, and notice that they have in fact moved. Continue this manual sorting until everything is properly ordered. It's painstaking, but it works.

Incidentally, we have filed an enhancement request at Check that ticket to see whether the situation has been improved by the time you read this.

Keep keywords clean with Plone Keyword Manager

As the number of keywords in your site increases, keep the third-party Plone Keyword Manager ( in mind. Keywords in Plone are site-wide and, like all uncontrolled vocabularies, need a bit of gardening to remain consistent. Keyword Manager lets you merge synonymous keywords without having to manually troll through the whole site. It is a well-maintained product in wide use, so the risk of it breaking your site is slim.

Plone 3 for Education

Tips for event contributors

Of course, a calendaring system is no good without a good supply of events. Spare yourself the webmaster bottleneck by farming out event creation to other contributors. Just remember to give them these three tips so your site-wide calendar (and any others you make) are consistent and easy to understand:

  • Name events globally. It makes sense for the president of the Parcheesi club, adding a night of Parcheesi-filled fun within his own club folder, to name it "Open Play". However, that title doesn't work so well on the site-wide calendar: play of what? Make sure your event contributors understand that "Open Parcheesi Play" is a better title. In addition to making the calendar clear, it will also net visitors more hits when they search for "Parcheesi".
  • Keep dates out of titles. Because no one can ever get enough Parcheesi, the club offers weekly sessions. It can be tempting, while working in the club's own folder, to differentiate the sessions by adding dates to their titles: "April 15 Open Parcheesi Play". This, of course, is redundant when displayed on a calendar. Steer your contributors away from this practice by showing them how to apply a monthly calendar view even to event folders within clubs.
  • Remember to apply keywords. Of course, none of this site-wide event aggregation will work unless contributors add keywords to their events. Fortunately, the default event-editing template helps us by prompting for keywords on its main tab, but a little personal encouragement can't hurt either. Also, remember to teach contributors about the "Site-Wide Event" keyword if you decided to use that filtering method.

Represent recurring events

The Recurring Events product, which comes in the p4a.ploneevent package, adds the beginnings of repeating event support to Plone, and though it's a bit buggy and in need of user interface work at the moment (such that I wouldn't recommend it for a production site), its underpinnings are well designed. An event can repeat every so many days, weeks, months, or years, and it can stop repeating on a certain date or after some set number of occurrences. Repetition is controlled through a new Recurrence tab in the event editor:

Plone 3 for Education

In the above, setting Repeats every to 2 would mean "repeat every 2 weeks," with 1 meaning "repeat every week". Count means "stop repeating after this many occurrences". If you provide both a Range and a Count, the most limiting one wins. And although the present interface doesn't support more complex patterns like repeating every Tuesday and Thursday, the underlying dateutil library does—so there's plenty of room for future improvement.

Spotty support for showing recurrences

As of p4a.ploneevent 0.7.2, event recurrences appear on Plone4Artists Calendar views but not in standard event folder listings. Uninstalling and reinstalling Calendar quietly breaks even the former, so, if you do attempt to use event recurrence, don't plan on reinstalling.

When viewing a single event, the recurrence is rendered in plain English: "Apr 01, 2009 from 10:55 PM to 11:55 PM Every 2 weeks for 5 times until Mar 02, 2010." Unfortunately, the first-ever date of the event always appears instead of the date of its nearest future occurrence. Also, the iCal and vCal downloads are not yet aware of recurrences.

For these and various other reasons, it's probably best to wait until recurring event support is more complete before using it in production sites.


In this article, we have...

  • Used Plone4Artists Calendar and collections to gather important events onto a central calendar
  • Built a keyword-driven, drill-down navigation scheme for homing in on events by topic
  • Made the presentation of events independent of their actual location in the site, letting you take advantage of security inheritance parallel to your organizational structure
  • Learned the three things to teach event contributors that will keep your calendar users happy
  • Explored the state of Plone4Artists Calendar's recurring event support



Further resources on this subject:


You've been reading an excerpt of:

Plone 3 for Education

Explore Title