Commit 227650e3 authored by Robert Rollins's avatar Robert Rollins

Updated the README, added new tests, implemented hook_help().

parent d2491d2e
Date iCal
This module allows users to export iCal feeds with Views, and import iCal feeds
from other sites with Feeds. Any Entity can act as the source of events for an
iCal feed, as long as that entity contains a Date field. Date
iCal creates a new iCal "view mode" for all entities, which is used to format
the Description field of the events in the iCal feed (when using the iCal
Entity plugin).
For an easier-to-read HTML version of these instructions, please go to
http://www.drupal.org/project/date_ical and click the "Read documentation" link
in the Resources section of the right sidebar.
This module allows users to export iCal feeds using Views, and import iCal feeds
from other sites using Feeds. Any entity that contains a Date field can act as
the source of events for an iCal feed.
===============================================================================
INSTALLATION
===============================================================================
Date iCal has several required dependencies, and an optional one:
- The Views (version 3.5+), Entity API, Libraries API (version 2.0), and Date
- The Views (version 3.5+), Entity API, Libraries API (version 2.0+), and Date
modules are required.
- The iCalcreator library is required.
- PHP 5.3 is required by the iCalcreator library to properly handle timezone
data. Date iCal *might* work with PHP 5.2, but that configuration is
untested and unsupported.
- The Feeds module is optional, but it's needed to enable import of iCal feeds
from other sites.
- PHP 5.3 is required for the iCalcreator library to properly handle timezones.
- The Feeds module is optional. It's needed only if you you wish to import iCal
feeds from other sites.
To install the iCalcreator library, download it from the project's github:
http://github.com/iCalcreator/iCalcreator
......@@ -34,24 +25,23 @@ Or, if you have drush, install iCalcreator by running this command from your
site's root directory:
drush make sites/all/modules/date_ical/date_ical.make --no-core
Then clear the cache on your site, by using either "drush cc all"
or logging in to your site and going to Configuration -> Development ->
Performance and click the "Clear all caches" button. This is necessary because
libraries are cached, and you may see confusing behavior from Date iCal if the
iCalcreator library gets cached at a bad time.
Then, clear the cache on your site by using either "drush cc all" or logging in
to your site and going to Configuration -> Development -> Performance and click
the "Clear all caches" button. This is necessary because libraries are cached,
and you may see confusing behavior from Date iCal if the iCalcreator library
gets cached at a bad time.
To confirm that iCalcreator is installed correctly, log in to your Drupal site
and navigate to the admin/reports/status page. If the row titled "Date iCal" is
green, Date iCal is ready to go. If it's red, the iCalcreator library is not
properly installed. If it's missing, you'll need to enable Date iCal and then
come back to this page.
properly installed. If it's missing, you'll need to enable Date iCal.
===============================================================================
EXPORTING AN ICAL FEED USING Views
===============================================================================
There are two plugins that export iCal feeds. You can use either one, though
the iCal Fields plugin is a bit more versatile.
the iCal Fields plugin (described later) is a bit more versatile.
HOW TO EXPORT AN ICAL FEED USING THE iCal Entities PLUGIN
......@@ -68,19 +58,19 @@ HOW TO EXPORT AN ICAL FEED USING THE iCal Entities PLUGIN
site's iCal feeds.
5. Create a new View that displays the entities that you want to include in the
iCal feed.
6. Add a "Feed" to the view. Change the Format to 'iCal Feed'. When you click
6. Add a "Feed" to the view. Change the Format to "iCal Feed". When you click
Apply from that dialog, you'll be given the option to name the calendar,
which will appear in your users' calendar clients as the calendar's title.
7. Change the Show setting to 'iCal Entity'.
7. Change the Show setting to "iCal Entity".
8. In the settings for iCal Entity, select the date field that should be used
as the event date for the iCal feed. Make sure that you choose a field that
is a part of every entity that your View displays. Otherwise, the entities
which don't have that field will be left out of the iCal feed.
9. You may optionally choose a field that will be used to populate the Location
property of events in your iCal feed. This field can be either a text field
or a Node Reference field, in which case the title of the node will be used.
10. Give the feed a path like 'calendar/%/export.ics', where you have a
'/%/' for every contextual filter in the view.
property of events in your iCal feed. This field can be a text field, a
Node Reference field, an Addressfield, or a Location field.
10. Give the feed a path like 'calendar/%/export.ics', including a '/%/' for
every contextual filter in the view.
11. Make sure the Pager options are set to "Display all items".
12. Add date filters or arguments that will constrain the view to the items you
want to be included in the iCal feed.
......@@ -91,9 +81,9 @@ HOW TO EXPORT AN ICAL FEED USING THE iCal Entities PLUGIN
14. Save the View.
15. Navigate to a page which displays the attached view. You should see the iCal
icon at the bottom of the view's output. Clicking on the icon will subscribe
your preferred calendar app the iCal feed. However, if you don't have a
your preferred calendar app to the iCal feed. However, if you don't have a
calendar app set up on your computer, you'll want to go back to the View
settings page, click the Settings link next to "Format:iCal Feed", and check
settings page, click the Settings link next to "Format: iCal Feed", and check
"Disable webcal://", then save your View. This will make the iCal icon
download a .ics file with the events, instead of loading the events directly
into a calendar app.
......@@ -118,7 +108,7 @@ IMPORTING AN ICAL FEED FROM ANOTHER SITE USING Feeds
- Login to your Drupal site and navigate to the admin/structure/feeds page.
- Click the "Add importer" link, and give it a name and description.
- Clicking "Create" will bring you to the general Feeds importer settings page.
This page displays some general information about makign Feeds importers,
This page displays some general information about making Feeds importers,
which you should familiarize yourself with.
- In the left sidebar, you'll see "Basic settings", "Fetcher", "Parser", and
"Processor". The Parser and Processor settings are what we're interested in.
......@@ -141,8 +131,11 @@ IMPORTING AN ICAL FEED FROM ANOTHER SITE USING Feeds
"Add", click the gear-shaped button that appears in the new table row,
and check the "Unique" checkbox. Then click "Update", and then before
you add any more mappings, click "Save" at the bottom of the page.
3) It's a good idea to map the "Summary/Title" source to the "Title" target,
2) It's a good idea to map the "Summary/Title" source to the "Title" target,
and the "Description" source to whatever field is the "body" of the node.
3) As of 2014/02/03 there is a major bug in Feeds that leaves the Date
values on all imported events blank. You must update your Feeds module
to the dev release (https://drupal.org/node/927032) to overcome this bug.
- Once you've completed all the mappings, click the "Save" button on the
bottom left side of the page.
- Now you can import the iCal feed into nodes by going to the /import page of
......@@ -157,9 +150,7 @@ IMPORTING AN ICAL FEED FROM ANOTHER SITE USING Feeds
Remember, you have to map the UID source to the GUID target, and make it
unique, or your imports won't work!
===============================================================================
IMPORTANT NOTE:
===============================================================================
If you're building a site that will be viewed by out-of-state users, and you
allow said users to set their own timezone, you'll want to set up your Date
fields to use the "Date's time zone" option. If you don't, then users who live
......@@ -193,20 +184,21 @@ function <module>_date_ical_import_timezone_alter(&$tzid, $context) {
Replace <module> with the name of your module, change the code to do whatever
needs to be done to fix your timezones, and clear your Drupal cache.
Additional Notes:
At this time, Date iCal only supports outputting iCal calendars through Views.
===============================================================================
ADDITIONAL NOTES
===============================================================================
Date iCal only supports outputting iCal calendars through Views.
To put an "Add to calendar" button on individual event nodes, try the
<a href="http://drupal.org/project/addtocal">Add to Cal</a> module, or follow
the instructions created by the estimable nmc at:
Add to Cal module (http://drupal.org/project/addtocal), or follow the
instructions created by the estimable nmc at:
http://nmc-codes.blogspot.ca/2012/11/creating-ical-feed-for-single-node-in.html
The Feeds Tamper module is quite useful for manipulating the data in imported
iCal feeds.
The Feeds Tamper module is useful for altering the data in imported iCal feeds.
Developers who wish to implement more powerful manipulation of event data can
read the date_ical.api.php file to learn about the various alter hooks that
date_ical exposes.
The libraries/windowsZones.json file is from Version24 of the Unicode CLDR:
The libraries/windowsZones.json file, which Date iCal uses to map Windows-style
timezone names to real timezone IDs, is from Version24 of the Unicode CLDR:
http://cldr.unicode.org/.
......@@ -185,8 +185,7 @@ function date_ical_libraries_info() {
function date_ical_help($path, $arg) {
switch ($path) {
case 'admin/help#date_ical':
// Return a line-break version of the module README.txt
return check_markup(file_get_contents(dirname(__FILE__) . "/README.txt"));
return '<pre>' . file_get_contents(drupal_get_path('module', 'date_ical') . "/README.txt") . '</pre>';
}
}
......
......@@ -43,11 +43,11 @@ DESCRIPTION:This is a standard 2-hour event in America/New_York.
END:VEVENT
BEGIN:VEVENT
SUMMARY:Broken Event (Central Standard Time)
SUMMARY:Central Standard Time Event
DTSTART;TZID=Central Standard Time:20131009T190000
DTEND;TZID=Central Standard Time:20131009T210000
UID:date_ical_basic_test03
DESCRIPTION:This event uses a deprecated TZID, Central Standard Time, and should be treated as UTC.
DESCRIPTION:This event uses a Windows TZID, Central Standard Time, and will be parsed correctly only in Date iCal 3.1+.
END:VEVENT
BEGIN:VEVENT
......@@ -124,4 +124,12 @@ UID:date_ical_basic_test0C
DESCRIPTION:This event has several escaped characters right here:\,\;\\\n\NThis text should be 2 lines down from the rest.
END:VEVENT
BEGIN:VEVENT
SUMMARY:Bad TZID Event
DTSTART;TZID=Fake TZID:20131009T190000
DTEND;TZID=Fake TZID:20131009T210000
UID:date_ical_basic_test0D
DESCRIPTION:This event uses a fake TZID and should throw the "not a valid timezone" warning at import time, and be treated as UTC.
END:VEVENT
END:VALENDAR
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment