Feeds

The RSS Aggregator module displays external feed content on a Magnolia page (feed aggregation) and generates feeds from Magnolia content (feed syndication).

Planet feeds enhance standard aggregation feeds by collecting additional data and generating feed statics. 

Creating an aggregate feed

A feed aggregator retrieves external feeds and displays the content on a Magnolia page. 

Planet feeds have all the features of standard feeds but can generate additional data and statistics that is displayed in planet components. See Feed components and Generating planet data for more.

In this example we collect three individual RSS feeds into one aggregate feed:

• Radar Online: http://radaronline.com/feed/
• Defamer: http://defamer.gawker.com/rss
• Perez Hilton: http://i.perezhilton.com/?feed=rss2

These have a common topic – celebrity gossip – so they are good candidates for aggregation. A reader interested in one feed is likely to be interested in the others too.

To create a RSS aggregator, in the Feeds app:

1. Add a new feed.
   
   • Name: CelebrityGossip. This is the internal name of the aggregator.
   • Title: Feed title.
   • Short description: Feed description.
   • Check Planet Feed to mark the feed as a planet feed. 
2. Add the feed URLs from above.
   
   • Title: Leave blank to get the title from the external feed title
   • URL: Feed URL.
     Image: Select an image from the DAM. 60x60 px works best. The image is displayed in the Planet Feeds component. Hackergotchi images are supported.
3. Add filters to refine content.
   1. Condition: Select an AND, OR or NOT condition to include or exclude content.
   2. Property: Select from a pre-defined list of options, Author, Category, Description or Title, commonly found in feeds.
   3. Regex: Type a regex pattern to meet the condition and property in the first two boxes.

Importing feed data

To import data:

• All feeds: Click Import all feeds now.
• A single feed: Click Import feed now.

See also: Scheduling automated feed imports.

Feed components

The module includes components that display external feeds and generate feeds from internal content. 

The feed components are configured in /modules/rssaggregator/templates/components.

combinedFeedsParagraph	Combines all feeds in a channel and displays them sequentially. Editors can set the number, sort order and character limit of the entries. Use with standard or planet feeds.
feedListParagraph	Displays a defined number of entries for each feed in the channel. The external feed title is used if no internal title is set. Editors can set the number, sort order and character limit of the entries. Use with standard or planet feeds.
planetFeeds	Displays the entries of all feeds in a channel with the latest appearing first. Uses the HTML of the source entry. This means that images and links are preserved and displayed. Allows pagination. Use with planet feeds only.
feedStatistics	Uses planet statistics data to display a list of authors with feed subscription icons and links to the external website. Author list is ordered by post frequency with top contributors appearing first. Editors can set a title and subtitle, define the number of authors to include, and whether links and the post count should be included. Use with planet feeds only.
feedSyndication	Displays Atom and RSS subscription icons and links that allow users to subscribe to the feed on your site. Editors can add a title and select a planet feed. Use with planet feeds only.

Creating a custom component

The model class and template script are the important properties that determine content in the different components. All RSS model classes extend  that provides the business logic to retrieve a defined feed and it's data from the rss workspace and supports:

• Entry sorting by title or publication data.

• Ascending and descending entry sorting.

• Maximum results property. Default is 20 .

• Search capabilities

Any custom model class should extend AbstractFeedModel.

Adding components to templates

You can add the feed components to any template. 

Example: Template definition with all feed components in main area.

templateScript: /my-module/templates/pages/my-script.ftl
renderType: freemarker
visible: true
title: My template
areas:
  main:
    availableComponents:
      combinedFeeds:
        id: rssaggregator:components/combinedFeedsParagraph
      feedList:
        id: rssaggregator:components/feedListParagraph
      planetFeeds:
        id: rssaggregator:components/planetFeeds
      feedStatistics:
        id: rssaggregator:components/feedStatistics
      feedSyndication:
        id: rssaggregator:components/feedSyndication

Scheduling automated feed imports

Importing feed data manually is not a long-term solution. You should configure an automated import schedule. Choose the update frequency depending on how often feeds have new content. For example, if a blog gets one post a day then importing once a day at 6 a.m. is enough.

Setting automated imports for all feeds

You can schedule automated imports for all feeds in the Configuration app. The global settings can be overridden for single feeds.

1. Periodic import: 
   1. Disabled: Automated imports are disabled by default. You can switch off them off at any time.
   2. Import every: Quick option to set imports for a specified number of minutes, hours or days.
   3. Use cron time/date defintion: Define a Quartz Cron Pattern to create a suitable import schedule. For example, the pattern 0 0 6 * * * imports data daily at 6 a.m. See Cron Maker for help.
2. Fetcher: Substitute the default feed fetcher class if necessary. See Properties table below for options.

The input in the app is stored in the module configuration in /modules/rssaggregator/config/.

Properties:

Setting automated imports for single feeds

You can configure automated import settings for each feed in the Import Settings tab of the edit dialog. These setting override the global settings. 

1. Periodic import: 
   1. Select This feed has different import settings to override the global settings.
   2. Disabled: Stops any scheduled automated imports for the individual feed and the global settings take over.
   3. Import every: Quick option to set imports for a specified number of minutes, hours or days.
   4. Use cron time/date defintion: Define a Quartz Cron Pattern to create a suitable import schedule. For example, the pattern 0 0 6 * * * imports data daily at 6 a.m. See Cron Maker for help.
2. Fetcher: Substitute the default feed fetcher class if necessary. See Properties table above for options.

Feed data storage

Feed data is stored in the rss workspace. 

Example: CelebrityGossip feed in the JCR Browser app.

Structure:

Generating planet data

Planet commands

The module includes two custom commands to generate planet data.

The commands are configured in /modules/rssaggregator/commands/planet/.

Scheduling planet updates

Use the Scheduler module to execute the planet commands to generate planet data and schedule regular updates.

 Two jobs are preconfigured in /modules/scheduler/config/jobs:

Properties:

Planet data storage

Planet data is used in planet components. The data is stored in the planetData folder in the rss workspace. View the data in your custom JCR.  

Example: CelebrityGossip feed after marking it as a planet feed, re-importing the data, and running the generatePlanetData job. 

Structure:

Planet statistics storage

Planet statistics are generated from planet data and stored in the statistics folder in the rss workspace. View the data in your custom JCR.

Example: CelebrityGossip feed after running the generatePlanetStatistics job. 

Structure:

Configuring how long to keep planet data

Planet data is generated and stored for the last 3 months by default. You can configure the time period for which the data is retained in /modules/rssaggregator/config/planetOptions.

Properties:

Feed generators

Feed generators generate RSS feeds from Magnolia content and imported content stored in the rss workspace.

Four feed generators are registered in /modules/rssaggregator/config/feedGenerators.

Properties:

Feed syndication servlet

The feed syndication servlet writes an XML feed to the response.

The servlet is registered in /server/filters/servlets/FeedSyndicationServlet. 

Properties:

FeedSyndicationServlet	required Feed syndication servlet node.
servletClass	required writes an XML feed to the response. Based on the request parameters, the feedGenerators configuration is resolved and used to generate the XML feed. The content of the feed is written to the response with the appropriate character encoding.

Virtual URI mapping

Syndication components use virtual URI mappings to redirect generated feeds. The mappings use regular expressions and are called by the feed generator classes to render appropriate content in the XML feed. 

Mappings are configured in /modules/rssaggregator/virtualURIMappings.

Properties:

Security

Public users

The anonymous role does not have permissions to the rss workspace on the author or public instance. Public users cannot see the feed content by default. 

The RSS Aggregator module installs the rss-aggregator-base role that provides read permissions to the rss workspace.

To provide public access to feed content, assign the rss-aggregator-base role to the anonymous systems user on the public instance.

App access

By default only superuser can access the Feeds app and work with feeds because the superuser role includes read/write permissions to the rss and config workspaces.

Here's how to grant permissions for various feed tasks:.

• App launcher access: The Feeds app is in the Setup group and editors typically cannot access this group. Move the app to the Edit group to grant access in the app launcher. See App launcher layout for more. This allows the user to open the app but not view the content.
• Read only access: Assign the rss-aggregator-base role to give read only access to feed content. This allows the user to view the list of feeds in the app, select feeds in components and view feed content on pages. 
• Read/write access: Create a new role granting read/write access to the rss workspace and assign it to the user. This allows the user to create new feeds in the Feeds app, but they cannot access the Configuration subapp.
• Configuration app access: Create a new role granting read/write access in the config workspace to /modules/rssaggregator to allow the user to schedule automated feed imports in the Configuration subapp.