What’s New in Event Calendar 3.0

6 Sep

What’s New in Event Calendar 3.0

A Hesitant Upgrade

I’ve gone on record many times as a self-deprecating coder. I despise a lot of what I’ve created — especially the really early stuff. So when the newest version of SilverStripe finally reached its stable release, I was pretty well convinced that none of my antiquated, convention-breaking work would ever see the light of the polished and affection-worthy 3.0 world. For the most part, that has stayed true. Goodbye, DOM, hello GridField. Goodbye, Uploadify, hello, UploadField. Goodbye, ImageGallery, hello — well, something will come along, right?

Then a project came along that was to be built in 3.0 that required an event calendar. I looked for every possible way around using the tired old beast of a module, but when all was said and done, it made more sense to improve what was there than to reinvent the wheel.

Rebuilding EventCalendar for 3.0 was actually a nourishing and cathartic experience. It felt good to have a reason to clean up and enhance a tool that has offered so much utility to so many users. Along the way, a lot of new features were added — some entirely new ideas, and others improvements on old functionality.

Here are some of the highlights you’ll find in EventCalendar 3.0, now in the master branch on Github.

Rebuilt from the ground up. Almost.

It was overwhelming looking at everything that needed improvement in the EventCalendar codebase. Rather than take a hatchet to the existing code, I started with a blank slate and included only what was good in the old codebase. The result is a much cleaner architecture that takes advantage of the things that SilverStripe 3 does best.

Templates that stay out of your way.

The default templates for EventCalendar 3.0 are exceedingly minimal in design. Rather than have users fight with tangled HTML structures and hundreds of lines of CSS selectors, the module uses the templates to show off its features and functionality rather than offering up an opinionated layout and design.

An improved (Live)CalendarWidget

The old EventCalendar offered two types of calendar widgets. The first was a plain client side calendar that had no communication with the database. The second, $LiveCalendarWidget offered asynchronous communication with the database, allowing users to see which days had events. Since $LiveCalendarWidget was generated server side, it had severe latency problems.

The new $CalendarWidget template variable combines the best of both worlds. The widget now operates mostly client side, but polls the database in broad strokes to get information about many months at a time. If the information for the current month already exists in memory, it doesn’t run the request. The result is a much faster and user-friendly calendar.

Best of all, it does not use a third-party library. The JavaScript code is a 100% Uncle Cheese creation, and therefore much easier to maintain and enhance.


More i18n options

The last version of EventCalendar had  several challenges with localization and translation. The CalendarWidget did not translate easily, and there was a lot of trouble negotiating the cultural definition of the first day of the week. In the United States, it’s Sunday, but elsewhere it’s Monday.

This is all cleaned up in the new version of EventCalendar. There’s even a translatable field for “FIRSTDAYOFWEEK” to make things extra simple.

More intelligent handling of the default view

One of the challenges for any calendar is figuring out what to show on the default page. If the calendar is densely populated, maybe you want to show just this week. But what if it’s Friday? If the calendar is lightly populated, maybe you just show this month, but what if it’s the 27th? You can show the next 30 days, but if there’s nothing happening on the horizon, it can create a spooky place for a user to hang out.

The last version of EventCalendar addressed this by showing the next X number of events, with a limit into the future that could be defined in the CMS — i.e. “Show the next 10 events, but don’t go farther than six months from today.”

The new version of EventCalendar offers many more options:

  • Show a list of upcoming events: Show the next X events,  within the next Y months, where X and Y are both defined in the CMS.
  • Show this month’s events: If it’s August 27th, show August 1 – 31.
  • Show this week’s events, and fall back on this month: Show Monday-Sunday (or Sunday-Saturday), but if the set is empty, fall back on the month view.
  • Show today’s events, and fall back on this week: Show today, and if nothing is happening today, show this week.
  • Show this weekend’s events: If it’s Sunday, show the next weekend.

This highly granular level of control will help content editors deliver something truly meaningful to their users.

New widgets

In addition to CalendarWidget, there is now a $MonthJumper widget that allows a user to select a month and year from a pair of dropdowns.

Also, the new “QuickNavBar” include allows easy filtering of events for this month, week, weekend, or today.

Intelligent pagination

Pagination on a calendar never seemed appropriate to me. Who cares what’s on page 8 when you’re on page 2? But there are clear benefits to pagination when it comes to database overhead. To that end, the pagination in event calendar is more of an “infinite scroll” approach, where the user is offered a link for “more events” that append to the existing event list.

Further, each view has “next” and “previous” links that are context aware. When viewing a month, the “next month” and “previous month” links are available. When viewing a weekend, it changes to “next weekend” and “previous weekend,” etc.

Simple search

With the migration to InnoDB, we don’t have much in the way of fulltext search options without a thirdparty tool, but EventCalendar does support a simple search of events. Just append ?s=your+search+query to the URL.

More extensible

Every component of EventCalendar now offers itself up to the decorator pattern. Customize as you see fit.

What’s next

There are a ton of features that have yet to be implemented, including the import of ICS files, inclusion of remote feeds, and a calendar filter form. Further, there still needs to be a lot of testing for i18n users, and lang files need to be created and populated.

What you can do

Try it out, test it, and by God, submit those pull requests!

55 Responses to “What’s New in Event Calendar 3.0”

  1. Craftnet 07. Sep, 2012 at 7:04 am #

    I need to test.

  2. Ryan M 10. Sep, 2012 at 12:09 pm #

    Great work UC! I’ve used the EventCalendar module on several websites in 2.4. Cant wait to use the new and improved one!

  3. Ben 30. Sep, 2012 at 10:10 pm #

    Hey Uncle Cheese!

    Very nice. So do you ever post your mods in the list on SilverStripe.org?

    • unclecheese 03. Oct, 2012 at 10:43 am #

      I used to, but it’s too complicated to maintain. I’m waiting for 3.1 when all of that changes. For now, all my stuff is on Github. I don’t know too many active SS devs who use ss.org to post their work.

      • Ben 12. Oct, 2012 at 3:00 pm #

        Makes sense! I’m finding your comment true as I search around on Github. :-)

  4. Ross 07. Oct, 2012 at 1:22 am #

    Awesome to see an update to this!

    I am currently building a site for my student organization and I need some help. I am a bit of a noob to php and SS (I can read but have difficulty writing), but I always learn best by just throwing myself into a project, so any guidance would be very helpful!

    Anyway, the home page should have a combined container pulling both events and news/article items together. Is this possible, and if so how? I have tried altering the SS tutorial articlePage a few different ways with no success.

  5. Ian Walls 10. Oct, 2012 at 5:13 pm #

    Uncle Cheese,

    Thanks so much for your awesome and timely work on this module. I’m currently in the process of evaluating SS3, along with EventCalendar and a few other modules, for my institution’s website. So far, it’s very encouraging. As you requested, I’m submitting Pull Requests on GitHub for any of the issues I find that I can fix.

    Some of the issues out of my (current) depth surround Recursion and inclusion of ICS feeds, which you mention is a known issue). Is there any documentation on how these features are supposed to work? I’d love to help, but I don’t want to start down a wrong direction due to misunderstanding.

  6. Ben 12. Oct, 2012 at 3:11 pm #

    So I installed the calendar and everything is in good shape except the calendar widget isn’t appearing “out of the box”. The div with class “calendar-widget” is there, but it appears that the forTemplate() Requirements in CalendarWidget.php are not being loaded as I do not see the .js & .css files in the source of my page. I just pulled again from git a few minutes ago to ensure I had latest source code.

    On another note, the dates, times & recursion settings are pretty stellar… along with being able to load up a Google Cal feed. Rock on!

    • Ben 12. Oct, 2012 at 11:23 pm #

      Ah, found the problem. When pulling from Git you get a folder “EventCalendar” but need to change it to “event_calendar” when dropping it into your SilverStripe install so the resource paths match up correctly. Golden!

      • unclecheese 13. Oct, 2012 at 9:56 pm #

        Yup. That’s all going to change with the new module system in 3.1. No more guessing directory names.

        • Ben 19. Oct, 2012 at 12:41 pm #

          It’s the little things in life… :D

  7. saulius 23. Nov, 2012 at 4:05 pm #


    Was trying to use calendar with ss 3, however no luck.
    Live_calendar_widget was what i was trying to use.

    however calendar was not loaded just like the rest part like months,etc…

    I noticed that folder should be name event_calendar (as in includes it is like this).
    But still i miss something and don’t see the live calendar widget.

    • unclecheese 23. Nov, 2012 at 8:46 pm #

      Hi, Saulias,

      $LiveCalendarWidget doesn’t exist anymore. Use $CalendarWidget.

  8. Tim 02. Dec, 2012 at 8:05 pm #

    Hi Uncle Cheese,

    Great work on the re-write… I am having a couple of issues and have written a forum post on ss.org. If you have a chance could provide some advice? I added the link above to my post.

    Appreciate it and your hard work

    Cheers Tim

  9. Johannes 12. Dec, 2012 at 8:13 pm #

    This module is really awesome. I created the respective de.yml for i18n. I don’t have an account with github but if you mail me I will send it to you…

    Thanks again!

    • Johannes 16. Dec, 2012 at 1:53 pm #

      Quick steps for i18n and Silverstripe 3.0 (i.e. usage for german language [de, de_DE]):

      – lang/de.yml is broken (wrong content). It is a duplicate of de_DE.php. Instead it need to be like:

      STRING: ‘Value’
      STRING: ‘Value’

      Compare it to en.yml and add the missing strings.

      – for localization of the form elements (quick jump) your mysite/_config.php needs:

      setlocale(LC_ALL, ‘de_DE’);
      setlocale (LC_TIME, “de_DE.UTF-8″);

      Hopefully that helps others. It took me some time to get localization running… I will submit a complete de.yml to the author.

  10. Reece Cropley 13. Dec, 2012 at 6:27 am #

    Hello UC,

    I am new of SS but I was wondering if you could help me.

    I have installed your event_calender module and it is all working fine. What I would like to display the $CalenderWidget on the Home Page of the site, so on HomePage.ss.

    Is there any documentation or code that has instruction on how to do this. I assume you add a function to the relevant ~Page.php files and then call it in the ~Page.ss.

    Any help is greatly appreciated.

    • unclecheese 14. Dec, 2012 at 2:35 pm #

      Hi, Reece,

      Just create a function that returns the CalendarWidget() function to whatever template you’re working on.

      public function CalendarWidget() {
      return Calendar::get()->first()->CalendarWidget();

      • Reece Cropley 08. Jan, 2013 at 8:31 am #

        Hello UC,

        Thank you the code worked great, although …

        If I wanted to return a specific calender, would this be possible?

        I have multiple pages that use the Page.ss template. Each will have a child page of the ‘Calender’ type.

        I want to display this $CalenderWidget on the parent of this page (so the Page.ss).

        Im guessing it would be something like:

        public function CalendarWidget() {
        return Calendar::get([PageNameofParent?])->first()->CalendarWidget();

        but then I get stuck due to complete lack of SS knowledge.

        Any help is greatly appreciated.

        • Reece Cropley 08. Jan, 2013 at 8:54 am #

          I worked this one out!!

          Using the did it.

          Here is the code I used, for anyone else wanted to find this solution.


          • Reece Cropley 08. Jan, 2013 at 8:55 am #

            Using the loop Children function. Don’t know why it cut it out of my previous comment.

  11. Johannes 16. Dec, 2012 at 2:03 pm #

    Hi unclecheese!

    I submitted a complete de.yml via your translation upload form. Unfortunately I had to name it de.yml.php (.yml is not allowed).

    Also I would recommend to add an empty .yml without any values (strings only) file to lang dir …

    Thanks for your work!

  12. Joaquin Valdez 28. Dec, 2012 at 2:00 pm #


    I am having difficulty displaying the Calendar Widget. What am I missing? I downloaded the module from Github. Hmm….

    Thanks for any tips.

    • unclecheese 03. Jan, 2013 at 9:07 am #

      Hi, Joaquin,

      What difficulty are you having?

      • Joaquin Valdez 03. Jan, 2013 at 9:39 am #

        I see $CalendarWidget in the template but it doesn’t render on my Calendar page. the module folder name is event_calendar. Anything else I am missing?

        • unclecheese 05. Jan, 2013 at 11:33 am #

          Any JavaScript errors?

          • Reece Cropley 27. Aug, 2013 at 6:49 am #

            Hi, I have a similar issue.

            I have the $CalenderWidget in my HomePage.ss, there is nothing being displayed. No Javascript or CSS seems to be loading in either.

            Any ideas?

  13. Nitin Shah 05. Jan, 2013 at 10:28 am #

    I am using silverstripe 3.0.3 and Uncle Cheese’s
    EventCalendar module and am trying to add location to the
    calendarevent using the following tutorial.
    The above tutorial is for older version of the module and it seems
    the extendTable function no longer works in the new version. Kindly

    • unclecheese 05. Jan, 2013 at 11:33 am #

      Yeah, those docs are for the 2.0 version. That API no longer exists. Just use a decorator.

      • Nitin Shah 07. Jan, 2013 at 3:01 pm #

        Can you please guide me to a tutorial or an example to understand how decorator is used

  14. Nitin Shah 08. Jan, 2013 at 4:06 pm #

    This is what I did:

    Created a new page CalendarDetails.php in mysite/code with the following code:

    ‘City’ => ‘Text’,
    ‘Ticket’ => ‘HTMLText’,

    public function updateCMSFields(FieldList $fields) {
    $fields->addFieldToTab(“Root.DATESANDTIMES”, new TextField(“Venue”));
    $fields->addFieldToTab(“Root.DATESANDTIMES”, new TextField(“City”));
    $fields->addFieldToTab(“Root.DATESANDTIMES”, new TextField(“Ticket”));


    But when I try to add date & time in a calendar event i get a blank page. I am not sure where am I going wrong. Kindly help…

  15. Nitin Shah 08. Jan, 2013 at 4:10 pm #

    For some reasons the above code did not post as pasted.
    following is the code I have in CalendarDetails.php

    class CalendarDetails extends DataExtension
    static $db = array(
    ‘Venue’ => ‘Text’,
    ‘City’ => ‘Text’,
    ‘Ticket’ => ‘HTMLText’,

    public function updateCMSFields(FieldList $fields) {
    $fields->addFieldToTab(“Root.DATESANDTIMES”, new TextField(“Venue”));
    $fields->addFieldToTab(“Root.DATESANDTIMES”, new TextField(“City”));
    $fields->addFieldToTab(“Root.DATESANDTIMES”, new TextField(“Ticket”));

    Kindly suggest

  16. Nitin Shah 10. Jan, 2013 at 4:48 am #

    Have this working now. This is what I did:

    Created a new page CalendarDetails.php in mysite/code/ with the following content:
    ‘City’ => ‘Text’,
    ‘Ticket’ => ‘HTMLText’,

    static $has_one = array (
    ‘Event’ => ‘CalendarEvent’

    public function updateCMSFields(FieldList $fields) {

    $fields->push(new TextField(‘Venue’, ‘Venue’));
    $fields->push(new TextField(‘City’, ‘City’));
    $fields->push(new TextareaField(‘Ticket’, ‘Ticket’));

    and in _config.php added the following line:

    Object::add_extension(‘CalendarDateTime’, ‘CalendarDetails’);

  17. Warren 27. Feb, 2013 at 10:55 am #

    I’m attempting to use this module, but it doesn’t seem to be working for me. I’m on Silverstripe 3.0.3, and the module appears to install fine – dev/build works, and I can add Calendar pages and Calendar Events. The problem is if I click ‘Add Calendar Event Time’ on a Calendar Event, or ‘Add Calendar Announcement’ on a Calendar page – I get ‘Internal Server Error’.
    I’m having difficulty getting any further details regarding the problem, too. Any idea what it could be?

    • Warren 27. Feb, 2013 at 11:58 am #

      Realised it was because I was missing the Silverstripe TimePickerField. I had no idea that was a dependency. Was it mentioned somewhere, and I just missed it?

      • Doyle 26. Apr, 2013 at 6:30 am #

        I’m new to silverstripe and also receiving the internal server error. Warren can you elaborate on what you did to fix it?

  18. PinkP 09. Apr, 2013 at 4:09 pm #

    I have a strange issue, that the JS files are only being added to one page type. So if I put $CalendarWidget in my Page.ss code the Calendar is currently only showing on one page which happens to be “MyCustomPage.ss”. On all the other pages of any type the scripts are missing and it does not show.

  19. PinkP 09. Apr, 2013 at 4:15 pm #

    Actually scratch that!! My mistake, sorry

  20. PinkP 10. Apr, 2013 at 7:13 am #

    Quick question, I have an event in November, Its currently April.
    My config is set to “Show a list of upcoming Events”
    Set to show the next “12” months.
    But when I go to my calendar page its says:
    “Upcoming Events
    There are no events.”
    This should show my November event? correct?

    It will show events for May, but not November. (unless I got to that month)

  21. Kyley23 01. May, 2013 at 12:47 pm #


    Thanks for the great work on the event calendar. I would like to add the LiveCalendarWidget.ss in my Sidebar. Could you tell me how to get it there. I’m a noob so please explain in great detail. Thanks in advance.

  22. Carsten 02. May, 2013 at 8:23 am #

    Hi unclecheese,

    i am using the latest version of the event calendar modul with my SS3.1.0Beta3 install. Unfortunately there are some problems with the recurring events. The Checkboxfield titles are not populated correctely.

    Something went wrong with “getTitle” in RecurringDayOfWeek.php.

    I have put some screenshots in the silverstripe forum: http://www.silverstripe.org/all-other-modules/show/23620

    Can you help, please?

  23. Interalianz 14. May, 2013 at 12:13 am #

    Hello Warren,
    I have stumbled on the same problem as you had. Have you found any fix for this matter? Look forward to it. Thanks

  24. Ruth 21. May, 2013 at 8:57 pm #

    Hi Uncle Cheese,

    I want to use your event calendar module for a school website I’m currently work on. One of the client’s requirements is that when the Calendar is in week view, it displays much like google calendar or outlook. I’m thinking that I could do this if I can get a GroupedList (then just add some fancy css for the right display).
    I’m not sure whether to decorate EventCalendar and write a new function in there getting the Events for the week and outputting them in a GroupedList, or if there is a better way to do it.
    Any ideas?


  25. beni 30. May, 2013 at 2:39 pm #

    Hey unclecheese,
    thanks a lot for the new event calendar.
    Everythings works fine in Firefox, IE Opera and Safari but in Googles Chrome, nothing is loading. Just a white page shows up.
    Do you have an idea to figure out, whats wrong?


    Cheers Ben

    • beni 31. May, 2013 at 4:58 am #

      When I delete the ‘$CalendarWidget’ the whole page including the upcomming events are displayed.
      Any idea?

  26. Brendan 10. Jul, 2013 at 9:50 am #

    Hi Uncle Cheese –
    Thank you so much for making your plugins available. I’m having some trouble with the calendar plugin.

    In the function getEventList in Calendar.php, whenever push or merge are called, it cleans out the data that existed in $events and returns a null set. This causes the calendar to display “no events” every time.

    When I have this function return $events and not $eventList, it returns data and the plugin works – with the obvious exception that Announcements and Recurring Events are not included.

    Any help would be hugely appreciated.

    • Steve 20. Jul, 2013 at 1:35 am #

      Hi Brendan / Uncle Cheese

      I have the same problem – did you manage to get to the bottom of it?

  27. Brendan 27. Jul, 2013 at 12:01 am #

    Haven’t had any success yet. Any luck on your end?

    • Steve 03. Aug, 2013 at 10:16 pm #

      Hi Brendan
      I changed the return value to:
      return $eventList; //$this->EventList_cache = $eventList;
      Since I havnt yet figured out how to turn on eventlist caching as per the very beginning of this function I wondered whether this might be impacting. It seems to be working – announcements are displaying along with events. Be interested to know if this works for you.

  28. Sabin Farley 01. Aug, 2013 at 11:48 am #

    Hi, can someone post some help on how to implement event-calendar? I mean:

    // Page.ss


    And all the other templates? When i click on a date, it shows Page.ss. What template event is using?

    Docs would be appreciated Uncle… :0


  29. Thomas 10. Dec, 2013 at 4:14 am #

    Hello Aaron

    I like the event module, it is really awesome.
    Now I would like to add category to event. Could you guide to do this, I am pretty new with SS.

  30. Angela 16. Dec, 2013 at 6:03 pm #

    Using latest Event Calendar with latest SS.

    Events created show up when I go to the URL (event page)- but they are not showing up in the event page (calendar Page)for upcoming events.

    I had everything working fine on the dev website. But not working on the live site…exact same files etc.

    I can’t figure this out. I look forward to your advice.

  31. Ruth 14. Jan, 2014 at 10:52 pm #

    Hi Uncle Cheese,

    Has event filtering been added to the 3.1 version of your event calendar module?
    I’ve extended Calendar and CalendarEvent so I can add extra fields and a filter form and I’m half way through writing my own, but having some difficulties.


  32. Thomas 21. Jan, 2014 at 10:14 pm #

    I am trying to listing upcoming events in footer.ss file. Below is code i am using, Unfortunately it list only recurring CalendarEvent,

    * Class EventsControllerExtension
    class EventsControllerExtension extends Extension
    * @param $limit
    * @return mixed

    public function MyUpcomingEvents($limit){
    return Calendar::get()->First()->UpcomingEvents($limit);


    — config.php —

    if (class_exists(‘ContentController’)) {
    Object::add_extension(‘ContentController’, ‘EventsControllerExtension’);

    — footer.ss ———

    $Title – $StartDate


    Could somehelp me to list both non-recurring and recurring events.