RS Event 0.9.3

RS Event is a WordPress plugin that uses the power of widgets. It gives you an extremely quick and easy way to tag your posts with a a date and time, and then build a list of these dates in your sidebar.

RS Event requires WordPress 2.0.1 or above. The WordPress Widgets plugin will make your life a whole lot easier, but isn't strictly nessecary.

If you're using WordPress Widgets, then it couldn't be simpler. If you can't or won't install it, skip to the advanced install.

There are three very easy steps to installing RS Event as a widget:

1. Upload the file rs-event.php to your /wordpress/wp-content/plugins/ directory.
2. Go to the WordPress Plugins page, and activate RS Event.
3. Go to the Presentation » Sidebar Widgets page^a, and drag the RS Event widget into your sidebar.

^a If this page does not appear, make sure you have the Sidebar Widgets plugin activated. If it still doesn't appear, then your WordPress theme is not widgets compatible. You can upgrade the theme to accept widgets yourself by following these instructions (harder) or using the advanced install instructions (easier).

The default RS Event display in the blog sidebar

Advanced install: Calling it an "advanced install" is a bit of a lie, as it's still pretty easy. There are still just three small steps, but one involves fiddling directly with the template.

1. Upload the file rs-event.php to your /wordpress/wp-content/plugins/ directory.
2. Go to the WordPress Plugins page, and activate RS Event.
3. Go to the Presentation » Theme Editor page, open up the Sidebar file and make the following change:

If your theme's sidebar file does not look anything like this, then you're going to have to poke about and work out how to insert it yourself. Sorry, I can't help on a theme-by-theme basis.

To add events to the list, simply add a date to a post in the RS Event sidebar box when editing or creating a post.

The RS Event tag editor

The Day, Month and Year fields are mandatory, while the Hour and Minute fields are optional. However, if you use any time-related formating details when customizing the output, dates without hours and minutes set will appear as 12 midnight.

If you installed RS Event as a widget, everything is customizable through the widget options panel. If you installed it into your sidebar by hand (the advanced method), you have to pass arguments to the widget manually. See the advanced customization section to see how.

The RS Event widget options panel

These are the meanings of the various options you can set:

Title

The title for the widget. Default value is Upcoming Events.

Note: this is not used when using the advanced method.

Output HTML (event_html)

The formatting style for each event. There are a number of variables you can use in this string to customize it each time an event is outputted:

• %URL% — the URL of the post with the event.
• %DATE% — the event date, formatted as date_format
• %TIME% — the event time, formatted as time_format.
• %TITLE% — the title of the post.
• %FULLTEXT% — the entire text of the post.
• %EXCERPT% — the post excerpt.

Default value is "%DATE%: <a href='%URL%'>%TITLE%</a>".

"No events" message (no_events_msg)

The output when the are no events within the set timespan.

Default is No upcoming events.

Date Formatting (date_format)

The style in which the date is formatted. For instructions on how to format this, see the PHP manual page on date().

Default value is "j M".

Time Formatting (time_format)

Works in the same way as Date Formatting.

Default value is "H:i".

Timespan (timespan)

The maximum distance into the future events will be retrieved for, in days.

Default value is 365.

History (history)

The maximum distance into the past that events will be retrieved for, in days. This can also be set to a negative negative number, e.g. -2 to prevent events that are occuring in the next two days from appearing.

Default value is 0 (i.e. don't show events that have passed).

Show up to __ events (max_events)

The maximum number of events to show. If you have a lot of events coming up in the current timespan, but not regularly, it is inconvenient to have to modify the template on just this occasion. This lets you restrict the maximum number of events to show simultaneously.

Alternatively, you can set Timespan to a huge value (e.g. 36500, for 100 years), and use this value to restrict the number of upcoming events to just the next few, regardless of date.

Default value is 0 ("show all").

Group by date? (group_by_date)

If this is set to No (false), then each event will be separated into individual list element <li> tags.

If this is set to Yes (true), then the Date Formatting is checked for each post. Events with the same Date Formatting value are grouped together in a single <li> element, with the date first and subsequent posts separated by break rules <br />.

By setting the Date Formatting to different values, you can group by different date properties, e.g. use "Y" to group by year, or "W Y" to group by week.

Default value is false.

Sort Order (sort_order)

Whether to list the events in ascending or descending date order. If you are using the advanced method, the values are ASC and DESC respectively.

Default value is ASC (ascending date order).

Restrict to category (category)

Show only events listed against posts in the category with this ID number. If this is set to 0, then all events will be shown.

This option is only available in advanced mode, as it is useful if you want to create multiple lists for different types of event. In widgets mode you can only create one RS Event item.

Default value is 0 ("show all").

Advanced customization: You're going to need a tiny bit of PHP knowledge for this, but copying and pasting the code below should work just fine.

The rs_event_list() function accepts a single optional argument, an associative array of various things you want to customize. All of these array elements are optional and will use the default if not defined.

The array keys for each option are listed above in brackets after the name of the option. To customize the output, call rs_event_list() like this:

$rs_event_arg = array
(
  'timespan'      => 28,
  'date_format'   => 'jS M y',
  'time_format'   => 'g:i A',
  'group_by_date' => true,
  'event_html'    => '<a href="%URL%">%TITLE% (%TIME%)</a>',
  'max_events'    => 0,
);

rs_event_list($rs_event_arg);

0.9.3 — 13^th August 2006

• Bugfix: fixing (hopefully) the last timezone issue introduced in 0.9.1

0.9.2 — 11^th August 2006

• Bugfix: shifting dates problem introduced in 0.9.1

0.9.1 — 28^th July 2006

• Bugfix: MySQL timezone settings cause a delay in event appearance for servers behind UTC

0.9 — 26^th July 2006

• Bugfix: events attached to postdated posts are not shown
• Bugfix: output variables now passed through appropriate filters
• New-look widget options panel
• New output variable %EXCERPT%
• Ability to restrict to a single category
• Ability to change sort order
• Cleaned up code substantially

0.6.3 — 8^th July 2006

• Bugfix: events attached to unpublished posts are not shown.
• You can now specify a distance into the past to retrieve posts for.

0.6.2 — 12^th May 2006

• Events no longer remain listed when the parent post is deleted

0.6.1 — 7^th May 2006

• Date output now obeys WordPress locality (thanks Choan!)
• Clickable tags in widget options
• New %FULLTEXT% tag for more flexibility

0.6 — 16^th April 2006

• Now widgets compatible!
• Timespan is now in units of days, not seconds
• A couple of small alterations to the HTML output to make it more compatible with widgets

0.5.2 — 15^th April 2006

• You can now easily remove events from posts
• Default timespan is now 365 days, to clear up some confusion

0.5.1 — 13^th March 2006

• You can now restrict the number of events displayed simultaneously.
• Cleaned up ambiguous documentation about "timestamp".

0.5 — 3^rd March 2006

• Initial release.

Still stuck? Check the frequently asked questions, drop into the RS Event forum or email me at robert@sargant.com

RS Event was written by Rob Sargant, a Physics undergraduate with a bit too much free time.

RS Event is licenced under the GPL (GNU Public License) Version 2.

Comments and suggestions are appreciated. As are donations :P

For more plugins, odds and sods, go to www.sargant.com