| 1 |
=== iCal Events === |
|---|
| 2 |
Tags: calendar, events |
|---|
| 3 |
Contributors: dwc |
|---|
| 4 |
|
|---|
| 5 |
A plugin for getting and displaying upcoming events from a shared calendar. |
|---|
| 6 |
|
|---|
| 7 |
This plugin uses <a href="http://cvs.sourceforge.net/viewcvs.py/webcalendar/webcalendar/import_ical.php?rev=HEAD">import_ical.php</a> from the <a href="http://sourceforge.net/projects/webcalendar/">WebCalendar</a> project. A slightly modified version of their parser is provided with this plugin. |
|---|
| 8 |
|
|---|
| 9 |
== Installation == |
|---|
| 10 |
|
|---|
| 11 |
1. Upload `ical-events.php` and `import_ical.php` to your plugins folder, usually `wp-content/plugins`. |
|---|
| 12 |
2. Activate the plugin on the Plugins screen. |
|---|
| 13 |
3. Place the following in your template: |
|---|
| 14 |
|
|---|
| 15 |
`<?php ICalEvents::display_events('url=http://www.ufl.edu/calendar/ufCalendar.ics&limit=3&gmt_start=' . time()); ?>` |
|---|
| 16 |
|
|---|
| 17 |
This example displays three events from the University of Florida calendar, from the current time forward. For more information, see below. |
|---|
| 18 |
|
|---|
| 19 |
== Frequently Asked Questions == |
|---|
| 20 |
|
|---|
| 21 |
= How can I control the output of this plugin? = |
|---|
| 22 |
|
|---|
| 23 |
The `display_events` function takes the following arguments: |
|---|
| 24 |
* `url`: The URL of the iCal file. |
|---|
| 25 |
* `gmt_start` (optional): Only events from this time forward are displayed. If not specified, the earliest events are displayed. |
|---|
| 26 |
* `gmt_end` (optional): Only events before this time are displayed. |
|---|
| 27 |
* `limit` (optional): The maximum number of events to display. |
|---|
| 28 |
* `date_format` (optional): The format string used to format dates` (see <a href="http://php.net/strftime">strftime documentation</a>). Default: `%a %b %e`. |
|---|
| 29 |
* `time_format` (optional): The format string used to format times. Default: `%l:%M %p`. |
|---|
| 30 |
* `before` (optional): HTML or text to display before each event. Default: `<li>`. |
|---|
| 31 |
* `after` (optional): HTML or text to display after each event. Default: `</li>`. |
|---|
| 32 |
* `before_date` (optional): HTML or text to display before each event's date. Default: `<strong>`. |
|---|
| 33 |
* `after_date` (optional): HTML or text to display after each event's date. Default: `</strong>: `. |
|---|
| 34 |
* `use_summary` (optional): Whether or not to use the event summary in the output. Default: `true`. |
|---|
| 35 |
* `before_summary` (optional): HTML or text to display before each event's summary. Default: Empty string. |
|---|
| 36 |
* `after_summary` (optional): HTML or text to display after each event's summary. Default: ` - `. |
|---|
| 37 |
* `use_description` (optional): Whether or not to use the event description in the output. Default: `true`. |
|---|
| 38 |
* `before_description` (optional): HTML or text to display before each event's description. Default: Empty string. |
|---|
| 39 |
* `after_description` (optional): HTML or text to display after each event's description. Default: Empty string. |
|---|
| 40 |
* `replace_newlines_with` (optional): String with which to replace newlines in the description. Default: `<br />`. |
|---|
| 41 |
* `use_location` (optional): Whether or not to use the event location in the output. If false, only the summary is used. Default: `true`. |
|---|
| 42 |
* `before_location` (optional): HTML or text to display before each event's location. Default: `` (`. |
|---|
| 43 |
* `after_location` (optional): HTML or text to display after each event's location. Default: `)`. |
|---|
| 44 |
* `use_url` (optional): Whether or not to use the event URL in the output. If true, the event URL is made into a link around the event summary. Default: `true`. |
|---|
| 45 |
* `echo` (optional): Whether or not to directly display the events. Default: `true`. |
|---|
| 46 |
|
|---|
| 47 |
For example, if you want to hide the description and location, you could use something like the following: |
|---|
| 48 |
|
|---|
| 49 |
`<?php ICalEvents::display_events('url=http://www.ufl.edu/calendar/ufCalendar.ics&limit=3&use_description=0&use_location=0&gmt_start=' . time()); ?>` |
|---|
| 50 |
|
|---|
| 51 |
If you need more control over the output, use the `get_events` function, which takes the following arguments: |
|---|
| 52 |
* `url: The URL of the iCal file. |
|---|
| 53 |
* `gmt_start` (optional): Only events from this time forward are displayed. If not specified, the earliest events are displayed. |
|---|
| 54 |
* `gmt_end` (optional): Only events before this time are displayed. |
|---|
| 55 |
* `limit` (optional): The maximum number of events to display. |
|---|
| 56 |
|
|---|
| 57 |
The function returns an array of events, as parsed by `import_ical.php`. For example usage, refer to the `display_events` function in the plugin. |
|---|
| 58 |
|
|---|
| 59 |
= How often is the calendar checked for new events? = |
|---|
| 60 |
|
|---|
| 61 |
Once a day. You can change this using the ICAL_EVENTS_CACHE_LIFETIME near the top of the plugin. |
|---|
| 62 |
|
|---|
| 63 |
= Does the plugin support repeating events? = |
|---|
| 64 |
|
|---|
| 65 |
This plugin makes an attempt to support repeating events. However, not all recurrence rules are implemented in the parser. There may also be bugs in how the plugin interprets the parsed data. |
|---|
| 66 |
|
|---|
| 67 |
= Where can I find iCal files? = |
|---|
| 68 |
|
|---|
| 69 |
There are many iCal sources, such as: |
|---|
| 70 |
* <a href="http://www.apple.com/ical/library/">Apple's iCal library</a> |
|---|
| 71 |
* <a href="http://www.icalshare.com/">iCalShare</a> |
|---|
| 72 |
* <a href="http://calendar.google.com/">Google Calendar</a> |
|---|
