# feedwordpress/0.99/README.text FeedWordPress, version 0.99. 508 lines. - Page: https://pluginprobe.com/plugins/feedwordpress/0.99/code/README.text - Raw: https://pluginprobe.com/plugins/feedwordpress/0.99/raw/README.text - Modified: 2007-11-21T23:15:10+00:00 Line numbers below start at 1. Link to a line or a range by appending a fragment to the page URL, for example `https://pluginprobe.com/plugins/feedwordpress/0.99/code/README.text#L10-L20`. ``` FeedWordPress ============= * Author: [Charles Johnson](http://radgeek.com/contact) * Version: 0.99 * Project URI: * License: GPL 2. See License below for copyright jots and tittles. Introduction ------------ FeedWordPress is an Atom/RSS aggregator for the WordPress weblog software. It syndicates content from newsfeeds that you choose into your WordPress webblog; if you syndicate several newsfeeds then you can use 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 (version [2.3][], [2.2][], [2.1][], [2.0][] or [1.5][]), and also 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*.) [2.3]: http://codex.wordpress.org/Version_2.3 [2.2]: http://codex.wordpress.org/Version_2.2 [2.1]: http://codex.wordpress.org/Version_2.1 [2.0]: http://codex.wordpress.org/Version_2.0 [1.5]: http://codex.wordpress.org/Version_1.5 Installation ------------ ### Requirements ### To use version 0.99 of FeedWordPress, you will need: 1. an installed and configured copy of WordPress 2.3.x, 2.2.x, 2.1.x, 2.0.x, or 1.5.x. (FeedWordPress currently *will not work* with older versions of WordPress, or with WordPress MU.) 2. FTP or SFTP access to your web host ### Installation ### #### Upgrades #### To *upgrade* an existing installation of FeedWordPress to version 0.99: 1. Download the FeedWordPress archive in zip or gzipped tar format and extract the files on your computer. 2. If you are upgrading from version 0.98 or earlier, then you need to create a new directory named `feedwordpress` in the `wp-content/plugins` directory of your WordPress installation, and you also need to *delete* your existing `wp-content/update-feeds.php` and `wp-content/plugins/feedwordpress.php` files. The file structure for FeedWordPress has changed and the files from your old version will not be overwritten, which could cause conflicts if you leave them in place. 3. Upload the new PHP files to `wp-content/plugins/feedwordpress`, overwriting any existing FeedWordPress files that are there. Also be sure to upgrade `wp-includes/rss.php` and `wp-includes/rss-functions.php` if you use the optional MagpieRSS upgrade, or don't use it yet but do want to syndicate Atom 1.0 feeds. 3. If you are upgrading from version 0.96 or earlier, **immediately** log in to the WordPress Dashboard, and go to Options --> Syndicated. Follow the directions to launch the database upgrade procedure. The new versions of FeedWordPress incorporate some long-needed improvements, but old meta-data needs to be updated to prevent duplicate posts and other possible maladies. If you're upgrading an existing installation, updates and FeedWordPress template functions *will not work* until you've done the upgrade. Then take a coffee break while the upgrade runs. It should, hopefully, finish within a few minutes even on relatively large databases. 4. If you are upgrading from version 0.98 or earlier, note that the old `update-feeds.php` has been eliminated in favor of a (hopefully) more humane method for automatic updating. If you used a cron job for scheduled updates, it will not work anymore, but there is another, simpler method which will. See [Setting Up Feed Updates][] below to get scheduled updates back on track. 5. Enjoy your new installation of FeedWordPress. #### New Installations #### 1. Download the FeedWordPress archive in zip or gzipped tar format and extract the files on your computer. 2. Create a new directory named `feedwordpress` in the `wp-content/plugins` directory of your WordPress installation. Use an FTP or SFTP client to upload the contents of the `wp-content/plugins/feedwordpress` directory in the FeedWordPress archive to the new directory that you just created on your web host. 3. (Optional) Upgrade the copy of MagpieRSS packaged with WordPress by installing the new `rss.php` and `rss-functions.php` (archived in `OPTIONAL/wp-includes`) into your WordPress `wp-includes` directory. Upgrading MagpieRSS is necessary if you want to take advantage of support for Atom 1.0, multiple post categories, RSS enclosures, and multiple character encodings. (Note, however, that support for transliterating between character encodings is a very complex and iffy prospect in some PHP environments, so if you intend to use a lot of feeds with alternate encodings you should make sure that your installation of PHP is up-to-date and that you keep a copy of the old MagpieRSS around to compare results.) 4. Log in to the WordPress Dashboard and activate the FeedWordPress plugin. 5. While you're at the Dashboard, once the plugin is activated, you can go to **Syndication --> Options** and set (1) the link category that FeedWordPress will syndicate links from (by default, "Contributors"), and (2) whether FeedWordPress will use automatic updates or only manual updates. 5. Go to the main **Syndication** page to set up the list of sites that you want FeedWordPress to syndicate onto your blog. (If you have the feeds you want to aggregate in a service such as Bloglines, you may prefer to export them to an OPML file and use WordPress's **Blogroll --> Import Links** to import them into the contributors category.) #### Setting Up Feed Updates #### FeedWordPress is now ready to accept posts from its syndication sources. The next thing to do is to make sure it knows *when* to go get them. **N.B.:** If you are upgrading from version 0.981 or earlier of FeedWordPress, the system for checking for new posts has been overhauled, hopefully making it more humane, and also easier to use for people who do not have access to task scheduling tools such as `cron`. You will need to re-read this section and change your set-up accordingly. FeedWordPress allows you to choose whether it will check for new posts automatically, or only when you manually request for it to check. By default, FeedWordPress opts for the **manual** option -- so that you can get your feeds set up properly before FeedWordPress begins importing new posts. If you want to use automatically scheduled updates, remember to enable them in **Syndication --> Options** after you finish setting up FeedWordPress. ##### Manual Feed Updates ##### To manually check for new posts, log in to the WordPress Dashboard and go to the main page under **Syndication**. You can use the "Update feeds now" button to check for new posts on feeds that are due for a scheduled update, or use the checkboxes and "Update Checked Feeds" button to force FeedWordPress to check one or more specific feeds for new posts. FeedWordPress will check the selected feed or feeds for new posts, and import any new content available. ##### Automatic Feed Updates ##### If you choose an automatic update schedule, then FeedWordPress will automatically check for new posts based on a schedule you determine. When automatic updates are enabled, FeedWordPress will check for new posts when (1) at least ten minutes have passed since the last update, and (2) a viewer visits your FeedWordPress-enabled blog. (If you want the interval of time to be shorter or longer, you can change the interval in the Dashboard under **Syndication --> Options**.) Note that this is not quite the same thing as precisely scheduled updating. If you get at least one viewer every ten minutes, then FeedWordPress will be regularly checking for new posts on schedule; if not, not. But for a relatively active aggregator blog this is probably close enough for government work. However, if you want to ensure regular updates, and you have access to a task-scheduling tool such as `cron`, you can use it to schedule regular checks for updates on a fixed schedule. For example, using `cron`, you can easily ensure that FeedWordPress checks for new posts regularly by adding the following line to your crontab, substituting the actual address of your WordPress installation for "http://www.zyx.com/blog/": */15 * * * * curl http://www.zyx.com/blog/ > /dev/null If you don't have direct access to `cron` or a similar scheduling tool, you can use online tools such as [WebCron](http://www.webcron.org/?lang=en) to schedule a regular fetch of your blog's front page to much the same effect. ##### Feed Updates using XML-RPC ##### FeedWordPress also allows syndicated blogs to notify you of updates using the XML-RPC "recently updated" pings (in the standard format accepted by Weblogs.com, Ping-O-Matic, Technorati, and other blogging services). Most blogging software allows users to add a URI to the list of URIs that get pinged with each new update -- see, for example, **Options --> Writing --> Update Services** in WordPress, or **Configuration --> Preferences --> Publicity / Remote Interfaces / TrackBack** in Movable Type. If you can get a contributor to add your XML-RPC URI to her list of update services to ping, then whenever she updates her blog, her blogging software will notify your FeedWordPress installation, and FeedWordPress will look up her feed to grab the new posts off of it. (If you have WordPress installed at , say, the URI for her to ping should be ). Basic Concepts -------------- FeedWordPress is written as a plugin for the WordPress weblog software. It is designed to store all the data it needs within the WordPress database and to make that data easy to manage from within the WordPress Dashboard. ### Contributors / Newsfeeds ### FeedWordPress uses the WordPress Links database to keep a list of the feeds from which it will syndicate content. WordPress allows you to place links in categories; FeedWordPress will make use of all and only the links in one category (by default, this is a category named "Contributors"; you can change the category that FeedWordPress will use using **Options --> Syndication**). From WordPress's perspective, the list of Contributors are normal links, and they can be manipulated like other links through the WordPress Dashboard. However, FeedWordPress provides a nicer interface for adding, removing, or changing information for the Contributor Links from the WordPress Dashboard, under **Links --> Syndicated**. If you want to distribute the labor of adding, updating, and managing feeds between several people, you can use the WordPress login andaccess privileges system. Any users with an access level of 5 or greater can add, delete, and modify Contributors; users with an access level of 6 or greater can change syndication options. When FeedWordPress looks for new posts, it retrieves one or all of the links from the Contributors category (depending on whether it has been told to scan for new posts on one or all of the feeds), determines which of them should be polled for updates (based on how long it has been since the last time each feed was polled for updates), and then uses an HTTP conditional GET to check for updates at the "RSS URI" for each Link that it selects. Any new posts are added to the database, and old posts that have been updated since the last poll are updated to reflect the new version. __Feed settings:__ All of the information for a syndicated feed is stored in the WordPress Links database, and can be easily edited using an interface that FeedWordPress provides under **Links --> Syndicated**. (If you're curious about the technical details of how the information is stored, you can find out more under [API: How feed information is stored][].) You can use a feed's **Edit** link under **Links --> Syndicated** to affect how FeedWordPress prcesses posts from that feed. (Most of these options can either be set for *one particular feed* using **Links --> Syndicated --> Edit**, or set as the default for *all feeds* using **Options --> Syndication**.) The **Edit** link also allows you to set **Custom Feed Settings** for use in templates, through the use of the [`get_feed_meta()`][get_feed_meta] template function in a post context (see [Template API][]). 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 custom setting for each Contributor Link, with the key of "face" and a URI such as "http://www.zyx.com/mugs/ugly" for the value. (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, add something like: // 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()`][get_feed_meta] will return an empty string and no image will be displayed. [API: How feed information is stored]: http://projects.radgeek.com/feedwordpress/api#how-feed-information-is-stored ### Syndicated Posts ### Whenever FeedWordPress updates, it scans one or more of the feeds in its Contributors list and adds any new posts that it finds to the WordPress database. Syndicated posts are displayed on your WordPress pages like any other posts: they can be listed in archives by category, author, or date; they can be found with the search box; and they are included in the newsfeed of your blog. In your WordPress templates (**Presentation --> Theme Editor**) you can access special information about syndicated posts using [functions provided by FeedWordPress][Template API], such as [`is_syndicated()`][is_syndicated], [`the_syndication_source()`][the_syndication_source], [`the_syndication_source_link()`][the_syndication_source_link], and [`get_feed_meta()`][get_feed_meta]. For example, here is the template code that I use (in a post context) to display both the author's name and the original source of the post in the templates for [Feminist Blogs][]: from '; the_syndication_source(); echo ''; endif; ?> For more information on template functions, see [Template API][]. ### Categories ### WordPress allows for posts to be placed in *categories*. Each syndicated post that FeedWordPress adds to the WordPress database is placed into a set of categories. FeedWordPress gets the list of category names to use from two sources: 1. Categories (or "tags") that the original author placed the post in on her blog 2. Categories that you set explicitly for each feed using the **Categories** checkbox under **Links --> Syndicated --> Edit**. For example, if you wanted all the posts from Alas, A Blog to be placed in the "Pacific Northwest" category and the "Cartoonists" category (*in addition to* any other categories that they were placed in on Alas, A Blog), you could do this by creating the categories, going to **Links --> Syndicated**, clicking the "Edit" link for Alas, A Blog, and checking those two categories under the checkbox captioned "Categories." Given the list of category names, FeedWordPress looks for categories in the WordPress database with the same name as either (1) the category name, or (2) one of the "aliases" listed in the category description. __Aliases:__ Different often authors use slightly different names for categories that mean the same thing (contributors to Feminist Blogs, for example, used categories including "Feminism", "feministy stuff", "Women's Issues", "Gender Issues", "Gender Equality", and so on). If you want FeedWordPress to treat one category name as a synonym for another, you can do so by creating an "alias" for the category. For example, to make FeedWordPress treat posts that are placed in the category "feministy stuff" as if they had been placed in the category "Feminism", go to **Manage --> Categories**, find the category "Feminism" and click the "Edit" link for it, and then add the following to the Description field, on a line by itself: a.k.a.: feministy stuff You can add as many aliases as you like. You can also add any other text that you like to the Description without interfering with FeedWordPress's ability to use the aliases. Each alias must be on a line by itself. __Unfamiliar categories:__ If one of the category names that a newsfeed provides is *unfamiliar* -- that is, if there is not yet any category in your WordPress database that either has that name, or uses that name as an alias -- then by default FeedWordPress will *automatically create* a new category with that name and place the current post in it. The default behavior can be changed so that unfamiliar categories will *not* be added to the database, using the **Unfamiliar categories** setting, either for *all* feeds (under **Options --> Syndication**) or for *one particular feed* (under **Links --> Syndicated**). If you choose to disable the creation of new categories, either for all feeds or for one particular feed, then you can also choose whether or not FeedWordPress should syndicate posts that do not match *any* of the categories that are currently in the database. This allows you to do some simple filtering of posts by category: if you want to your blog to syndicate only the posts in one particular category from a feed that has several categories, you could do so by creating a category by that name, adding the new feed(s), and then setting **Unfamiliar categories** under **Links --> Syndicated --> Edit** to "don't create new categories and don't syndicate posts unless they match at least one familiar category". Since only posts in categories that are in your database will be included, and only the category or categories that you wanted posts from has been added to your database, this will filter out all the posts that aren't in the category or categories that you defined ahead of time. (Similarly, you could set up FeedWordPress so that *all* the feeds are filtered by author by creating the set of users named after the authors you want to syndicate, and then setting the default behavior for *all* feeds at **Options --> Syndication**). If you need a category filter with more complex logic, you can always create a `syndicated_item` filter in PHP (see [Plugin API][]) that manipulates the `['categories']` array of a syndicated item. ### Authors ### Most newsfeeds include information about the author of the items on them. (If a feed doesn't, then FeedWordPress will create an author's name based on the title of the feed from which the item was taken.) This information is used to determine the WordPress user that the post will be attributed to. Given the name of the author, FeedWordPress looks for authors in the WordPress database with the same name as either (1) their login, (2) their display name, (3) their e-mail address (if given), or (4) one of the "aliases" listed in the user's profile. __Aliases:__ If there is an author who posts under more than one name (for example, one of our contributors at [Feminist Blogs][] posts on several different blogs, sometimes using her full name and sometimes using only her first name), then you can ensure that FeedWordPress will attribute those posts to the same author by creating "aliases" for the author. For example, to make FeedWordPress treat posts by "Joseph Cardinal Ratzinger" and posts by "Pope Benedict XVI" as having the same author, go to **Users --> Authors & Users**, click on the "Edit" link for Pope Benedict XVI, and add a line like this to the Profile text: a.k.a.: Joseph Cardinal Ratzinger You can add as many aliases as you like. You can also add any other text that you like to the Profile without interfering with FeedWordPress's ability to use the aliases. Each alias must be on a line by itself. __Unfamiliar authors:__ By default, if the author named by the newsfeed is unfamiliar -- that is, if there is no-one with that name registered in the WordPress author's database -- then by default FeedWordPress will automatically create a new user account with the given name and attribute the post to the new user. The default behavior can be changed, using either the global settings in **Options --> Syndication** or the [feed settings][] under **Links --> Syndicated --> Edit**, so that posts by unfamiliar authors will either be attributed to a default author (instead of creating a new user account to attribute them to), or filtered out and not syndicated at all. One of the uses of this feature is to filtering posts by author: if you want to your blog to syndicate only the posts by one particular author from a feed that has several authors, you could do so by creating a user account with that author's name, adding the new feed(s), and then setting **Unfamiliar authors** under **Links --> Syndicated --> Edit** to "don't syndicate the post". Since only posts by authors that are in your database will be included, and only the author that you wanted posts from has been added to your database, this will filter out posts by anyone else on the feeds with that setting. (Similarly, you could set up FeedWordPress so that *all* the feeds are filtered by author by creating the set of users named after the authors you want to syndicate, and then setting the default behavior for *all* feeds at **Options --> Syndication**). If you need an author filter with more complex logic than this allows, you can always create a `syndicated_item` filter in PHP (see [Plugin API][]) that manipulates the `['author_name']` or `['dc']['creator']` elements of a syndicated item. 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_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_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_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_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()``][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-2007 by Charles Johnson. It uses code derived or translated from: - [wp-rss-aggregate.php][] by [Kellan Elliot-McCrea](kellan@protest.net) - [MagpieRSS][] 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 [MagpieRSS]: http://magpierss.sourceforge.net/ [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 ```