davec / radiant-events-calendar-extension

= Events Calendar

A calendar of events for Radiant CMS.

Note: This version of the events_calendar extension is compatible with Radiant 0.8.
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

This extension relies on the share_layouts extension, so install it first if you
are not already using it:

  git clone git://github.com/radiant/radiant-share-layouts-extension.git vendor/extensions/share_layouts

Edit config/environment.rb to force share_layouts to load first:

  config.extensions = [ :share_layouts, :all ]

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 library, so it must
also be added if it is not already included. 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/events_calendar.js"></script>

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

As distributed, the template for individual event listings does not include any
snippets or other page formatting beyond the listings themselves. You should alter
vendor/extensions/events_calendar/app/views/events/show.html.haml as appropriate
for your site.

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