Customize calendar feeds
When you publish your calendar, Trumba Connect generates RSS, Atom (XML), and Icalendar (ICS) feeds that visitors can access from your calendar. Visitors can subscribe to your RSS or Atom feed to get notified of your calendar updates as soon as you make them. They can download the ICS feed to a file that they can import into their own calendar programs.
By default, a calendar's feeds show five weeks of event information starting from the current week. This topic describes how to edit the date range and number of events that are sent through a feed, or to add xCal data to RSS feeds. You can make these changes in:
- Feeds that visitors get when they click the appropriate button on your calendar.
- Feeds that you can provide to visitors through hyperlinks on your web pages.
Note The information in this topic assumes that you have published your calendar or are familiar with the publishing process. Learn more about publishing calendars.
Topic links
Customize the default feeds sent from your Trumba calendar spud
You can customize the feed that is sent when a visitor clicks the RSS button, or, on the Subscribe page, subscribes to the Atom (XML) feed, or downloads the ICS file.
To customize default feeds
- In your Trumba editing environment, display your published calendar and click Publish to open the Publishing Control Panel.
- Click the Feeds tab. In the Available Custom Feeds section, for the feed you want to customize, click Edit Settings & Styles.
- On the Edit Settings page, select the Feed Options you want:
- Start date and End date These settings are not as straightforward as they may seem and it's worthwhile to give some thought to the time period you want your feeds to cover.
For example, suppose you publish the annual calendar for the National Football League two months before the season actually begins. Avid fans will immediately begin subscribing to the feed. If the feed you provide covers events that take place starting in the current week and ending five weeks later, the feed will be empty and fans will be frustrated and confused. By changing the default start and end dates, you can provide fans with the season schedule information they need.
Is there a way that I can set specific start and end dates that aren't available in the Start date and End date drop-down lists?
- Maximum Number of Events Set the maximum number of events to include within the start and end date range.
- Ongoing events Select to include multi-day and ongoing events that begin before and end after the start date.
- (RSS and Atom feeds only) Include event template field, custom event fields, and web links Select Yes to include these fields in the body of each event.
- Include HTML If you used HTML formatting in the Notes or other multi-line custom event fields, selecting Yes preserves the HTML formatting. Events will display with formatting in feed readers that support HTML tags.
If you feed event data to Twitter or other services that show HTML tags rather than the formatted result, select No.
For the iCal feed, it's usually best to select No. Many calendar programs, including Microsoft Office Outlook, display the HTML tags rather than the formatted result.
- (RSS feeds only) Include xCal data If you're using the RSS feed for reverse publishing, you might want to select Yes. Learn more about allowing access to your RSS data via XSLT.
- (RSS and Atom feeds only) Publish Date Select the source for the feed publish date or hide the date altogether.
- (RSS and Atom feeds only) Date/Time Options, Image Settings, Inline Images, and Custom Field Icons These options affect the appearance and content of the events in your feed. Take the time to select options that make your feeds look the way you want.
- Click OK.
- Back in the Custom Feed Settings list, at the bottom left of the feed description, click Preview.
How and whether or not a feed preview displays depends upon:
- The operating system version you have on your computer.
- The browser you're using, and the browser version.
- Whether or not you have added an RSS reader extension, if the browser requires one.
- For iCal feeds, whether or not you have a calendar program, such as Microsoft® Office Outlook®, installed that opens .ics files.
- Which feed type you're trying to preview. Most browsers can't preview Atom feeds.
Tip You can also preview a feed by copying the feed URL and using the URL to subscribe to the feed from within the feed reader you typically use.
Build URLs to provide custom feeds through links on your web page
If you want to provide links on your webpages for a choice of different feeds, you can build your own URLs in addition to customizing the default feed. For example, if you publish a calendar of events for a group of nightclubs, you might want provide viewers with the current week's all-ages vs. 21 and older shows, or the current week's shows at each club.
Note Although this topic addresses calendar publishers, anyone can use this information to create a custom URL to retrieve data from a Trumba Connect published calendar.
To customize the URL for your calendar feeds
- First find the base URL for the feed you want to customize.
- Specify what information you want to retrieve from the calendar by appending query strings to the default URL, using one or a combination of the supported parameters.
To add the query strings, at the end of the default URL for the feed, add a question mark (?) to begin the first parameter, and use an ampersand (&) to combine parameters. For example:
http://www.trumba.com/calendars/[calendarwebname].rss?
startdate=20080205&weeks=1&previousweeks=0
In your calendar settings, if you set Week display starts to Sunday, this will display events that occur between Sun. and Sat. of the week that includes Feb. 5, 2008. In other words, events that occur on Feb. 3–9.
Supported parameters for building query strings
The following table lists the parameters you can use to retrieve specific information from an RSS, Atom, or ICS feed published from Trumba Connect.
| Parameter | How to use it |
|---|
| startdate | Specify a start date. If not specified, uses the current date. Date format is yyyymmdd, for example, 20080205 for 5 Feb. 2008.
Note Formerly the date parameter was used to specify the start date. The date parameter is still supported for the time being, but for new feeds, please use startdate instead. |
| enddate | Specify an end date using the same date format as for startdate above. If not specified, all future events are included in the feed. |
| months | Number of calendar months to retrieve. Use months=0 to retrieve one day only. If excluded, the default setting is six months. |
| weeks | Number of calendar weeks to retrieve. |
| days | Number of days to retrieve (frequently used with the startdate parameter). |
| previousweeks | Number of weeks previous to the specified date to retrieve. If previousweeks is excluded, the feed will include two weeks' worth of events previous to the specified date (or the current date if date is not specified). |
| mixin, mixout | Specify which calendars' events to mix into the feed. Values of these parameters are set by including the calendar id number of each calendar to mix in or out, separated by URL-encoded commas.
You use the mixin and mixout parameters for feeds as you do for URLs that display spuds. Learn more… |
| html |
If you added HTML formatting to the event Notes and other multi-line text custom fields, this parameter controls whether or not to include that formatting in the event data. Values are 1 for Yes and 0 for No.
You can override the default Yes setting by adding html=0 to a feed URL. Use this approach if you feed events to Twitter and other services that do not support HTML tags.
|
| customnotes |
Most calendar programs, including Microsoft Office Outlook, that read the Trumba iCal feed do not recognize the feed's custom field data. You can use this parameter to include the custom field data at the top of the Notes field.
Values are 1 (Yes, include fields in Notes) and 0 (No, do not include fields in Notes). You can override the default No setting by adding customnotes=1 to a feed URL.
|
| xcal | Add xcal=1 to an RSS feed to include xCal-namespace data. Supported only by RSS. |
Tip Calendar feeds also support some URL parameters that are available for displaying calendar spuds. For example, you can use the search parameter to display a feed that contains events that match the specificed search string. See the list of spud URL parameters.
How time periods are determined
Time periods are based on calendar weeks and months. For example, if you specify a date and a number of months, the information returned will start from the first of the month specified in the date. Likewise, information returned for weeks is determined by the week start day in the calendar settings. Usually weeks are set to start on Sunday or Monday.
Allow access to your calendar RSS data via XSLT
Use the xCal parameter to enable access to the calendar's RSS data via XSLT. If xcal=1, the RSS feed will include the following xCal tags for basic data that applies to the calendar or to each event.
| Tag | Applies to |
|---|
| xCal:prodid | calendar |
| xCal:version | calendar |
| xCal:method | calendar |
| xCal:summary | event |
| xCal:location | event |
| xCal:dtstart | event |
| xCal:duration | event |
| xCal:x-microsoft-cdo-alldayevent | event |
| xCal:description | event |
| xCal:uid | event |
For example, to the following default event information:
<item>
<title>Massenet's Manon</title>
<description><b>Massenet's Manon</b>
<br/>Met Opera Broadcast<br/>Saturday, April 08, 2006
<br/>10:30 AM - 2:15 PM<br/><br/>
Fleming, Giordano, Chaignaud, Robbins; López-Cobos</description>
<link>http://www.trumba.com/calendars/metbroadcasts?eventid=23491156</link>
<guid isPermaLink="false">http://www.trumba.com/guid/CwAvhUERZlLH2VHRUqeYYJko-zmv16LRHD4G2FH4XcQxwQ!!</guid>
<category>2006/04/08 (Sat)</category>
<pubDate>07 Jan 2006 00:29:17 GMT</pubDate>
</item>
|
The following additional information appears:
<xCal:summary>Massenet's Manon</xCal:summary>
<xCal:location>Met Opera Broadcast</xCal:location>
<xCal:dtstart>2006-04-08T10:30:00Z</xCal:dtstart>
<xCal:dtend>2006-04-08T14:15:00Z</xCal:dtend>
<x-microsoft:cdo-alldayevent>False</x-microsoft:cdo-alldayevent>
<xCal:description>Fleming, Giordano, Chaignaud, Robbins; López-Cobos</xCal:description>
<xCal:uid>
X-TRUMBA-CwAvhUERZlLH2VHRUqeYYJko-zmv16LRHD4G2FH4XcQxwQ!!
</xCal:uid>
|
And the following calendar tags appear a the top of the feed.
<xCal:prodid>
-//Trumba Corporation//Trumba Connect Services 0.11.1402//EN
</xCal:prodid>
<xCal:version>2.0</xCal:version>
<xCal:method>PUBLISH</xCal:method>
<xCal:calscale>GREGORIAN</xCal:calscale>
|
Get the base URL for the feed you want to customize
The default base URL for a feed is always your calendar's address on the Trumba Connect hosted server, with the appropriate extension appended to it.
- For RSS, append .rss to the default URL.
www.trumba.com/calendars/yourcalendarwebname.rss
- For Atom, append .xml to the URL.
- For Icalendar (Ical or ICS), append .ics to the URL.
Trumba Connect makes your published calendar feeds available in two locations:
- www.trumba.com/calendars/yourcalendarwebname.extension
- www.trumba.com/service/yourcalendarwebname.extension
The information available in a feed depends on which URL you use.
- www.trumba.com/calendars/…
- The default URL when you request a feed for a published calendar.
- Feeds include mixed-in events.
- www.trumba.com/service/…
- Used for import and export.
- Feeds do not contain events from mixed-in calendars.
- None of the URL parameters apply to these URLs.
Accessing password-protected calendars' RSS feeds
You can publish calendars with password protection.
- When you are signed in to your Trumba account, you can access the RSS feed for an unpublished calendars by assigning a web name to your calendar (in the Calendar Settings page) and then using the www.trumba.com/service/… URL. Tell me more about web names.
- When you're not signed in, the RSS reader you use to open or subscribe to a password-protected calendar's RSS feed must allow you to sign in to a password-protected address.
