Project

General

Profile

Revision 55670b15

Added by Assos Assos over 10 years ago

Weekly update of contrib modules

View differences:

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