1
|
Date iCal
|
2
|
|
3
|
This module allows users to export iCal feeds using Views, and import iCal feeds
|
4
|
from other sites using Feeds. Any entity that contains a Date field can act as
|
5
|
the source/target to export/import an iCal feed.
|
6
|
|
7
|
|
8
|
===============================================================================
|
9
|
INSTALLATION
|
10
|
===============================================================================
|
11
|
Date iCal has several required dependencies, and an optional one:
|
12
|
- The Views (version 3.5+), Entity API, Libraries API (version 2.0+), and Date
|
13
|
modules are required.
|
14
|
- The iCalcreator library is required.
|
15
|
- PHP 5.3 is required for the iCalcreator library to properly handle timezones.
|
16
|
- The Feeds module is optional. It's needed only if you you wish to import iCal
|
17
|
feeds from other sites.
|
18
|
|
19
|
To install the iCalcreator library, download the project's official zip file:
|
20
|
https://github.com/iCalcreator/iCalcreator/archive/master.zip
|
21
|
Extract it, and copy iCalcreator.class.php to a folder in your Drupal site
|
22
|
named sites/all/libraries/iCalcreator (you'll need to create that folder).
|
23
|
|
24
|
Or, if you have drush, you can install iCalcreator by running this command from
|
25
|
your site's root directory:
|
26
|
drush make sites/all/modules/date_ical/date_ical.make --no-core
|
27
|
|
28
|
Then, clear the cache on your site by using either "drush cc all" or logging in
|
29
|
to your site and going to Configuration -> Development -> Performance and click
|
30
|
the "Clear all caches" button. This is necessary because libraries are cached,
|
31
|
and you may see confusing behavior from Date iCal if the iCalcreator library
|
32
|
gets cached at a bad time.
|
33
|
|
34
|
To confirm that iCalcreator is installed correctly, log in to your Drupal site
|
35
|
and navigate to the admin/reports/status page. If the row titled "Date iCal" is
|
36
|
green, Date iCal is ready to go. If it's red, the iCalcreator library is not
|
37
|
properly installed. If it's missing, you'll need to enable Date iCal.
|
38
|
|
39
|
|
40
|
===============================================================================
|
41
|
EXPORTING AN ICAL FEED USING Views
|
42
|
===============================================================================
|
43
|
There are two plugins that export iCal feeds. You can use either one, though
|
44
|
the iCal Fields plugin (described later) is a bit more versatile.
|
45
|
|
46
|
HOW TO EXPORT AN ICAL FEED USING THE iCal Entities PLUGIN
|
47
|
|
48
|
1. Go to the Manage Display page for the content type you want to export in an
|
49
|
iCal feed. On the "Default" tab, check the box for "iCal" in the section
|
50
|
titled "Use custom display settings for the following view modes", then
|
51
|
click Save.
|
52
|
2. Click the new "iCal" tab that now appears in the upper-right corner of the
|
53
|
Manage Display page for this content type.
|
54
|
3. Set up the iCal view mode to contain whatever should be exported as the
|
55
|
'Description' field for the iCal feed. You can trim the text to the desired
|
56
|
size, include additional information from other fields, etc.
|
57
|
4. Do this for each of the content types that you wish to include in your
|
58
|
site's iCal feeds.
|
59
|
5. Create a new View that displays the entities that you want to include in
|
60
|
the iCal feed.
|
61
|
6. Add a "Feed" display to the same View. Change the Format to "iCal Feed".
|
62
|
When you click "Apply" from that dialog, you'll be given the option to name
|
63
|
the calendar, which will appear in your users' calendar clients as the
|
64
|
calendar's title.
|
65
|
7. Change the Show setting to "iCal Entity".
|
66
|
8. In the settings for iCal Entity, select the date field that should be used
|
67
|
as the event date for the iCal feed. Make sure that you choose a field that
|
68
|
is a part of every entity that your View displays. Otherwise, the entities
|
69
|
which don't have that field will be left out of the iCal feed.
|
70
|
9. You may optionally choose a field that will be used to populate the
|
71
|
Location property of events in your iCal feed. This field can be a text
|
72
|
field, a Node Reference field, an Addressfield, or a Location field.
|
73
|
10. Give the Feed a path like 'calendar/%/export.ics', including a '/%/' for
|
74
|
every contextual filter in the view.
|
75
|
11. Make sure the Pager options are set to "Display all items".
|
76
|
12. Add date filters or arguments that will constrain the view to the items you
|
77
|
want to be included in the iCal feed.
|
78
|
13. Using the "Attach to:" setting in the Feed Settings panel, attach the feed
|
79
|
to a another display in the same view (usually a Page display). Be aware,
|
80
|
though, that the Feed will display exactly what its settings tell it to,
|
81
|
regardless of how the Page display is set up. Thus, it's best to ensure
|
82
|
that both displays are configured to include the same content.
|
83
|
14. Save the View.
|
84
|
15. Navigate to a page which displays the view (usually the Page display's
|
85
|
"path" setting). You should see the iCal icon at the bottom of the view's
|
86
|
output. Clicking on the icon will subscribe your calendar app to the iCal
|
87
|
feed.
|
88
|
16. If you don't have a calendar app set up on your computer, or you want your
|
89
|
users to download the ical feed rather than subscribe to it, you'll want to
|
90
|
go back to the View settings page, click the Settings link next to
|
91
|
"Format: iCal Feed", and check "Disable webcal://". Then save your View.
|
92
|
This will make the iCal icon download a .ics file with the events, instead
|
93
|
of loading the events directly into the user's calendar app.
|
94
|
|
95
|
HOW TO EXPORT AN ICAL FEED USING THE iCal Fields PLUGIN
|
96
|
1-6.These steps are the same as above.
|
97
|
7. Add views fields for each piece of information that you want to populate
|
98
|
your iCal feed with. A Date field is required, and fields that will act as
|
99
|
the Title and Description of the events are reccomended. You can also
|
100
|
include a Location field.
|
101
|
8. Back in the FORMAT section, change the "Show" setting to 'iCal Fields'.
|
102
|
9. In the settings for iCal Fields, choose which views fields you want to use
|
103
|
for the Date, Title, Description, and Location.
|
104
|
10+ These steps are the same as above.
|
105
|
|
106
|
|
107
|
===============================================================================
|
108
|
IMPORTING AN ICAL FEED FROM ANOTHER SITE USING Feeds
|
109
|
===============================================================================
|
110
|
- Install the Feeds module, which is the framework upon which Date iCal's
|
111
|
import functionality is built.
|
112
|
- Login to your Drupal site and navigate to the admin/structure/feeds page.
|
113
|
- Click the "Add importer" link, and give it a name and description.
|
114
|
- Clicking "Create" will bring you to the general Feeds importer settings page.
|
115
|
This page displays some general information about making Feeds importers,
|
116
|
which you should familiarize yourself with.
|
117
|
- In the left sidebar, you'll see "Basic settings", "Fetcher", "Parser", and
|
118
|
"Processor". The Parser and Processor settings are what we're interested in.
|
119
|
- In the Parser section, click "change". This will bring up the Parser
|
120
|
selection page, on which you should select the radio button for "iCal Parser"
|
121
|
and then click Save.
|
122
|
- Now, under Processor, click the "Settings" link. Most of the time, you'll
|
123
|
want to use the "Update existing nodes (slower than replacing them)" setting.
|
124
|
Then select the Content type of the nodes you'd like to create from iCal
|
125
|
events. You can leave the other settings as their defeaults, or change them
|
126
|
as you need. Click Save.
|
127
|
- Now click the "Mapping" link at the bottom of the left sidebar. This page is
|
128
|
where you'll define how iCal event properties get mapped into your nodes'
|
129
|
fields. Expand the "Legend" for a detailed description of each source and
|
130
|
target field. Sources are the attributes available in iCal event objects,
|
131
|
and Targets are the fields in your nodes.
|
132
|
- Most of this setup is going to be dependant upon how your content type's
|
133
|
fields are configured, but there are some universal requirements:
|
134
|
1) You MUST map the "UID" source to the "GUID" target. Then, after clicking
|
135
|
"Add", click the gear-shaped button that appears in the new table row,
|
136
|
and check the "Unique" checkbox. Then click "Update", and then before
|
137
|
you add any more mappings, click "Save" at the bottom of the page.
|
138
|
2) It's a good idea to map the "Summary/Title" source to the "Title" target,
|
139
|
and the "Description" source to whatever field is the "body" of the node.
|
140
|
3) AS OF 2014/04/10 THERE IS A MAJOR BUG IN Feeds WHICH LEAVES THE DATE
|
141
|
VALUES ON ALL IMPORTED EVENTS BLACNK. YOU MUST APPLY A PATCH TO Feeds
|
142
|
TO FIX THIS PROBLEM. IT IS AVAILABLE HERE: http://drupal.org/node/2237177.
|
143
|
- Once you've completed all the mappings, click the "Save" button on the
|
144
|
bottom left side of the page.
|
145
|
- Now you can import the iCal feed into nodes by going to the /import page of
|
146
|
your site (e.g. http://www.exmaple.com/import). Click the link for the
|
147
|
importer you just created, and enter the URL of the feed into the "URL"
|
148
|
field. Click the "Import" button, and observe the progress.
|
149
|
- Once it's done, you should see a green message saying "Created X nodes." If
|
150
|
you do, you've successfully set up your iCal importer. If you get some other
|
151
|
message, you'll need to tweak the importer's settings.
|
152
|
|
153
|
Remember, you have to map the UID source to the GUID target, and make it
|
154
|
unique, or your imports won't work!
|
155
|
|
156
|
|
157
|
===============================================================================
|
158
|
IMPORTANT NOTE ABOUT THE DATE FIELD TIMEZONE SETTING
|
159
|
===============================================================================
|
160
|
Date fields have a setting called "Time zone handling" which determines how
|
161
|
dates are stored in the database, and how they are displayed to users.
|
162
|
- "Site's time zone" converts the date to UTC as it stores it to the DB. Upon
|
163
|
display, it converts the date to the "Default time zone" that's set on your
|
164
|
site's Regional Settings configuration page (/admin/config/regional/settings).
|
165
|
- "Date's time zone" stores the date as it is entered, along with the timezone
|
166
|
name. Upon display, it converts the date from the stored timezone into the
|
167
|
site's default timezone. Well, I'm pretty sure it's *supposed* to do that, but
|
168
|
the code behind this setting is very buggy. DO NOT USE THIS SETTING.
|
169
|
- "User's time zone" converts the date to UTC as it stores it to the DB. Upon
|
170
|
display, it converts the date to the current user's timezone setting.
|
171
|
- "UTC" converts the date to UTC as it stores it to the DB. Upon display, it
|
172
|
performs no conversion, showing the UTC date directly to the user.
|
173
|
- "No time zone conversion" performs no conversion as it stores the date in
|
174
|
the DB. It also performs no conversion upon display.
|
175
|
|
176
|
The appropriate setting to choose here will depend upon how you want times to
|
177
|
be displayed on your site. The best setting *would* be "Date's time zone",
|
178
|
but since that setting is so buggy, I must recommend against it. Instead,
|
179
|
I'd suggest using "Site's time zone" for sites which host events that are
|
180
|
mostly in the same timezone (set the site's default timezone appropriately).
|
181
|
This works just right for local users of your site, and will be the least
|
182
|
confusing for users who live in a different timezone.
|
183
|
|
184
|
For sites which store events that take place in multiple different timezones,
|
185
|
the "User's time zone" setting is probably the most appropriate. Most users will
|
186
|
presumably be tuning in to your events online or on TV (since many take place
|
187
|
far away from them), which means they'll want to know what time the event occurs
|
188
|
in their local timezone, so they don't miss the broadcast.
|
189
|
|
190
|
If your Date field is already set to "Date's time zone", you won't be able to
|
191
|
change it, because that setting uses a different table schema than the others.
|
192
|
Since "Date's time zone" is very buggy, I'd strongly recomend deleting the
|
193
|
field and recreating it with a different setting. This will delete all the
|
194
|
dates in existing event nodes which use this field.
|
195
|
|
196
|
|
197
|
===============================================================================
|
198
|
HOW TO FIX THE "not a valid timezone" ERROR
|
199
|
===============================================================================
|
200
|
If you are seeing a warning about invalid timezones when you import an iCal
|
201
|
feed, you'll need to implement hook_date_ical_import_timezone_alter() in a
|
202
|
custom module to fix it. To do so, either edit an existing custom module, or
|
203
|
make a new module and add this function to it:
|
204
|
|
205
|
<?php
|
206
|
/**
|
207
|
* Implements hook_date_ical_import_timezone_alter().
|
208
|
*/
|
209
|
function <module>_date_ical_import_timezone_alter(&$tzid, $context) {
|
210
|
if (!empty($tzid)) {
|
211
|
// Do something to fix your invalid timezone.
|
212
|
// For instance, if all your events take place in one timezone, find your
|
213
|
// region's official TZID, and replace $tzid with it. Like this:
|
214
|
// $tzid = 'America/Los_Angeles';
|
215
|
}
|
216
|
}
|
217
|
?>
|
218
|
|
219
|
Replace <module> with the name of your module, change the code to do whatever
|
220
|
needs to be done to fix your timezones, and clear your Drupal cache.
|
221
|
|
222
|
|
223
|
===============================================================================
|
224
|
ADDITIONAL NOTES
|
225
|
===============================================================================
|
226
|
Date iCal only supports exporting iCal calendars by using Views.
|
227
|
To put an "Add to calendar" button on individual event nodes, try the
|
228
|
Add to Cal module (http://drupal.org/project/addtocal), or follow the
|
229
|
instructions created by the estimable nmc at:
|
230
|
http://nmc-codes.blogspot.ca/2012/11/creating-ical-feed-for-single-node-in.html
|
231
|
|
232
|
The Feeds Tamper module is useful for altering the data in imported iCal feeds.
|
233
|
|
234
|
Developers who wish to implement more powerful manipulation of event data can
|
235
|
read the date_ical.api.php file to learn about the various alter hooks that
|
236
|
date_ical exposes.
|
237
|
|
238
|
The libraries/windowsZones.json file, which Date iCal uses to map Windows-style
|
239
|
timezone names to real timezone IDs, is from Version24 of the Unicode CLDR:
|
240
|
http://cldr.unicode.org/.
|