Revision 55670b15
Added by Assos Assos over 10 years ago
drupal7/sites/all/modules/date_ical/README.txt | ||
---|---|---|
2 | 2 |
|
3 | 3 |
This module allows users to export iCal feeds using Views, and import iCal feeds |
4 | 4 |
from other sites using Feeds. Any entity that contains a Date field can act as |
5 |
the source of events for an iCal feed. |
|
5 |
the source/target to export/import an iCal feed. |
|
6 |
|
|
6 | 7 |
|
7 | 8 |
=============================================================================== |
8 | 9 |
INSTALLATION |
... | ... | |
15 | 16 |
- The Feeds module is optional. It's needed only if you you wish to import iCal |
16 | 17 |
feeds from other sites. |
17 | 18 |
|
18 |
To install the iCalcreator library, download it from the project's github: |
|
19 |
http://github.com/iCalcreator/iCalcreator |
|
20 |
Using either git clone or the "Download Zip" button, you'll find the file |
|
21 |
iCalcreator.class.php inside. Copy that file to a folder in your Drupal site |
|
22 |
named sites/all/libraries/iCalcreator. |
|
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 | 23 |
|
24 |
Or, if you have drush, install iCalcreator by running this command from your
|
|
25 |
site's root directory: |
|
24 |
Or, if you have drush, you can install iCalcreator by running this command from
|
|
25 |
your site's root directory:
|
|
26 | 26 |
drush make sites/all/modules/date_ical/date_ical.make --no-core |
27 | 27 |
|
28 | 28 |
Then, clear the cache on your site by using either "drush cc all" or logging in |
... | ... | |
56 | 56 |
size, include additional information from other fields, etc. |
57 | 57 |
4. Do this for each of the content types that you wish to include in your |
58 | 58 |
site's iCal feeds. |
59 |
5. Create a new View that displays the entities that you want to include in the |
|
60 |
iCal feed. |
|
61 |
6. Add a "Feed" to the view. Change the Format to "iCal Feed". When you click |
|
62 |
Apply from that dialog, you'll be given the option to name the calendar, |
|
63 |
which will appear in your users' calendar clients as the calendar's title. |
|
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. |
|
64 | 65 |
7. Change the Show setting to "iCal Entity". |
65 | 66 |
8. In the settings for iCal Entity, select the date field that should be used |
66 | 67 |
as the event date for the iCal feed. Make sure that you choose a field that |
67 | 68 |
is a part of every entity that your View displays. Otherwise, the entities |
68 | 69 |
which don't have that field will be left out of the iCal feed. |
69 |
9. You may optionally choose a field that will be used to populate the Location
|
|
70 |
property of events in your iCal feed. This field can be a text field, a
|
|
71 |
Node Reference field, an Addressfield, or a Location field. |
|
72 |
10. Give the feed a path like 'calendar/%/export.ics', including a '/%/' for
|
|
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
|
|
73 | 74 |
every contextual filter in the view. |
74 | 75 |
11. Make sure the Pager options are set to "Display all items". |
75 | 76 |
12. Add date filters or arguments that will constrain the view to the items you |
76 | 77 |
want to be included in the iCal feed. |
77 |
13. Attach the feed to a another view (usually a Page view that is displaying |
|
78 |
the same events). Be aware, though, that attaching the feed to a view with |
|
79 |
different output will not make the iCal feed include that output. It will |
|
80 |
always include the events which match the feed's filters. |
|
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. |
|
81 | 83 |
14. Save the View. |
82 |
15. Navigate to a page which displays the attached view. You should see the iCal |
|
83 |
icon at the bottom of the view's output. Clicking on the icon will subscribe |
|
84 |
your preferred calendar app to the iCal feed. However, if you don't have a |
|
85 |
calendar app set up on your computer, you'll want to go back to the View |
|
86 |
settings page, click the Settings link next to "Format: iCal Feed", and check |
|
87 |
"Disable webcal://", then save your View. This will make the iCal icon |
|
88 |
download a .ics file with the events, instead of loading the events directly |
|
89 |
into a calendar app. |
|
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. |
|
90 | 94 |
|
91 | 95 |
HOW TO EXPORT AN ICAL FEED USING THE iCal Fields PLUGIN |
92 | 96 |
1-6.These steps are the same as above. |
... | ... | |
94 | 98 |
your iCal feed with. A Date field is required, and fields that will act as |
95 | 99 |
the Title and Description of the events are reccomended. You can also |
96 | 100 |
include a Location field. |
97 |
8. Back in the FORMAT section, change the Show setting to 'iCal Fields'.
|
|
101 |
8. Back in the FORMAT section, change the "Show" setting to 'iCal Fields'.
|
|
98 | 102 |
9. In the settings for iCal Fields, choose which views fields you want to use |
99 | 103 |
for the Date, Title, Description, and Location. |
100 | 104 |
10+ These steps are the same as above. |
... | ... | |
133 | 137 |
you add any more mappings, click "Save" at the bottom of the page. |
134 | 138 |
2) It's a good idea to map the "Summary/Title" source to the "Title" target, |
135 | 139 |
and the "Description" source to whatever field is the "body" of the node. |
136 |
3) As of 2014/02/03 there is a major bug in Feeds that leaves the Date
|
|
137 |
values on all imported events blank. You must update your Feeds module
|
|
138 |
to the dev release (https://drupal.org/node/927032) to overcome this bug.
|
|
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.
|
|
139 | 143 |
- Once you've completed all the mappings, click the "Save" button on the |
140 | 144 |
bottom left side of the page. |
141 | 145 |
- Now you can import the iCal feed into nodes by going to the /import page of |
142 | 146 |
your site (e.g. http://www.exmaple.com/import). Click the link for the |
143 |
importer you just created, and enter the URL of the feed you'd like to |
|
144 |
import into the "URL" field. Click the "Import" button, and observe the |
|
145 |
progress. |
|
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. |
|
146 | 149 |
- Once it's done, you should see a green message saying "Created X nodes." If |
147 | 150 |
you do, you've successfully set up your iCal importer. If you get some other |
148 | 151 |
message, you'll need to tweak the importer's settings. |
... | ... | |
150 | 153 |
Remember, you have to map the UID source to the GUID target, and make it |
151 | 154 |
unique, or your imports won't work! |
152 | 155 |
|
153 |
IMPORTANT NOTE: |
|
154 |
If you're building a site that will be viewed by out-of-state users, and you |
|
155 |
allow said users to set their own timezone, you'll want to set up your Date |
|
156 |
fields to use the "Date's time zone" option. If you don't, then users who live |
|
157 |
in a different timezone will be shown the times for your events in their local |
|
158 |
timezone, rather than your events' timezone. This makes sense if your events |
|
159 |
will be broadcast live to these out-of-state users, but if they need to travel |
|
160 |
to your event, they may end up arriving at the wrong time. |
|
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 |
|
|
161 | 196 |
|
162 | 197 |
=============================================================================== |
163 | 198 |
HOW TO FIX THE "not a valid timezone" ERROR |
... | ... | |
184 | 219 |
Replace <module> with the name of your module, change the code to do whatever |
185 | 220 |
needs to be done to fix your timezones, and clear your Drupal cache. |
186 | 221 |
|
222 |
|
|
187 | 223 |
=============================================================================== |
188 | 224 |
ADDITIONAL NOTES |
189 | 225 |
=============================================================================== |
190 |
Date iCal only supports outputting iCal calendars through Views.
|
|
226 |
Date iCal only supports exporting iCal calendars by using Views.
|
|
191 | 227 |
To put an "Add to calendar" button on individual event nodes, try the |
192 | 228 |
Add to Cal module (http://drupal.org/project/addtocal), or follow the |
193 | 229 |
instructions created by the estimable nmc at: |
Also available in: Unified diff
Weekly update of contrib modules