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!

23 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

    1. Hi Pieter,

      The date retrieval options are found in the settings for each feed, they aren’t set in the shortcode itself.

      Ross.

      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

    1. Hi Axel,

      This is great feedback, thanks! I’ll look into fixing / implementing the things you mention.

      It is sort of possible to adjust the tooltip width via CSS, with something like this:

      .gce-qtip, .gce-qtip .qtip-wrapper{
	width:500px !important;
}
 
.gce-event-info{
	max-width:500px;
}

      However, this certainly isn’t particularly obvious or intuitive!

      You’re right about qTip, it is quite hefty. I have looked at alternatives in the past, but I’ve not seen TipTip before, so I’ll definitely have a play around with it.

      And no, I don’t mind you adapting my design! I’m glad you like it. I’m thinking about doing a re-design at some point, when I have the time!

      Thanks again,
      Ross.

      Reply

      1. Hi Ross,
        cheers for the CSS hints.
        I’ve had a go at replacing qtip with tiptip, and unfortunately it doesn’t stay within the browser window either once a tooltip gets to big. It does seem to work fairly well apart from that though for what I want it to do – it may not be suitable for others though (and will need a bit more TLC on its CSS).
        If you want to try it out send me a mail, and I can either send you a git patch, or the files I changed to save you the work…
        You can also see it in action here: http://cambridge105.gigx.co.uk/
        Cheers,
        Axel

        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

    1. Hi Brian,

      The limitations of multi-day events in the plugin still exist in the 0.5 beta, so I suspect the answer to your question is probably no, I’m afraid.

      I think the only completely reliable way around this limitation is for the plugin to retrieve all past events, and check each one to see if it is a multi-day event that spans the required date range. This could potentially mean retrieving a huge number of past events, which could slow things down considerably. In most cases, however, probably looking back a month or so would be enough. I’ll need to spend some more time on this to figure out what works best.

      Ross.

      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

    1. Hi Jimmy,

      That’s very odd!

      What does WordPress say the time is? (in Settings > General, under ‘Timezone’, there’s ‘UTC time is…’ and ‘Local time is…’ info). Is it correct?

      Could you let me know the feed URL you are using, so I can do some testing?

      Thanks,
      Ross.

      Reply

      1. Ok, I figured out my problem with your lead… I had a wrong PHP time format in the plugin settings! I was using H:m instead of H:i. So the second part of the time was in fact the month number (04 or 05, giving the 25 or 26 minutes difference). That was stupid :-) Sorry and thank you for the great plugin!

        Reply

        1. Oh, I see! :)

          Well, I’m glad it was a simple fix in the end, I was worried you had discovered a nasty bug of some sort! :P

          Ross.

          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

    1. Hi Conrad,

      This is likely to be because your theme doesn’t contain the necessary wp_head() and wp_footer() function calls in its header.php and footer.php files. These functions are responsible for loading JavaScript and CSS files.

      If your theme does have these functions already, it may be that something is de-registering jQuery. The JavaScript in my plugin is dependent upon jQuery and tells WordPress about this dependency. If something (perhaps the theme itself, or a plugin) de-registers jQuery, then WordPress won’t load any of the JavaScript files that are dependent upon it.

      I hope this is useful. If you’re still having problems, could you provide a link to your site, so that I can investigate further?

      Ross.

      Reply

  6. Hi all,

    I have updated the beta with a few things:

    • Fixed a bug that prevented properly selecting ‘Now’ for the ‘Retrieve events from’ setting (thanks to Axel for spotting this)
    • Fixed a bug in the upgrade code that caused the ‘Number of days (specify)’ option to be incorrectly selected for the ‘Retrieve events until’ setting, with a value of 0 (thanks to Art for drawing my attention to this)
    • Fixed a bug that prevented admin pages (add, edit, delete) from redirecting back to the main admin page after clicking ‘Save’. This actually affects 0.4.1 (and below) too, and seems to be related to changes in WordPress 3.1, although I’m not sure exactly what. Anyway, fixed now!
    • Changed the [all-day] and [not-all-day] shortcodes to [if-all-day] and [if-not-all-day] respectively to match the other conditional shortcodes (that all begin with ‘if’)
    • Added some more shortcodes for the event display builder (explanations added to the post above): [start-human], [end-human], [if-now], [if-not-now], [if-started], [if-not-started], [if-ended], [if-not-ended], [if-first] and [if-not-first]

    Thanks to everyone for their feedback so far. Further comments / bug reports on this update would be great!

    You can download the beta from here. Choose the Development Version.

    Ross.

    Reply

  7. 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

  8. 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

    1. Hi Lassana,

      I’m afraid this isn’t currently possible. The upcoming 0.5 release of the plugin will allow you to specify exact starting and ending dates for retrieval of events, but will always display the current month to start with, which I don’t think is really what you’re after.

      I’ll look into this for a future release, as it would make more sense for the calendar to display a month with events (that may not be the current month) rather than an ‘empty’ current month. I’ll give it some thought!

      You can adjust the height and width of a calendar via the plugin CSS stylesheet (google-calendar-events/css/gce-style.css). To change the width, you would add something like this:

      .gce-page-grid .gce-calendar{
	width:500px;
}

      To change the height, you can adjust the height of the table cells that make up the grid:

      .gce-page-grid .gce-calendar td{
	height:50px;
}

      Ross.

      Reply

  9. Hello,

    Version 0.5 has now been released!

    Thanks to everyone for their assistance in testing the beta. Your feedback was invaluable.

    There’s a couple of changes I’ve made between the beta and the release:

    - Retrieval date range options are slightly different, take a look at the release post for details.

    - Removed the [timezone] shortcode. It didn’t always seem to work properly, and I don’t think it would be particularly useful anyway

    Thanks again all!

    Ross.

    Reply

  10. 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

    1. Hello,

      What do you have the WordPress timezone (Settings > General), and the “Timezone adjustment” option (in the plugin feed settings) set to?

      How far out (how many hours) are the times?

      Ross.

      Reply

  11. 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

    1. Hi Scott,

      The order of events should be chronological. If events start at the same time, then the order isn’t really defined, so may appear sort of random. There isn’t currently any way to change this, I’m afraid. I’ll look into this for a future release though, as I can certainly see how the order could be important (as in your case).

      Ross.

      Reply

Leave a Reply