Google Calendar Events, 0.5 beta

Version 0.5 has now been released! Please take a look at this post for details on the release.

Over the last couple of weeks, I managed to find a little time to spend developing my WordPress plugin, Google Calendar Events. I’ve implemented a couple of features / enhancements that I’m quite excited about, as I think they really add a lot of flexibility.

These features also encompass a large proportion of the requests I have had over the last few months, and should prevent a lot of the inelegant hacks that have been required to do various things in the past.

I have had to make some fairly significant changes to the code in order to implement the features, so I don’t want to release 0.5 straight away, just in case I’ve introduced (or re-introduced) any bugs. Any feedback on this beta ‘release’ would be greatly appreciated!

You can download the beta from the plugin directory (choose the ‘Development Version’). The beta version will still say it is 0.4.1 in the WordPress plugin admin, as I haven’t changed the readme file yet.

Here’s a quick explanation of the new stuff / changes:


Event Display Builder

I’m quite pleased with this feature, it’s pretty snazzy! I can’t really take much credit for it though, much of the concept and code behind it is ‘borrowed’ from the WordPress shortcode API.

The event display builder allows you customise the information that is displayed for each event in the grid tooltips or list. This is done by specifying a HTML structure containing shortcodes that will be replaced by the relevant event information when the grid or list is generated.

A brief explanation of the available shortcodes is below. I’ll write a more in-depth guide to these before release.

Shortcode Explanation
[event-title] The title of the event (possible attributes: html, markdown)
[start-time] The start time of the event. Will use the time format specified in the feed settings (or if this has been omitted, the default WordPress time format)
[start-date] The start date of the event. Will use the date format specified in the feed settings (or if this has been omitted, the default WordPress date format)
[start-custom] The start time / date of the event. Will use the format specified in the format attribute (possible attributes: format)
[start-human] The difference between the start time of the event and the time now, in human-readable format, such as ’1 hour’, ’4 days’, ’15 mins’
[end-time] The end time of the event. Will use the time format specified in the feed settings (or if this has been omitted, the default WordPress time format)
[end-date] The end date of the event. Will use the date format specified in the feed settings (or if this has been omitted, the default WordPress date format)
[end-custom] The end time / date of the event. Will use the format specified in the format attribute (possible attributes: format)
[end-human] The difference between the end time of the event and the time now, in human-readable format, such as ’1 hour’, ’4 days’, ’15 mins’
[location] The location of the event (possible attributes: html, markdown)
[maps-link]…[/maps-link] A link to Google Maps. Utilises the information in the location field to search Google Maps. The link text should be specified between the opening and closing shortcode tags (possible attributes: newwindow)
[description] The description of the event (possible attributes: html, markdown, limit)
[link]…[/link] A link to the Google Calendar page for the event. The link text should be specified between the opening and closing shortcode tags (possible attributes: newwindow)
[link-path] The raw URL to the Google Calendar page for the event
[feed-id] The ID of the feed from which the event comes. Useful for constructing feed specific CSS classes
[feed-title] The title of the feed from which the event comes
[timezone] The timezone of the feed from which the event comes

In addition to the above shortcodes, there are also logical / conditional shortcodes. Anything you enter between the opening and closing tags of the following shortcodes (including any further shortcodes!) will only be displayed if its conditions are met:

Shortcode Condition
[if-all-day]…[/if-all-day] The event is an all-day event
[if-not-all-day]…[/if-not-all-day] The event is not an all-day event
[if-title]…[/if-title] The event title is not empty
[if-description]…[/if-description] The event description is not empty
[if-location]…[/if-location] The event location is not empty
[if-tooltip]…[/if-tooltip] This is to be displayed in a tooltip
[if-list]…[/if-list] This is to be displayed in a list
[if-now]…[/if-now] The event is taking place now (after the start time, but before the end time)
[if-not-now]…[/if-not-now] The event is not taking place now (may have ended or not yet started)
[if-started]…[/if-started] The event has started (even if it has also ended)
[if-not-started]…[/if-not-started] The event has not started
[if-ended]…[/if-ended] The event has ended
[if-not-ended]…[/if-not-ended] The event has not ended (even if it hasn’t started)
[if-first]…[/if-first] The event is the first of the day
[if-not-first]…[/if-not-first] The event is not the first of the day

The possible attributes mentioned in the above tables are explained here:

Attribute Values Explanation
html true or false Whether or not to parse HTML that has been entered in the relevant field.
markdown true or false Whether or not to parse Markdown that has been entered in the relevant field. This requires PHP Markdown to be installed
limit A positive integer The word limit for the field (it probably isn’t a good idea to use this in conjunction with the html attribute, as it could cause tags to become unbalanced)
format A PHP date format string The date / time format to use
newwindow true or false Whether or not the link should open in a new window / tab

Here’s an example of the sort of thing you could enter in the event display builder field:

<div class="gce-tooltip-event">[event-title] ([feed-title])</div>
[if-not-all-day]<div><strong>Time:</strong> From [start-time] until [end-time]</div>[/if-not-all-day]
[if-all-day]<div><strong>Time:</strong> All day</div>[/if-all-day]
[if-location]<div><strong>At: </strong> [maps-link newwindow="true"][location][/maps-link]</div>[/if-location]
[if-description]<div><strong>Description:</strong> [description html="true"]</div>[/if-description]

This would result in a tooltip something like the following:

Event display builder example

Notice that the event display builder has allowed the following things, that were previously difficult / impossible:

  • Differentiation between all-day and ‘normal’ events
  • Display of feed titles
  • Parsing of HTML entered in Google Calendar fields
  • Linking to Google Maps
  • Customisation of where information is displayed (start and end time on same line, for example)
  • Ability to specify your own HTML and CSS classes, allowing for more styling possibilities

Obviously, this is a little more complex than the ‘old’ display options from current versions of the plugin and may take a little getting used to, especially for those without any knowledge of HTML. For this reason (and for backwards compatibility) the plugin still has the old display options available.


Flexible Retrieval Date / Time Range

In previous versions of the plugin, there wasn’t much flexibility in the date / time range of when events would be retrieved from the Google Calendar feed. The new options offer much more control, making the following ranges simple to set up:

  • This month
    • Retrieve events from: Start of this month
    • Retrieve events until: End of this month
  • The past
    • Retrieve events from: The beginning of time
    • Retrieve events until: Now
  • The future
    • Retrieve events from: Now
    • Retrieve events until: The end of time
  • The next 7 days (including today)
    • Retrieve events from: 00:00 today
    • Retrieve events until: Number of days (7)
  • 1 hour ago until 1 hour from now
    • Retrieve events from: Number of seconds (-3600)
    • Retrieve events until: Number of seconds (3600)
  • Events currently occuring
    • Retrieve events from: Now
    • Retrieve events until: Now
  • Today until Christmas Day 2021
    • Retrieve events from: 00:00 today
    • Retrieve events until: Specific date (1640390400)

These are just a few examples, of course there are lots of other possibilities. Note that it may be necessary to reduce the cache duration when using smaller time ranges, to ensure that the plugin remains ‘up-to-date’.


Error Message

The error messages that the plugin outputs when something has gone wrong aren’t particularly friendly, and it’s unlikely that you’ll want your regular site visitors to see them. So, in the General Options for the plugin, you can now specify an error message that regular users will see if any error occurs that prevents the grid list from being displayed. Logged-in admin users will still see the old error messages, that give more information on the problem.


Memory

Previously, the plugin was loading SimplePie all the time, even when not needed. I think this may have been the cause of the memory limit issues that several people experienced. Now the plugin should only load SimplePie when it actually needs it!


Any feedback (good or bad!) on any of the new stuff would be very much appreciated. Obviously, this is just a ‘beta’ at the moment, so there may be some horrible bug lurking! I wouldn’t recommend that you use this on a live site, yet!
Specifically, feedback on the following would be great:

  • Event display builder – any shortcode combinations that don’t work / produce unexpected results? Any ideas for more shortcodes?
  • Date / time range options – are they accurate, especially in timezones other than UTC? Ideas for more options?
  • Memory – if you were previously experiencing memory limit issues, are they resolved / better / worse now?
  • Updating from previous versions – are your settings carried across properly?
  • Usability – are the new options easy to understand? Are more instructions required?

Please use the comments below, or contact me directly.

Just in case you missed the link at the top, the beta can be downloaded here (choose the ‘Development Version’). The beta version will still say it is 0.4.1 in the WordPress plugin admin, as I haven’t changed the readme file yet.

Thanks!

24 Responses

  1. How do you use the date retrieval settings in a shortcode?

    I’ve added:
    Retrieve events from: Start of this month to the shortcode so it looks like:

    [google-calendar-events id="1" type="list" title="Screenings" Retrieve events from: Start of this month]

    but that’s not working.

    Reply
  2. Hi Ross,
    that’s a great update!

    All my settings have migrated over ok, and I haven’t found any problems with the event display builder yet. I did just notice that changing “Retrieve events from” to “Now” doesn’t seem to save – it keeps on reverting back to 00:00 today.

    Shortcode suggestion: What about a [if-first-event-of-the-day] shortcode or similar? I’ve got the problem that my tooltip can never be fully seen due to the length of content, so it’d be nice to have a full description just for the first event, and just a title or truncated description for subsequent ones.

    Something else related to the above I’d like to see is being able to adjust the width of the tooltip (So far I only managed to do this by specifying a max width in the js file, unless there’s already a way of doing this using CSS?).

    Also, have you considered using another tooltip jquery plugin? Qtip is quite bulky at 84KB. I’ve had a bit of a play with http://code.drewwilson.com/entry/tiptip-jquery-plugin which is only around 6KB and has the option of always staying within the browser window.

    Finally, I got a bit “inspired” by your web page design and recreated a VERY similar box layout (see my homepage) – I hope you don’t mind!

    Keep up the great work!

    Reply
  3. Hi.

    Great plugin, I just installed the 0.4.1 on our webpage and are using the list function, but i’m considering trying out the beta, as we soon have an upcoming event that spans a week from 25 March until 5 April. With the current release there is not a good way to display this in a list due to the limitations. (Either all the days are listed, or it will disappear after the date/after 1 April)
    But I see in this version, you added a way to set what range of time to retrieve.
    So I was wondering
    If I use the:

    Events currently occuring
    Retrieve events from: Now
    Retrieve events until: Number of days (30)

    Will it be able to handle an event as the one I described above, and keep displaying the event during the whole time it is active?

    Kind regards.
    Brian

    Reply
  4. Hi,
    I have setup 0.4.1 recently and just upgraded to 0.5 beta. I have a strange problem (both versions). My start/end times are wrong by a few minutes, 25 or 26 minutes depending. Both WordPress and Google Calendar are on the same timezone. If it was a timezone problem, you’d expect 0.5 hour or 1 hour increments difference?

    Does anyone have an idea? Thanks!

    Reply
  5. Hello,

    I have been having problems getting the AJAX and other JavaScript to load using this plugin – this occurs in both 0.4.1 and the 0.5 beta. I have tried checking the box that is supposed to fix it but to no avail. It seems that the JavaScript is not getting loaded anywhere, looking at the page’s source. Any suggestions?

    Thanks,
    Conrad

    Reply
  6. Hey Ross,

    Is there anyway to be able to put in a custom event information? For example, is it possible for the plugin to read somehow an additional field from the “description” section of Google Maps?

    To better explain this, say I have an event.

    Currently, it has:
    Time:
    Venue:
    Cost:

    But, I wanted an additional field that would be:

    Facebook Event:

    Unfortunately, since google calenders can only have a single description field, I can’t exactly “trick” it. Can you think of any work around?

    Reply
    1. Nevermind, for some reason the wasn’t working in my calender description. Really good plugin you got! The only google calender that works properly in my opinion.

      Reply
  7. Is it possible to display static calendars? I want to display three calendar at once (May, June, July). Also how do i specify the height and with for a given calendar.

    Thanks in advance for your assistance. this is a FANTASTIC plugin.

    Lassana

    Reply
  8. Hi,
    Our Calendar is not showing the right times – I am actually on the west coast the client who this site is for is east coast – we have checked the settings in Google Calendar and the wordpress instance but can not seem to get it right – any ideas?

    Thanks!

    Reply
  9. We have eight calendar feeds that are shown on our main calendar. When different feeds have events on the same day the order they are listed in the tooltip seems to be random (probably based on how they were created in Google Calendar). Is there a way to sort the tooltip listing based on feed #, so Feed #1 is always listed first, then #2, etc?

    Reply

Leave a Reply