FeedWordPress ============= * Author: [Charles Johnson](http://www.radgeek.com/contact) * Version: 0.91 * Project URI: * License: GPL. See License below for copyright jots and tittles. Introduction ------------ FeedWordPress is an Atom/RSS aggregator for WordPress. It syndicates content from newsfeeds that you select into your WordPress blog; if you syndicate several newsfeeds then you can WordPress's posts database and templating engine as the back-end of an aggregation ("planet") website. I originally developed it because I needed a more flexible replacement for [Planet][] to use at [Feminist Blogs][]. [Planet]: http://www.planetplanet.org/ "Planet Planet" [Feminist Blogs]: http://www.feministblogs.org/ FeedWordPress is designed with flexibility, ease of use, and ease of configuration in mind. You'll need a working installation of [WordPress 1.5][] and FTP or SFTP access to your web host. The ability to create cron jobs on your web host would be very helpful but it's not absolutely necessary. You *don't* need to tweak any plain-text configuration files and you *don't* need shell access to your web host to make it work. (Although, I should point out, web hosts that *don't* offer shell access are *bad web hosts*.) [WordPress 1.5]: http://wordpress.org/development/2005/02/strayhorn/ Installation & Requirements --------------------------- You'll need a website with WordPress 1.5 installed and configured and FTP or SFTP access to your web space. You'll probably also want to have either (1) the ability to create cron jobs on your web host, or (2) a computer of your own that has always-on Internet access. 1. Install `feedwordpress.php` in your WordPress `plugins` directory and `update.php` in your WordPress `wp-content` directory. 2. (Optional) Upgrade the copy of MagpieRSS packaged with WordPress by installing the new `rss-functions.php` (archived in `OPTIONAL/wp-includes`) into your WordPress `wp-includes` directory. 3. Log in to the WordPress Dashboard and activate the FeedWordPress plugin. Go to Options --> Syndication to set up initial settings for the syndication link category ("Contributors") by default and the RPC secret word (blank by default, but you should probably set it to something.) 4. Set up links for syndication from the WordPress Dashboard using Links --> Syndicated or Links --> Import. 5. FeedWordPress is now *ready* to feed syndicated content into WordPress. In order for it to actually receive that content, either (1) have your contributors add WordPress's XML-RPC URI to their blog's list of URIs to ping when they update posts, (2) set up a cron job to check in on all the feeds on a regular basis, or (3) both. If you do (2), you can either set up a job to run `php update-feeds.php` on your web host, or set one up on any computer with always-on Internet access to request `update-feeds.php` over the web. If your copy of WordPress is installed at , and you set the secret word for XML-RPC pings to "foo", then your XML-RPC URI will be , and the URI to request for `update-feeds.php` to update all feeds will be For detailed installation instructions, point your web browser to . Feed Settings ------------- Once you have your links configured and regular feed updates scheduled, you can mostly leave FeedWordPress to run on its own. If you need to add, remove, or change information for any contributors, you can do so from the WordPress Dashboard under Links --> Syndicated. If you want to distribute the labor of adding, updating, and managing feeds, you can use the WordPress login and access privileges system. Users with an access level of 5 or greater can add or modify syndicated links, and change syndication options. All the information for a syndicated feed is managed through the WordPress Links database. Feeds in the category to be syndicated (by default, "Contributors") use several fields of the standard WordPress Link record: - The Link URI is used to store a URI to the front page (*not* the feed!) of the syndicated website. - The Link Name is used to store the title of the syndicated website. - The Short Description is used to store the tagline of the syndicated website. - The RSS URI is used to store the URI for the feed to be syndicated. - The Link Notes are used to store a collection of manually-encoded and automatically-generated settings that apply to this feed. The format of settings in Link Notes is: key1: value1 key2: value2 key3: value3 feed/key1: value1 feed/key2: value2 And so on. Values that are prefixed by 'feed/' are automatically generated from feed data every time the feed syndicated by this link is checked for updates. Values without the prefix are set manually by the user. Most settings in the Link Notes have no effect on FeedWordPress, but can be accessed from templates using the ``get_feed_meta()`` template function in a post context. For example, many aggregator sites use a "face" image for each feed to visually distinguish posts from different feeds. To implement a face feature, you could add a line like this to each feed's Link Notes section: face: http://www.zyx.com/mugs/ugly The URI should be changed out for each feed to point to the appropriate image, of course. Then, to use the setting from within a template: // In a post context 0): ?> ... which will display the image, if any, whose URI is set in the "face" setting for the feed that post comes from. If there is no "face" setting for a particular feed, ``get_feed_meta()`` will return an empty string and no image will be displayed. Not all feed settings are only for templates. Some affect how FeedWordPress processes posts from that feed. Currently, the special settings are: - `cats:` a colon-separated list of default categories for any post coming from this feed. So, for example, a this line in its Notes section: cats: computers:web ... will make FeedWordPress place any posts syndicated from that feed in the "computers" and "web" categories (*in addition to*, not *instead of* any categories that are applied to the post in the feed) - `hardcode name: (yes|no)` A yes/no setting. By default, FeedWordPress updates the value of the Link Name field automatically to reflect the title that is reported by a syndicated feed. (So, for example, if one of your contributors changes the title of her weblog, the change will be reflected on your Contributors list after the next update.) To manually set the Link Name and prevent your new name from being overridden by FeedWordPress (so as to, for example, use an abbreviated form of the site's title for reasons of space), change the Link Name to a title of your choosing and then add a line like this to the Link Notes section: hardcode name: yes If `hardcode name` is absent, or set to a value other than `yes`, FeedWordPress will take that as a 'no' and follow the default behavior. - `hardcode description: (yes|no)` A yes/no setting. By default, FeedWordPress updates the value of the Link Description field automatically to reflect the tagline or description that is reported by a syndicated feed. To manually set the Link Description and prevent your new description from being overridden by FeedWordPress (so as to, for example, use an abbreviated form of the site's tagline for reasons of space), change the Link Description to a title of your choosing and then add a line like this to the Link Notes section: hardcode description: yes If `hardcode description` is absent, or set to a value other than `yes`, FeedWordPress will take that as a 'no' and follow the default behavior. - `hardcode categories: (yes|no)` A yes/no setting. FeedWordPress places each syndicated post in a set of categories within WordPress. It gets that list from two sources: 1. Categories that you set explicitly for each feed (see the `cats` setting above) 2. Categories that the original author placed the post in on her blog If any of the categories on the list do not exist, they are created automatically. If you want the posts from a particular feed to be placed *only* in the categories that you set manually (see the `cats` setting above), and not in the categories that they are in on the Contributor's blog, then add a line like this to the Link Notes section: hardcode categories: yes If `hardcode categories` is absent, or set to a value other than `yes`, FeedWordPress will take that as a 'no' and follow the default behavior. - `post status:` sets the default post status for posts from this feed This can be 'publish', 'draft', or 'private'. By default, it is set to 'publish' (syndicated posts go online immediately). - `comment status:` sets the default status for comments on posts syndicated from this feed. By default, all comments on syndicated posts are closed, but you can set it to 'open', 'closed', or 'registered_only' for particular feeds. - `ping status:` sets the default status for receiving TrackBack and PingBack pings on posts syndicated from this feed. By default, syndicated posts are closed to pings, but you can set this to 'open' or 'closed' for particular feeds. Template API ------------ When activated, FeedWordPress makes the following functions available for use by themes/templates: * ``is_syndicated()``: in a post context, returns ``TRUE`` if the post was syndicated from another website, or ``FALSE`` if it was originally posted here * ``get_syndication_permalink()``: in a post context, returns the URI of the permalink for this post *on the website it was syndicated from* * ``the_syndication_permalink()``: in a post context, outputs the value returned by ``get_syndication_permalink()`` * ``get_syndication_source_link()``: in a post context, returns the URI of the front page (*not* the feed) of the website this post was syndicated from * ``the_syndication_source_link()``: in a post context, outputs the URI returned by ``get_syndication_source_link()`` * ``get_syndication_source()``: in a post context, returns the human-readable title of the website that a syndicated post was syndicated from * ``the_syndication_source()``: in a post context, outputs the value returned by ``get_syndication_source()`` * ``get_syndication_feed():`` in a post context, returns the URI of the feed (*not* the front page) that this post was syndicated from * ``the_syndication_feed()``: in a post context, outputs the value returned by ``get_syndication_feed()`` * ``get_feed_meta($key)``: in a post context, returns the value, if any, of the feed setting ``$key`` for the feed that this post was syndicated from By default, FeedWordPress also places a filter on the standard functions ``get_permalink()`` and ``the_permalink()`` that substitutes the URI returned by ``get_syndication_permalink()`` for the URI generated by WordPress. This means that by default the permalinks listed on your website and in your newsfeed will link to the location of the posts on the source website, *not* to their location on your website. You can switch this behavior on or off at Options --> Syndication in the WordPress Dashboard. ### Plugin API ### FeedWordPress creates five hooks through the WordPress plugin architecture that you can plug in to using PHP WordPress plugins, to supplement ordinary FeedWordPress behavior, or to filter posts according to criteria that you set. The hooks are the action ``feedwordpress_update``, the action ``feedwordpress_check_feed``, the action ``feedwordpress_update_complete``, the filter ``syndicated_item``, the filter ``syndicated_post``, the action ``post_syndicated_item``, and the action ``update_syndicated_item``. For more information, see . License ------- The FeedWordPress plugin is copyright (c) 2005 by Charles Johnson. It uses code derived or translated from: - [wp-rss-aggregate.php][] by [Kellan Elliot-McCrea](kellan@protest.net) - [HTTP Navigator 2][] by [Keyvan Minoukadeh](keyvan@k1m.com) - [Ultra-Liberal Feed Finder][] by [Mark Pilgrim](mark@diveintomark.org) according to the terms of the [GNU General Public License][]. This program is free software; you can redistribute it and/or modify it under the terms of the [GNU General Public License][] as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. [wp-rss-aggregate.php]: http://laughingmeme.org/archives/002203.html [HTTP Navigator 2]: http://www.keyvan.net/2004/11/16/http-navigator/ [Ultra-Liberal Feed Finder]: http://diveintomark.org/projects/feed_finder/ [GNU General Public License]: http://www.gnu.org/copyleft/gpl.html