=== Event Calendar 3 ===
Tags: calendar, event, vcalendar, ical
Contributors: Alex Tingle
Version: 3.0.4

Manage future events as an online calendar. Display upcoming events in a dynamic
calendar, on a listings page, or as a list in the sidebar. You can subscribe to
the calendar from iCal (OSX) or Sunbird.

Choose one Wordpress category as the 'event' category, and then add posts for
dates in the future. Add the calendar or event list functions to your template,
or just use the 'Event Category' page to list your forthcoming events.

EventCalendar works fine with WordPress v1.5. It has been reported to work with
WordPress 2.0, but only once a hack has been applied to the Wordpress code. If
you are not comfortable with changing the Wordpress code, then stick to WP v1.5
or wait for the next version of the EventCalendar plugin.

== Installation ==

1. Upload to your plugins folder, usually `wp-content/plugins/`
2. Activate the plugin on the plugin screen
3. Change settings on the Event Calendar Options screen. You must choose which
   Wordpress category to use for events.
4. Add ec3_get_calendar() or ec3_get_events() to your template.
5. ONLY FOR WORDPRESS v2.0+: Patch the file wp-includes/classes.php by adding
lines as below. Add the lines starting with '+', but don't include the '+'
itself:

--- wp-includes/classes.php
+++ wp-includes/classes.php
@@ -661,6 +661,18 @@
 			} else {
 				if (mysql2date('U', $this->posts[0]->post_date_gmt) > mysql2date('U', $now)) { //it's future dated
 					$this->is_preview = true;
+					/* DIRTY FUTURE-POSTS HACK FOR EC3 */
+					if (function_exists('ec3_get_calendar')) {
+						global $ec3;
+						$ec3_post_0_is_event = intval($wpdb->get_var(
+							"SELECT COUNT(0) FROM $wpdb->post2cat WHERE post_id="
+							.$this->posts[0]->ID." AND category_id=$ec3->event_category"));
+						if ($ec3_post_0_is_event) {
+							$this->is_preview = false;
+						}
+					}
+					if ($this->is_preview)
+					/* DIRTY FUTURE-POSTS HACK FOR EC3 */
 					if (!current_user_can('edit_post', $this->posts[0]->ID)) {
 						$this->posts = array ( );
 					}

== Display Events in a SIDEBAR CALENDAR ==

Add the following code to your sidebar.php:

  <li>
    <?php ec3_get_calendar(); ?>
  </li>

If you are using an older template, then you should check that your HTML header
contains the following tag: <?php wp_head(); ?>

Caution: The Event Calendar must be unique. If you try to show more than one
calendar on a page, then only the first will be displayed.


== Display Events on a FULL PAGE ==

Your events are all in the same Wordpress category, so you can see them all on
the normal 'Event Category' page. By default you will also see events
on your front page just like normal posts, once their date arrives.

If you want to use the category page for listings then go to the 'Event
Calendar Options' page and set Show events as blog entries: to Keep Events
Separate. This keeps event posts off the front page, and converts the category
page into a more useful form.


== Display Events in a SIDEBAR LIST ==

You can show an abbreviated version of the full page event listing on every page
of your site. The template function: ec3_get_events() shows a list of upcoming
events. Add the following code to your sidebar.php:

  <li><?php _e('Events'); ?>
    <?php ec3_get_events(5); ?>
  </li>

The function takes several parameters:

 o limit. The maximum number of future events to list.

 o template_event (OPTIONAL) DEFAULT="<a href='%LINK%'>%TITLE% (%TIME%)</a>".
   A template for the formating of each event. The following placeholders are
   available:

    o %TITLE% - the title of the event.
    o %LINK% - the URL of the event post.
    o %TIME% - the time of the event.
    o %AUTHOR% - the post's author.

 o template_day (OPTIONAL) DEFAULT="%DATE%:". A template for the formatting of a
   header for each day. If you don't want this header, then set this to an
   empty string. The following placeholders are available:

    o %DATE% - The date of the post.
    o %SINCE% - Time until the event (Only available when Dunstan's
      'Time Since' plugin is active).

 o date_format (OPTIONAL) DEFAUKT="j F". A PHP date format string used to
   calculate the value of %DATE%. If this option is set empty, then Wordpress'
   normal date format is used.

 o template_month (OPTIONAL) DEFAULT="". A template for the formatting of a
   header for each month. If you don't want this header, then set this to an
   empty string. The following placeholders are available:

    o %MONTH% - The month of the post.

 o month_format (OPTIONAL) DEFAULT="F Y". A PHP date format string used to
   calculate the value of %MONTH%.

Example 1. No special headers:

  <li><?php
    _e('Events');
    ec3_get_events(3,'%DATE%: <a href="%LINK%">%TITLE%</a>','');
  ?> </li>

  2 January: First event.
  5 January: Second event.
  5 January: Third event.
  14 February: Fourth event.
  
Example 2. Date header (default set up):

  <li><?php
    _e('Events');
    ec3_get_events(3,"<a href='%LINK%'>%TITLE% (%TIME%)</a>","%DATE%:","j F");
  ?> </li>

  2 January:
      First event.
  5 January:
      Second event.
      Third event.
  14 February:
      Fourth event.

Example 3. Month header:

  <li><?php
    _e('Events');
    ec3_get_events(3,'%DATE%: <a href="%LINK%">%TITLE%</a>','','j',"%MONTH%:");
  ?> </li>

  January 2006:
     2: First event.
     5: Second event.
     5: Third event.
  February:
     14: Fourth event.

== Subscribe to the vCalendar ==

The vCalendar feature is now fully integrated into the plugin. This allows you
to view the event calendar in iCal, Sunbird and other modern calendar
applcations. You can now subscribe to the calendar at the address
http://your.site.url/?ec3_vcal


== Set Options: ==

The 'Event Calendar Options' page is in the administration area. Click on
'Options', and then click on the 'Event Calendar' tab. The following settings
are available:

General:

 o Event category:
     Set the category you use for upcoming events.

 o Show events as blog entries:
     Set this to 'Keep Events Separate' in order to use the Event Category page
     to show future events, in date order. Events do not appear on front page.


Calendar Display:

 o Number of months: NUMBER
     How many monthly calendars should be drawn by the ec2_get_calendar()
     function. This is useful for looking forward to upcoming events.

 o Show all categories in calendar:
     Choose whether the calendars should show all posts, or just events.

 o Show day names as:
     Day names in calendar can be abbreviated down to 3 letters ('Mon',
     'Tue', etc.) or just one letter ('M', 'T', etc.).

 o Show Event Calendar logo:
     Normally, a little 'EC' logo is shown on the calendar.

 o Position of navigation links:
     The navigation links are more usable when they are above the calendar, but
     you might prefer them below it for aesthetic reasons.

 o Popup event lists:
     When you hover the mouse over a calendar day, a popup usually appears
     listing the events (and other posts) on that day. Some 'Nicetitles' scripts
     are not written to work well with others, so you might want to use this
     option to disable the Event Calendar popups if you have trouble.

The first day of the week is set on Wordpress' 'General Options' screen.


== How to make an Event Post ==

An event post is a normal blog post that is assigned to the 'Event' category.

In order to set the date, you need to go to the 'Advanced' editing screen and
scroll down until you find the 'Edit time:' field. Select the 'Edit timestamp'
checkbox, set the date and time of your event and click 'Save'. These controls
are only available if your user level is **5 or higher**.

If you subscribe to the vCalendar using iCal or Sunbird, then you can set the
duration of the event in hours by creating a new custom field: 'duration'.


== New Features ==

The main new feature is a piece of JavaScript (AJAX) wizardry that allows you to
flip backwards and forwards through the calendar without refreshing the entire
page. The 'Forthcoming Events' list is also far more flexible. Many many other
requested features have been added.

 o Live Calendar updating without the need to refresh the whole page. (Thanks to
   Jon Abad for the inspiration of his LiveCalendar.)

 o Keep Events Separate mode. Keeps event posts off the front page. Turns the
   Event category page into a properly ordered listing of forthcoming events.
   This feature is off by default. Activate it on the Event Calendar Options
   page.

 o Custom Popup replaces the usual tooltip with a popup that lists each event on
   its own line. The popup is always positioned below the calendar, to ensure
   that you can still see the whole month.

 o There is no need to edit your CSS files. All essential stylesheet definitions
   are now part of the plugin.

 o Plus many more minor usability issues.


== Planned features ==

Some enhancement haven't made it into this release, but they are planned for the
future:

 o Multiple-day events.

 o Repeating events (good for birthdays).


== Frequently Asked Questions ==

Q: Can I disable your headers on pages with no calendar?

A: Yes. Remove the filter **before** your template's call to `wp_head()`:

    <?php remove_filter('wp_head','ec3_action_wp_head'); ?>


Q: Can I supply my own CSS?

A: Yes. To disable the plugin's CSS, just insert the following code *before*
your template's call to `wp_head()`:

    <?php global $ec3; $ec3->nocss=true; ?>


== Note: ==

Copyright (c) 2005, 2006 Alex Tingle
License: GPL