# Feeds

Questions or comments?

## Purpose

The purpose of this feature is to provides a widget for aggregating and displaying the entries from one or more Web feeds on a Web page. Supported Web feed formats are Atom, RSS, and Media RSS.

## Use when

- Promoting and sharing information from Web feeds on a Web page

## Working example

- English working examples
- French working examples

## How to implement

1. For each area that will display Web feeds, create a `section` element with `class="wb-feeds"`.

       <section class="wb-feeds"></section>

2. Inside the `section` element add a heading (`h1` - `h6`).
3. Add an unordered list (`ul`) after the heading with the `feeds-cont` class.
   - Flickr and YouTube feeds:
     1. Add the `list-inline` class to the unordered list.
     2. Add `<div class="clearfix"></div>` after the unordered list.
4. For every Web feed source to display, add a list element containing a link to the feed.
   - Regular feeds:

         <li>
         	<a href="http://canada.ca/sample.atom">Sample Atom Feed</a>
         </li>

   - Flickr feeds:
     1. The link `href` attribute needs to contain the URL of the Flickr account's photostream.
     2. Add a `data-ajax` attribute to the link containing the URL of the Flickr account JSON feed.

         <li>
         	<a href="https://www.flickr.com/photos/environmentcan" rel="external" data-ajax="https://api.flickr.com/services/feeds/photos_public.gne?id=47711201@N05&amp;format=json">Environment Canada Flickr</a>
         </li>

   - YouTube feeds:
     1. The link `href` attribute needs to contain the URL of the YouTube account.
     2. Add a `data-ajax` attribute to the link with the URL of the YouTube account JSON feed.

         <li>
         	<a href="https://www.youtube.com/user/ParksCanadaAgency" rel="external" data-ajax="https://gdata.youtube.com/feeds/api/users/UCzJRhTw3KVtDlcdNz33eDMQ/uploads?v=2&amp;alt=json">Parks Canada Youtube</a>
         </li>

5. Optional: Group multiple types of feeds into a tabbed interface. The benefit of this approach is it will only load the feeds that are currently visible (significantly improves performance when there are lots of feeds).
   1. Create a `div` element with `class="wb-tabs"`.
   2. Add a `div` element with `class="tabpanels"` within the previous `div` element.
   3. For each group of feeds (group feeds by type), add a `details` element. Add `open="open"` to the group of feeds that should be displayed by default.
   4. Add a `summary` element at the start of each `details` element with the name of the group of feeds (e.g., `<summary>Pinterest</summary>`).
   5. Add the areas to display Web feeds after each `summary` element as described in steps 1 to 4, except add the `wb-inv` class to the heading for each area.

       <section>
       	<h3>Tabbed Social Feeds</h3>
       	<div class="wb-tabs col-md-5 wb-eqht">
       		<div class="tabpanels">
       		<details id="details-pinterest" open="open">
       			<summary>Pinterest</summary>
       				<section class="wb-feeds limit-5">
       					<h4 class="wb-inv">Pinterestk</h4>
       					<ul class="feeds-cont media-list">
       						...
       					</ul>
       					<div class="clearfix"></div>
       				</section>
       			</details>

       			<details id="details-flickr">
       				<summary>Flickr</summary>
       				<section class="wb-feeds limit-10">
       					<h4 class="wb-inv">Flickr</h4>
       					<ul class="feeds-cont list-inline">
       						...
       					</ul>
       					<div class="clearfix"></div>
       				</section>
       			</details>

       			<details id="details-youtube">
       				<summary>YouTube</summary>
       				<section class="wb-feeds limit-10">
       					<h4 class="wb-inv">YouTube</h4>
       					<ul class="feeds-cont list-inline">
       						...
       					</ul>
       					<div class="clearfix"></div>
       				</section>
       			</details>
       		</div>
       	</div>
       	<div class="clearfix"></div>
       </section>

### Example code

#### Regular feeds

    <section class="wb-feeds limit-5">
    	<h3>Road News Releases and Safety Recalls</h3>
    	<ul class="feeds-cont">
    		<li>
    			<a href="http://www.tc.gc.ca/mediaroom/rss/road.xml" rel="external">Road News Releases (All)</a>
    		</li>
    		<li>
    			<a href="http://wwwapps.tc.gc.ca/Saf-Sec-Sur/7/VRDB-BDRV/search-recherche/rss.aspx?lang=eng" rel="external">Road Safety Recalls</a>
    		</li>
    	</ul>
    </section>

#### Flickr feeds

    <section class="wb-feeds limit-15">
    	<ul class="feeds-cont list-inline">
    		<li>
    			<a href="https://www.flickr.com/photos/environmentcan" rel="external" data-ajax="https://api.flickr.com/services/feeds/photos_public.gne?id=47711201@N05&amp;format=json">Environment Canada Flickr</a>
    		</li>
    	</ul>
    	<div class="clearfix"></div>
    </section>

#### YouTube feeds

    <section class="wb-feeds limit-15">
    	<ul class="feeds-cont list-inline">
    		<li>
    			<a href="https://www.youtube.com/user/ParksCanadaAgency" rel="external" data-ajax="https://gdata.youtube.com/feeds/api/users/UCzJRhTw3KVtDlcdNz33eDMQ/uploads?v=2&amp;alt=json">Parks Canada Youtube</a>
    		</li>
    		<li>
    			<a href="https://www.youtube.com/user/fisheriescanada?feature=results_main" rel="external" data-ajax="https://gdata.youtube.com/feeds/api/users/UC5D1a5R8bbrTXEJrjmRX7gA/uploads?v=2&amp;alt=json">Department of Fisheries and Oceans’ YouTube</a>
    		</li>
    	</ul>
    	<div class="clearfix"></div>
    </section>

#### Tabbed feeds

    <section>
    	<h3>Tabbed Social Feeds</h3>
    	<div class="wb-tabs col-md-5 wb-eqht">
    		<div class="tabpanels">

    		<details id="details-flickr">
    				<summary>Flickr</summary>
    				<section class="wb-feeds limit-10">
    					<h4 class="wb-inv">Flickr</h4>
    					<ul class="feeds-cont list-inline">
    						<li>
    							<a href="https://www.flickr.com/photos/environmentcan" rel="external" data-ajax="https://api.flickr.com/services/feeds/photos_public.gne?id=47711201@N05&amp;format=json">Environment Canada Flickr</a>
    						</li>
    					</ul>
    					<div class="clearfix"></div>
    				</section>
    			</details>

    			<details id="details-youtube">
    				<summary>YouTube</summary>
    				<section class="wb-feeds limit-10">
    					<h4 class="wb-inv">YouTube</h4>
    					<ul class="feeds-cont list-inline">
    						<li>
    							<a href="https://www.youtube.com/user/ParksCanadaAgency" rel="external" data-ajax="https://gdata.youtube.com/feeds/api/users/UCzJRhTw3KVtDlcdNz33eDMQ/uploads?v=2&amp;alt=json">Parks Canada Youtube</a>
    						</li>
    						<li>
    							<a href="https://www.youtube.com/user/fisheriescanada?feature=results_main" rel="external" data-ajax="https://gdata.youtube.com/feeds/api/users/UC5D1a5R8bbrTXEJrjmRX7gA/uploads?v=2&amp;alt=json">Department of Fisheries and Oceans’ YouTube</a>
    						</li>
    					</ul>
    					<div class="clearfix"></div>
    				</section>
    			</details>
    		</div>
    	</div>
    	<div class="clearfix"></div>
    </section>

### Converting ATOM XML feed into JSON ATOM like format

Here is the skeleton structure for the feed:

    {
    	"feed": {
    		"entry": [
    			{
    				"title": "[Title of the entry]",
    				"updated": "[UTC date format]",
    				"link": "[URL]"
    			},

    			...
    		]
    	}
    }

Notes:

- Replace `...` in each entry and remove the ending comas for the least entry.
- The Feed plugin would ignore any meta information added to describe the feed. However we recommend that your feed contains self-describing information.

Alias for "Publication date" of each entry:

- `publishedDate`
- `published`
- `pubDate`
- `updated`

Alias for "Link" of each entry:

- `link`
- `href`

## Configuration options

These are the configuration options that can be used by implementers or developers.

Option | Description | How to configure | Values
--- | --- | --- | ---
`limit-x` | Controls the amount of items the Web feeds widget will display. | Add the `limit-x` class after the `wb-feeds` class and replace `x` with an integer. | default (not specified) Display all the entries of the feeds `limit-4`: Limits display to four items.
`data-cors="true"` | Allows cross-site requests to fetch ATOM feed without using the Yahoo API services | Add the attribute `data-cors="true"` | undefined (default) Use the Yahoo API service `true` Retreive directly the ATOM feed

## Events

These are the public events that can be used by implementers or developers.

Event | Trigger | What it does
--- | --- | ---
`wb-init.wb-feeds` | Triggered manually (e.g., `$( ".wb-feeds" ).trigger( "wb-init.wb-feeds" );`). | Used to manually initialize the Feeds widget. Note: The Feeds widget will be initialized automatically unless it is added after the page has already loaded.
`wb-ready.wb-feeds` (v4.0.5+) | Triggered automatically after the Feeds plugin has initialized. | Used to identify where the Feeds plugin has finished initializing (target of the event).
    $( document ).on( "wb-ready.wb-feeds", ".wb-feeds", function( event ) {
    });
    $( ".wb-feeds" ).on( "wb-ready.wb-feeds", function( event ) {
    });
`wb-feed-ready.wb-feeds` (v4.0.5+) | Triggered automatically after a feed has become visible. | Used to identify which feed has become visible (target of the event).
    $( document ).on( "wb-feed-ready.wb-feeds", ".wb-feeds .feeds-cont", function( event ) {
    });
    $( ".wb-feeds .feeds-cont" ).on( "wb-feed-ready.wb-feeds", function( event ) {
    });
`wb-ready.wb` (v4.0.5+) | Triggered automatically when WET has finished loading and executing. | Used to identify when all WET plugins and polyfills have finished loading and executing.
    $( document ).on( "wb-ready.wb", function( event ) {
    });

## Source code

Feeds widget source code on GitHub

Date modified:
  2014-08-04