=== RS EVENT multiday ===
Contributors: wp-lefty
Donate link: http://dalking.de/rs-event-multiday/
Tags: widget, plugin, manage events, event widget, events, event, rs event, multiday
Requires at least: 2.7
Tested up to: 2.9.2
Stable tag: 1.1 beta

"RS EVENT multiday" is a modification of "RS EVENT" by Robert Sargant. It is a easy to use and highly flexible tool to manage events.



== Description ==


"RS EVENT multiday" is a modification of "RS EVENT" by Robert Sargant. 

The plugin offers the possibility to add a "RS EVENT multiday" widget to the sidebar of your blog.
It allows you to show a list of upcoming and/or past events. 

"RS EVENT multiday" includes three different functions, which can be used in templates.
rs\_event\_list(), rs\_event\_post(), rs\_event\_id()

<br /><br />
**FUNCTIONS**

1. rs\_event\_list()<br />
This is the function used for the widget. Of course, it can be used in templates as well. 
It prints an unordered list of events according to the parameters given to it (see below).
Both, the `<ul>` and the `<li>` include class="rsevent", so you can costumize the output with stylesheets.
Furthermore, the output can be customized with the parameters "html\_list\_v1", "html\_list\_v2", "html\_list\_v3" and "html\_list\_v4".<br />
For details see the parameters-section below.

1. rs\_event\_post()<br />
This function should be used in the single-post-template (usually the file single.php of your theme).
It prints the date of the event.
The output can be customized with the parameters "html\_post\_v1", "html\_post\_v2", "html\_post\_v3" and "html\_post\_v4".<br />
For details see the parameters-section below.<br />
Note: If you just want to get the return values from rs\_event\post(), so they do not get printed, you should use the function rs\_event\_post\_return(). (This might be useful for e.g. Thematic themes.)

1. rs\_event\_id()<br />
This function returns an array with IDs of posts, which include event-data. This array of IDs can then be used in other functions.

Each function can be customized by parameters.

<br /><br />
**PARAMETERS**

**title**<br />
*(string)* The widget-title in your sidebar. Not used, when the function is added to a template.<br />
*default value: 'Upcoming Events'*

**timespan**<br />
*(integer)* The maximum distance into the future events will be retrieved for, in days. <br />
*default value: 365*

**history**<br />
*(integer)* 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. <br />
*default value: 0*

**date\_format\_1**<br />
*(string)* The style in which the date is formatted. date\_format\_1 is used for single-day events, for the end date of multi-day events, and for the start date of multi-day events if the two dates are NOT within the same year.
*default value: 'd.m.Y'*

**date\_format\_2**<br />
*(string)* The style in which the date is formatted. date\_format\_2 is used for the start date of multi-day events if the two dates are within the same year.<br />
*default value: 'd.m.'*

**time\_format**<br />
*(string)* The style in which the time is formatted.<br />
Note: 'second' cannot be entered for event time and must not be used because of variable $fake\_second (used to mark empty time value.)<br />
*default value: 'H:i'*
		
**html\_list\_v1**<br />
*(string)* Used for rs\_event\_list(). Formats the output, if first date and time of an event is entered with "multi-day"-option off.<br />
*default value:* <br />
' `<hr />%DATE% @ %TIME%<br /><strong>%TITLE%</strong> <br />&#187; <a href="%URL%">read more</a> &#171;` '

**html\_list\_v2**<br />
*(string)* Used for rs\_event\_list(). Formats the output, if first date but no time is entered with "multi-day"-option off; if %TIME% is used here anyway (which usually does not make any sense), output of %TIME% equals "--:--".<br />
*default value:*<br />
' `<hr />%DATE% <br /><strong>%TITLE%</strong> <br />&#187; <a href="%URL%">read more</a> &#171;` '

**html\_list\_v3**<br />
*(string)* Used for rs\_event\_list(). Formats the output, if "multi-day"-option is on and first date and end date is entered.<br />
*default value:*<br />
' `<hr />%DATE% - %ENDDATE%<br /><strong>%TITLE%</strong> <br />&#187; <a href="%URL%">read more</a> &#171;` '

**html\_list\_v4**<br />
*(string)* Used for rs\_event\_list(). Formats the output, if "multi-day"-option is on but no end date is entered.<br />
*default value:*<br />
' `<hr />%DATE% (multi-day)<br /><strong>%TITLE%</strong> <br />&#187; <a href="%URL%">read more</a> &#171;` '

**html\_post\_v1**<br />
*(string)* Used for rs\_event\_post(). Formats the output, if first date and time of an event is entered with "multi-day"-option off.<br />
*default value:*<br />
' `<div class="rseventpost">%DATE% @ %TIME%</div>` '

**html\_post\_v2**<br />
*(string)* Used for rs\_event\_post(). Formats the output, if first date but no time is entered with "multi-day"-option off; if %TIME% is used here anyway 

(which usually does not make any sense), output of %TIME% equals "--:--".<br />
*default value:*<br />
' `<div class="rseventpost">%DATE%</div>` '

**html\_post\_v3**<br />
*(string)* Used for rs\_event\_post(). Formats the output, if "multi-day"-option is on and first date and end date is entered.<br />
*default value:*<br />
' `<div class="rseventpost">%DATE% - %ENDDATE%</div>` '

**html\_post\_v4**<br />
*(string)* Used for rs\_event\_post(). Formats the output, if "multi-day"-option is on but no end date is entered.<br />
*default value:*<br />
' `<div class="rseventpost">%DATE% (multi-day event)</div>` '

**max\_events**<br />
*(integer)* The maximum number of events to show. If this is set to 0, then all events will be shown. <br />
*default value: 0 (i.e. show all)*

**group\_by\_date**<br />
*(integer)* If this is set to No (value: 0), then each event will be separated into individual list element `<li>`. If this is set to Yes (value: 1), 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>`.<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.<br /> 
*default value: 0 (i.e. "no")*

**no\_events\_msg**<br />
*(string)* The output when the are no events within the set timespan. <br />
*default value: 'no upcoming events'*

**sort\_order**<br />
*(string)* Whether to list the events in ascending (value: 'ASC') or descending (value: 'DESC') date order.<br />
*default value: 'ASC'*

**category**<br />
*(integer)* 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. <br />
*default value: 0 (i.e. show all)*

<br /><br />
**Customizing the html-output**

The values "html\_list\_vX" and "html\_post\_vX" can be styled both for the widget and within templates.
Simply use html-code and the following parameters:

**%URL%**
the URL of the post with the event

**%DATE%**
the start-date of the event, formatted as date\_format\_1 in \_v1, \_v2 and \_v4 and as date\_format\_2 in \_v3.
    
**%ENDDATE%**
the end-date of the event, formatted as date\_format\_2

**%TIME%**
the event time, formatted as time\_format

**%LOCATION%**
an ordinary text value which might be used to enter e.g. the location of the event

**%TITLE%**
the title of the post.

**%FULLTEXT%**
the entire text of the post.

**%EXCERPT%**
the post excerpt.

<br /><br />
**How to pass on parameters to one of the functions**

Here is an example of how to pass on some parameters to the function rs\_event\_list(), when used within a template.
It works similar with rs\_event\_post() [and rs\_event\_post\_return()], just use the html\_post\_vX parameters instead of the html\_list\_vX parameters.<br />
Note: Parameters for the widget can be simply passed via the Widget-Panel of your blog-backend.

`<?php 		
	$argsevent = array(	
		'timespan'	=> 60,
		'date_format_1'	=> 'm|d|Y',
		'date_format_2'	=> 'm|d',

		'html_list_v1'	=> '<a class="list1" href="%URL%">%DATE%, %TIME%<br /><b>%TITLE%</b></a>',
		'html_list_v2'	=> '<a class="list1" href="%URL%">%DATE%<br /><b>%TITLE%</b></a>',
		'html_list_v3'	=> '<a class="list1" href="%URL%">%DATE% to %ENDDATE%<br /><b>%TITLE%</b></a>',
		'html_list_v4'	=> '<a class="list1" href="%URL%">%DATE% (multiday!!!)<br /><b>%TITLE%</b></a>',
		'max_events'	=> 4,
		);

	rs_event_list($argsevent); 
?>`


== Installation ==

This section describes how to install the plugin and get it working.

1. Download the zip-file and unpack it.
1. Upload the folder `rs-event-multiday` to the `/wp-content/plugins/` directory of your blog.
1. Activate the plugin through the 'Plugins' menu in WordPress
1. Add the Widget "RS EVENT multiday" to your sidebar and customize it AND/OR
1. Place the function rs\_event\_list(), rs\_event\_post() and/or rs\_event\_id() in your template(s) and customize it.

See "Description" for details.


== Screenshots ==

1. Customization of the Widget "RS EVENT multiday".
2. Add event data to your post at the edit-post-panel.
3. This is how the widget might look like in your sidebar (using default values).


== Frequently Asked Questions ==

Q: Is an event nothing else then an ordinary post with some (hidden) meta values?
A: Yes, it is this simple!<br /><br />

Please see/search/use the comments on <a href="http://dalking.de/rs-event-multiday/">http://dalking.de/rs-event-multiday/</a><br />
A lot of questions are answered there already (including the one above).