← Go back to the Google Calendar Events plugin homepage

The event display builder is a feature (introduced in version 0.5) that allows you to customise the information that is displayed for events. It is much more flexible than the ‘old’ simple display options, but perhaps harder to get to grips with initially, hence this guide! If, after reading this guide, you have further questions, please ask in the comments below.

Jump To:

• Introduction
• Event information shortcodes
• Feed information shortcodes
• Conditional shortcodes
• Attributes
• Examples
• Further notes

Introduction

The event display builder is simply a text field into which you enter basic HTML and shortcodes. When the plugin generates the calendar grid or list to display on your page, post or widget, it replaces the shortcodes with the relevant information for each event. You may already be familiar with WordPress shortcodes, as they are widely used in many plugins (including this one!). The event display builder shortcodes use the same concept (and in fact much of the same code), but can only be used in the event display builder field. Here’s a couple of example feeds, with example events that I will use to explain the various shortcodes that you can use:

Feed 1

Feed ID: 1
Feed title: Exciting things

Event 1

Event title: Trip to the seaside
Date / time: 16th April, all day
Location: Whitby, North Yorkshire
Description: A day out in Whitby! Remember to bring an umbrella as it’ll probably rain

Event 2

Event title: Football match
Date / time: 19th April, 15:00 until 17:00
Location: Glanford Park, Scunthorpe

Feed 2

Feed ID: 2
Feed title: Boring things

Event 1

Event title: Dentist appointment
Date / time: 14th April, 11:00 until 12:00
Description: Just a check-up

Event 2

Event title: Cardboard box conference
Date / time: April 21st and 22nd, all day both days
Location: Birmingham NEC
Description: The latest advances in cardboard box technology

Event Information Shortcodes

These are the basic shortcodes that are replaced with event information when the plugin generates the grid or list.

[event-title]

Simply displays the event title. So, for event 1 from feed 1, ‘Trip to the seaside’ would be shown.

Possible attributes: html, markdown

[start-time]

Displays the start time of the event. The time format is determined by the ‘Time format’ option in the feed settings, or if this has been omitted, by the WordPress ‘Time format’ option (in Settings > General).Assuming that the time format for feed 2 is set to g:i a, this shortcode would output ’11:00 am’ for event 1 from feed 2.

Possible attributes: offset

[start-date]

Displays the start date of the event. The date format is determined by the ‘Date format’ option in the feed settings, or if this has been omitted, by the WordPress ‘Date format’ option (in Settings > General).Assuming that the date format for feed 2 is set to F j, Y, this shortcode would output ‘April 21, 2011′ for event 2 from feed 2.

Possible attributes: offset

[start-custom]

Displays the start date / time of the event. It uses whatever format you specify in the format attribute. This gives greater flexibility when displaying the start time and date together than using both [start-time] and [start-date].For example, if you entered jS F Y \\a\\t g:i a in the format attribute, the start date / time for event 2 from feed 1 would be displayed like this: ’19th April 2011 at 3:00 pm’.

Possible attributes: format, offset

[start-human]

Displays the amount of time until the event starts, or how long ago it started (the difference between ‘now’ and the start time of the event) in human-readable format, such as ’1 hour’, ’4 days’, ’15 mins’ etc.The output of this shortcode obviously depends on the time ‘now’, and is best used in conjunction with the [if-started] and [if-not-started] conditional shortcodes, which allow you to display something like ‘Started 1 hour ago’, or ‘Starts in 30 mins’.

Possible attributes: precision, offset

[end-time]

Displays the end time of the event. The time format is determined by the ‘Time format’ option in the feed settings, or if this has been omitted, by the WordPress ‘Time format’ option (in Settings > General).Assuming that the time format for feed 2 is set to g:i a, this shortcode would output ’12:00 pm’ for event 1 from feed 2.

Possible attributes: offset

[end-date]

Displays the end date of the event. The date format is determined by the ‘Date format’ option in the feed settings, or if this has been omitted, by the WordPress ‘Date format’ option (in Settings > General).Assuming that the date format for feed 2 is set to F j, Y, this shortcode would output ‘April 22, 2011′ for event 2 from feed 2.

Possible attributes: offset

[end-custom]

Displays the end date / time of the event. It uses whatever format you specify in the format attribute. This gives greater flexibility when displaying the end time and date together than using both [end-time] and [end-date].For example, if you entered g:i a \\o\\n F jS Y in the format attribute, the end date / time for event 2 from feed 1 would be displayed like this: ’5:00pm on April 19th 2011′.

Possible attributes: format, offset

[end-human]

Displays the amount of time until the event ends, or how long ago it ended (the difference between ‘now’ and the end time of the event) in human-readable format, such as ’1 hour’, ’4 days’, ’15 mins’ etc.The output of this shortcode obviously depends on the time ‘now’, and is best used in conjunction with the [if-ended] and [if-not-ended] conditional shortcodes, which allow you to display something like ‘Ended 3 days ago’, or ‘Ends in 2 hours’.

Possible attributes: precision, offset

[location]

Displays the location of the event. So, for event 2 from feed 1, ‘Glanford Park, Scunthorpe’ would be displayed.

Possible attributes: html, markdown

[maps-link]…[/maps-link]

Anything that you enter between the opening and closing tags of this shortcode (including further shortcodes) will be shown as a link to Google Maps, using the location of the event as a search parameter.

For example, if you were to use the shortcode like this: [maps-link]Map[/maps-link], event 1 from feed 1 would display ‘Map‘.

As mentioned, you can use further shortcodes between the opening and closing tags, so you could use this: [maps-link][location][/maps-link] to display this ‘Whitby, North Yorkshire‘.

Possible attributes: newwindow

[description]

Displays the event description. So, for event 2 from feed 2 ‘Cardboard box conference’ would be displayed.

Possible attributes: html, markdown, limit

[link]…[/link]

Anything that you enter between the opening and closing tags of this shortcode (including further shortcodes) will be shown as a link to the Google Calendar page for the event.For example, to make the event title into a link to the Google Calendar page, you would use this: [link][event-title][/link].

Possible attributes: newwindow

[url]

Outputs the raw URL to the Google Calendar page for the event. Perhaps useful for constructing your own links, e.g: <a href="[url]">More information</a>.

[length]

Displays the length of the event, in human-readable format. So for event 1 from feed 1, ’1 day’ would be displayed.

Possible attributes: precision

[event-id]

Outputs the unique identifier assigned to an event. This will be a string of characters like: n0b9hr7tfjhtoijyar67b4nnok. This is useful in combination with [cal-id] for constructing the URL to the .ics or XML feed for a specific event.

Feed Information Shortcodes

These shortcodes are replaced with the relevant information about the feed from which the event comes.

[feed-title]

Displays the title of the feed from which the event comes. The feed title is specified in the plugin feed settings. So, for feed 2, ‘Boring things’ would be displayed.

[feed-id]

Outputs the ID of the feed from which the event comes. This can be useful for constructing your own feed-specific CSS classes.

For example, you could enter something like this: <p class="feed-[feed-id]">[event-title]</p>. You could then add some CSS to the stylesheet to style this class differently from classes from other feeds, perhaps like:

.feed-1{
	background:#FF0000;
}

.feed-2{
	background:#00FF00;
}

This would display the event title on a red background for events from feed 1, and on a green background for events from feed 2.

[cal-id]

Outputs the calendar ID, which uniquely identifies the calendar. This may be an email address, or a string of characters followed by “@google.com”. In combination with the event-id] shortcode, you can construct links to the .ics feed for a specific event, like this:

<a href="http://www.google.com/calendar/ical/[cal-id]/public/full/[event-id]">ical feed</a>

or to the XML feed like this:

<a href="http://www.google.com/calendar/feeds/[cal-id]/public/full/[event-id]">XML feed</a>

Conditional Shortcodes

Each of the following shortcodes has a condition that must be met for anything between its opening and closing tag to be displayed. In other words, if its condition is not met, anything inside it will be ignored (including further shortcodes).

[if-all-day]…[/if-all-day]

Condition: The event is an all-day event

Anything between the opening and closing tags of the shortcode will only be displayed if the event is an all-day event. This means that you can display something like ‘All day’ rather than the start / end times of the event. Best used in conjunction with [if-not-all-day] if your feed contains both all-day and ‘normal’ events.

For example, [if-all-day]All day[/if-all-day] would display ‘All day’ for event 1 from feed 1, but wouldn’t display anything for event 2 from feed 1.

[if-not-all-day]…[/if-not-all-day]

Condition: The event is not an all-day event

Anything between the opening and closing tags of the shortcode will only be displayed if the event is not an all-day event. Best used in conjunction with [if-all-day] if your feed contains both all-day and ‘normal’ events.

[if-title]…[/if-title]

Condition: The event has a title

Anything between the opening and closing tags of the shortcode will only be displayed if the event has a title.

[if-description]…[/if-description]

Condition: The event has a description

Anything between the opening and closing tags of the shortcode will only be displayed if the event has a description.

For example, [if-description][description][/if-description] would display ‘Just a check-up’ for event 1 from feed 2, but wouldn’t display anything for event 2 from feed 1.

[if-location]…[/if-location]

Condition: The event has a location

Anything between the opening and closing tags of the shortcode will only be displayed if the event has a location.

For example, [if-location][location][/if-location] would display ‘Birmingham NEC’ for event 2 from feed 2, but wouldn’t display anything for event 1 from feed 2.

[if-tooltip]…[/if-tooltip]

Condition: The plugin is currently generating a calendar grid with tooltips

Anything between the opening and closing tags of the shortcode will only be displayed if the plugin is currently creating a calendar grid with tooltips. This allows you to display different information for tooltips and lists, and generate different CSS classes.

[if-list]…[/if-list]

Condition: The plugin is currently generating an events list

Anything between the opening and closing tags of the shortcode will only be displayed if the plugin is currently creating an events list. This allows you to display different information for tooltips and lists, and generate different CSS classes.

[if-now]…[/if-now]

Condition: The event is taking place now

Anything between the opening and closing tags of the shortcode will only be displayed if the event is taking place now (it is after the start time, but before the end time). This can be useful for highlighting current events.

[if-not-now]…[/if-not-now]

Condition: The event is not taking place now

Anything between the opening and closing tags of the shortcode will only be displayed if the event is not taking place now (it may have not yet started, or already ended).

[if-started]…[/if-started]

Condition: The event has started (even if it has also ended)

Anything between the opening and closing tags of the shortcode will only be displayed if the event has started. This works well with the [start-human] shortcode. For example, you could use something like this: [if-started]Started [start-human] ago[/if-started], which would output something like ‘Started 30 mins ago’.

[if-not-started]…[/if-not-started]

Condition: The event has not started

Anything between the opening and closing tags of the shortcode will only be displayed if the event has not started. Again, this works well with the [start-human] shortcode. For example, you could use something like this: [if-not-started]Starts in [start-human][/if-not-started], which would output something like ‘Starts in 3 days’.

[if-ended]…[/if-ended]

Condition: The event has ended

Anything between the opening and closing tags of the shortcode will only be displayed if the event has ended. This works well with the [end-human] shortcode. For example, you could use something like this: [if-ended]Ended [end-human] ago[/if-ended], which would output something like ‘Ended 2 days ago’.

[if-not-ended]…[/if-not-ended]

Condition: The event has not ended (even if it hasn’t started)

Anything between the opening and closing tags of the shortcode will only be displayed if the event has not ended. Again, this works well with the [end-human] shortcode. For example, you could use something like this: [if-not-ended]Ends in [end-human][/if-not-ended], which would output something like ‘Ends in 4 days’.

[if-first]…[/if-first]

Condition: The event is the first of the day

Anything between the opening and closing tags of the shortcode will only be displayed if the event is the first event of the day.

[if-not-first]…[/if-not-first]

Condition: The event is not the first of the day

Anything between the opening and closing tags of the shortcode will only be displayed if the event is not the first event of the day.

[if-multi-day]…[/if-multi-day]

Condition: The event spans multiple days

Anything between the opening and closing tags of the shortcode will only be displayed if the event spans more than one day (in other words, it doesn’t start and end in the same day).

[if-single-day]…[/if-single-day]

Condition: The event starts and ends on the same day

Anything between the opening and closing tags of the shortcode will only be displayed if the event starts and ends on the same day (it doesn’t span multiple days).

Attributes

Some of the above shortcodes have further attributes that you can use to enable / disable / specify certain things. An explanation of these attributes is below:

html

Description: Whether or not to parse HTML entered in the relevant field Valid values: true or false If omitted: HTML will not be parsed Example: [event-title html="true"]

If set to true, any HTML you have entered in the relevant field will be properly parsed, rather than displayed as plain text (the field content will passed through the wp_kses_post function to reduce the risk of cross-site scripting attacks if your Google Calendar account was to be compromised).

It’s probably not a good idea to use this at the same time as the limit attribute, as this could result in wonky HTML.

markdown

Description: Whether or not to parse Markdown entered in the relevant field Valid values: true or false If omitted: Markdown will not be parsed Example: [description markdown="true"]

If set to true, any Markdown in the relevant field will be properly parsed, rather than displayed as plain text. You must have PHP Markdown installed for this to work.

limit

Description: The word limit for the field Valid values: A positive integer If omitted: No word limit will be applied

This will trim the relevant field to the specified number of words.

format

Description: The date / time format to use Valid values: A PHP date format string If omitted: The date / time information will not be displayed! Example: [start-custom format="F j, Y - g:i a"]

The date / time format to use for the [start-custom] and [end-custom] fields.

newwindow

Description: Whether or not the link should open in a new browser window / tab Valid values: true or false If omitted: The link won’t open in a new window / tab Example: [maps-link newwindow="true"]

If set to true, the link will open in a new browser window or tab when clicked.

precision

Description: The precision to use for time differences in human-readable format Valid values: A positive integer If omitted: Defaults to 1 Example: [length precision="2"]

Defines how precise time differences expressed in human-readable format should be. For example, a precision of 1 might display ’1 day’, whereas a precision of 3 might display ’1 day, 1 hour, 24 minutes’.

offset

Description: An offset (in seconds) to apply to a date / time before it is displayed Valid values: An integer (positive or negative) If omitted: No offset is applied Example: [end-date offset="-1"]

Adds the specified value in seconds to the date / time before it is formatted and displayed. This is most useful for forcing the end date of an all-day event to display as expected (see above example).

autolink

Description: Whether or not to automatically make URLs entered into the description of an event into “clickable” links Valid values: true or false If omitted: URLs are automatically made into links Example: [description autolink="false"]

If set to true, URLs in the description will be automatically made into links. URLs will not be automatically made into links if the html or markdown attributes are used, regardless of this option.

Examples

Here’s some examples of how the above shortcodes and attributes can go together, along with some HTML, to create all sorts of different layouts.

The Default

Event display builder input:

<div class="gce-list-event gce-tooltip-event">[event-title]</div>
<div><span>Starts:</span> [start-time]</div>
<div><span>Ends:</span> [end-date] - [end-time]</div>
[if-location]<div><span>Location:</span> [location]</div>[/if-location]
[if-description]<div><span>Description:</span> [description]</div>[/if-description]
<div>[link newwindow="true"]More details...[/link]</div>

Example output (tooltips and list items):

This is a simple layout that is similar to the ‘old’ default. Notice that it doesn’t output the location or description if they’re empty. The newwindow attribute is used in the [link]shortcode, so that the link opens in a new window / tab. A possible drawback to this layout is that it doesn’t handle all-day events particularly well, just displaying ’12:00 am’ for the start / end times, which could cause confusion.

Handling All-Day Events

Event display builder input:

<p class="gce-list-event gce-tooltip-event">[event-title]</p>
[if-all-day]<p><span>Time:</span> All day</p>[/if-all-day]
[if-not-all-day]
<p><span>Starts:</span> [start-time]</p>
<p><span>Ends:</span> [end-date] - [end-time]</p>
[/if-not-all-day]
[if-location]<p><span>Location:</span> [location]</p>[/if-location]
[if-description]<p><span>Description:</span> [description]</p>[/if-description]
<p>[link newwindow="true"]More details...[/link]</p>

Example output (tooltips and list items):

Notice that events that last all day are now handled differently than ‘normal’ events.

Different Feeds

Event display builder input:

<div class="feed-[feed-id]">
<p>[link newwindow="true"][event-title][/link] - ([feed-title])</p>
<p>From [start-custom format="g:i a"] on [start-custom format="jS F"] until [end-custom format="g:i a"] on [end-custom format="jS F"]</p>
</div>

Example output (tooltips and list items):

In this example I have used the feed information shortcodes to display events from different feeds in different ways. I have constructed a feed-specific CSS class and used the following CSS to style the events:

.feed-1{
	background:#CCFFCC;
}

.feed-2{
	background:#FFCC99;
}

.feed-1 p:first-child,
.feed-2 p:first-child{
	font-weight:bold;
}

Also notice the use of the [start-custom] and [end-custom] shortcodes, and the format attribute. I’ve also made the event title into a link to the Google Calendar page for the event, by placing the [event-title] shortcode inside the [link]shortcode.

Saving Space

Event display builder input:

[if-all-day]<p><strong>[link][event-title][/link]</strong> - All day</p>[/if-all-day]
[if-not-all-day]</p><strong>[link][event-title][/link]</strong> - [start-time]</p>[/if-not-all-day]

Example output (tooltips and list items):

If you’re short of space, or have large numbers of events, and only want to display the bare minimum of event information, you can do so with something like this. This example still takes advantage of the ability to differentiate between all-day and ‘normal’ events. I’ll add more examples later!

Further Notes

I realise that the event display builder appears quite complex at first glance, so I hope the above information is helpful. If you’re not sure about anything, please ask in the commentsbelow. Any feedback regarding the following would be helpful for future developments to this feature:

• Bugs, or anything that doesn’t seem to work as described
• Ideas for more shortcodes / attributes that would be useful to you
• Is the documentation (this page!) good enough to understand how things work?

Also, if you come up with any really snazzy layouts, let me know!