= Events Calendar

A calendar of events for Radiant CMS.

Note: This version of the events_calendar extension is compatible with Radiant 0.9.
If you are using Radiant 0.8.x, please pull from the radiant-0.8.1 branch.
If you are using Radiant 0.7.1, please pull from the radiant-0.7.1 branch.

WARNING: The syntax of the `<r:events>` tag changed between version 0.3 and 0.4.

A bare `<r:events>` tag no longer returns the events for the current day (use
`<r:events for="today">` to achieve the same results) and instead returns all
events.

The `year`, `month`, and `day` attributes are no longer used; use the `for`
attribute instead. Instead of

  <r:events year="2009" month="12" day="6">

use

  <r:events for="2009-12-06">

== Installation

Install the events_calendar extension:

  git clone git://github.com/davec/radiant-events-calendar-extension.git vendor/extensions/events_calendar

Now, run the migration and copy the public assets:

  rake radiant:extensions:events_calendar:update
  rake radiant:extensions:events_calendar:migrate

To use the calendar, you must include the provided JavaScript and CSS files in
your layout. The included JavaScript relies on the Prototype and LowPro
libraries, so they must also be loaded prior to loading the events_calendar.js
file. Add the following to your layout header:

  <link rel="stylesheet" type="text/css" href="/stylesheets/events_calendar.css" />
  <script type="text/javascript" src="/javascripts/prototype.js"></script>
  <script type="text/javascript" src="/javascripts/lowpro.js"></script>
  <script type="text/javascript" src="/javascripts/events_calendar.js"></script>

An alternate version of the JavaScript file, named events_calendar_jquery.js,
is provided for use with jQuery (the minimum jQuery version is 1.4.2 and is
not included).

Events can be created and manged from the Events tab in the admin UI. A
calendar and listings of events can be displayed in your templates using the
supplied Radius tags.

== Configuration

This extension uses a custom page type called Events that is used to show all
events for a specific day via the /events/year/month/day path. (This replaces
the events show template that was previously used.) A default events page is
installed unless a page with a slug named `events` already exists.

When used in an Events page, the <r:events> tag does not take any attributes.

== Example

To display a calendar of the current month, use

  <r:calendar />

The month and year tags can be added to display a calendar for a specific month.

  <r:calendar year='2008' month='8' />

You can iterate over all events like so:

  <r:events>
    <dl>
      <r:each>
        <dt><r:event:name /></dt>
        <dd><r:event:time /></dd>
        <dd><r:event:location /></dd>
        <dd><r:event:description /></dd>
      </r:each>
    </dl>
  </r:events>

For today's events:

  <r:events for="today">
    <r:each>
      ...
    </r:each>
  </r:events>

For some other day's events:

  <r:events for="2009-03-14">
    <r:each>
      ...
    </r:each>
  </r:events>

Other options that you can put in the events tag (similar to children:each):
* by (default: start_date)
* order (default: asc)
* limit
* offset
* category

Special dates in the `for` option:
* today
* tomorrow
* yesterday

Relative date periods can also be used in the `for` option:
* next 1 week
* next 3 days
* previous 2 months
* any period matching the regexp `/(next|previous) \d+ (day|week|month|year)s?/`

When specifying a relative date period, the `inclusive` attribute can also be
specified to control whether the current day is included in the range. The
default setting `inclusive="true"` included the current day, but if `inclusive`
is set to any other value the current day is excluded from the returned value.

== Dependencies

This extension depends on, and includes, the following plugins:

* auto_complete <http://github.com/rails/auto_complete>
* calendar_date_select <http://github.com/timcharper/calendar_date_select>
* calendar_helper <http://github.com/topfunky/calendar_helper>
* simple_time_select <http://github.com/tamoyal/simple_time_select>

== Contributors

David Cato (davec)
Jeremy Stephens (viking)