|
| 1 | +## The Feed Package |
| 2 | + |
| 3 | +### Introduction |
| 4 | + |
| 5 | +The *Feed* package is designed to provide a straightforward way to manage interactions with RSS and atom feeds. It supports feed namespacing. |
| 6 | + |
| 7 | +### Accessing a feed |
| 8 | + |
| 9 | +The feed package accesses an individual feed using a factory followed by the getFeed() method which takes the feed's uri as its only argument. Calls to the getFeed() method should be enclosed in a try block since they will throw runtime exceptions if either connecting with or retrieving the feed fails. |
| 10 | + |
| 11 | + |
| 12 | +```php |
| 13 | +try |
| 14 | +{ |
| 15 | + $feed = new JFeedFactory; |
| 16 | + $feedDoc = $feed->getFeed(http://feeds.joomla.org/JoomlaAnnouncements); |
| 17 | +} |
| 18 | +catch (RunTimeException $e) |
| 19 | +{ |
| 20 | + $msg = JText::_('ERROR_FEED_NOT_RETRIEVED'); |
| 21 | +} |
| 22 | +``` |
| 23 | + |
| 24 | + |
| 25 | +### The Feed Class and Child Classes |
| 26 | + |
| 27 | +The factory class provides access to the feed class, its children, and their protected properties. |
| 28 | + |
| 29 | +The main class is the feed class which includes properties describing the feed as a whole: the feed uri, title, date of most recent update, description, categories and contributors. Magic get and set methods allow access to these and other methods allow more fine grained manipulation. The same is true for the child classes. |
| 30 | + |
| 31 | +The entry class, JFeedEntry, manages data about individual entries in the feed. |
| 32 | +The person class JFeedPerson, manages data about individual persons connected with the feed, typically authors, contributors or the person responsible for the feed as a whole. |
| 33 | +The link class, JFeedLink, manages data about individual links in a feed. Among other things it is used to construct html links to entries. |
| 34 | + |
| 35 | +```php |
| 36 | + // Show the feed description |
| 37 | + echo $feedDoc->description; |
| 38 | + |
| 39 | + // Create a link to the ith item in a feed. |
| 40 | + echo '<a href="' . $feedDoc[$i]->uri . '" target="_blank">' |
| 41 | + . $feedDoc[$i]->title . '</a>'; |
| 42 | + |
| 43 | +``` |
| 44 | + |
| 45 | +JFeedParser creates an XMLReader to manage parsing feed objects. Rss and atom are supported. |
| 46 | + |
| 47 | +This example shows a simple example of how a complete feed might be rendered. Always keep in mind that not all feeds will support all elements, which means that the existence of an element should be checked for before attempting to use it. Some differences between Atom and RSS (such as use of guid) can also be incorporated by checking for their presence. |
| 48 | + |
| 49 | +You also may want to use JHtmlString::truncate or JHtmlString::truncateComplex to limit the number of characters rendered and JFilterOutput::stripImages(), JFilterOutput::stripIframes or other filtering options. |
| 50 | + |
| 51 | +```php |
| 52 | + |
| 53 | +if (isset($feedDoc->title)) |
| 54 | +{ |
| 55 | + echo str_replace(''', "'", $feedDoc->title); |
| 56 | +} |
| 57 | + |
| 58 | +if (isset($feedDoc->description)) |
| 59 | +{ |
| 60 | + echo str_replace(''', "'", $feedDoc->description); |
| 61 | +} |
| 62 | +if (isset($feedDoc->image)) |
| 63 | +{ |
| 64 | + echo '<img src="' . $feedDoc->image . '"/>'; |
| 65 | +} |
| 66 | +if (!empty($this->rssDoc[0])) |
| 67 | +{ |
| 68 | + // Set the number of entries to display |
| 69 | + $numentries = 5; |
| 70 | + for ($i = 0; $i < $numentries; $i++) |
| 71 | + { |
| 72 | + if (!empty($this->feedDoc[$i]->uri)) |
| 73 | + { |
| 74 | + echo '<a href="' . $feedDoc[$i]->uri . '" target="_blank">' |
| 75 | + . $feedDoc[$i]->title . '</a>'; |
| 76 | + } |
| 77 | + if (!empty($feedDoc[$i]->content)) |
| 78 | + { |
| 79 | + echo $feedDoc[$i]->content; |
| 80 | + } |
| 81 | + } |
| 82 | +} |
| 83 | +```php |
| 84 | + |
| 85 | + |
| 86 | +## Namespacing Support |
| 87 | +Namespacing in feeds is used to add specialized elements to a feed. Some are widely used but individual feeds may also have customized namespacing. JFeed supports dependency injection for namespacing. Currently media and itunes support is implemented. |
| 88 | + |
| 89 | +#### More Information |
| 90 | + |
| 91 | +More information on feed related topics can be found at: |
| 92 | + |
| 93 | +[Atom Specification](http://www.atomenabled.org/developers/syndication/) |
| 94 | +[RSS Specification](http://cyber.law.harvard.edu/rss/rss.html) |
| 95 | +[W3 information on name spaces](http://feed2.w3.org/docs/howto/declare_namespaces.html) |
| 96 | +[Extending RSS with Namespaces](http://www.disobey.com/detergent/2002/extendingrss2/) |
| 97 | +[iTunes Namespace Specification](http://www.apple.com/itunes/podcasts/specs.html) |
| 98 | +[Media Namespace specifications](http://video.search.yahoo.com/mrss) |
| 99 | +[XMLReader Documentation](http://php.net/manual/en/book.xmlreader.php) |
0 commit comments