RS Event 0.6.1

RS Event is a WordPress plugin that makes it quick and easy to tag your posts with dates and times that can be displayed on your blog sidebar as a list of "upcoming events".

RS Event adds a simple panel to the posting sidebar of WordPress 2.0.1 and above, allowing a date and time to be quickly attached as metadata.

0.6 now also includes widget functionality! If you don't know what a widget is, go check out WordPress Widgets.

RS Event is now even easier to use through WordPress Widgets. If you haven't got it installed, go get it now. If you can't or don't want to install it, skip to the advanced instructions.

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

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

* 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

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.

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


          After this text:
          <li><h2>Categories</h2>

				    <ul>

				      <?php wp_list_cats('sort...

				    </ul>

			    </li>


          Insert this:
          <li><h2>Events</h2>

				    <?php rs_event_list() ?>

			    </li>

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 interface in the WordPress post editor

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 used the advanced install, jump to advanced customizing

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: you do not need to use this if you are 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 event.
- %FULLTEXT% — the entire text of the post with the event.
Note on the advanced method: using a double quote (") in the event_html will cause problems. Instead of typing it directly, use either \" or ".

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

If you aren't using it as a widget, 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 also optional.

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);

The array key names that you can use to customize it are listed above, in brackets after the option's name.

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.

RS Event was written by Robert 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

A WordPress plugin by Robert Sargant

What is it? ^

Easy install ^

Advanced install ^

Using it ^

Customizing it ^

Title

Output HTML (event_html)

"No events" message (no_events_msg)

Date Formatting (date_format)

Time Formatting (time_format)

Timespan (timespan)

Show up to __ events (max_events)

Group by date? (group_by_date)

Customizing it (advanced) ^

Update history ^

0.6.1 — 7^th May 2006

0.6 — 16^th April 2006

0.5.2 — 15^th April 2006

0.5.1 — 13^th March 2006

0.5 — 3^rd March 2006

Who is this by? ^