What’s New in Event Calendar 3.0
6 Sep
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!
Awsome.
I need to test.
Thanks
Great work UC! I’ve used the EventCalendar module on several websites in 2.4. Cant wait to use the new and improved one!
Hey Uncle Cheese!
Very nice. So do you ever post your mods in the list on SilverStripe.org?
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.
Makes sense! I’m finding your comment true as I search around on Github.
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.
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.
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!
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!
Yup. That’s all going to change with the new module system in 3.1. No more guessing directory names.
It’s the little things in life…
Hi,
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.
Hi, Saulias,
$LiveCalendarWidget doesn’t exist anymore. Use $CalendarWidget.
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
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!
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:
de:
Calendar:
STRING: ‘Value’
[...]
EventList.ss:
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:
i18n::set_locale(‘de_DE’);
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.
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.
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();
}
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.
I worked this one out!!
Using the did it.
Here is the code I used, for anyone else wanted to find this solution.
$CalendarWidget
Using the loop Children function. Don’t know why it cut it out of my previous comment.
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!
Hello!
I am having difficulty displaying the Calendar Widget. What am I missing? I downloaded the module from Github. Hmm….
Thanks for any tips.
Joaquin
Hi, Joaquin,
What difficulty are you having?
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?
Thanks!
Any JavaScript errors?
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.
http://ss2doc-v2.ernie.silverstripe.com/old/recipes:extending_the_event_calendar
The above tutorial is for older version of the module and it seems
the extendTable function no longer works in the new version. Kindly
suggest…
Yeah, those docs are for the 2.0 version. That API no longer exists. Just use a decorator.
Can you please guide me to a tutorial or an example to understand how decorator is used
This is what I did:
Created a new page CalendarDetails.php in mysite/code with the following code:
‘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”));
}
}
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…
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
Have this working now. This is what I did:
Created a new page CalendarDetails.php in mysite/code/ with the following content:
‘Text’,
‘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’);
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?
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?