# feedwordpress/0.95/README.text FeedWordPress, version 0.95. 604 lines. - Page: https://pluginprobe.com/plugins/feedwordpress/0.95/code/README.text - Raw: https://pluginprobe.com/plugins/feedwordpress/0.95/raw/README.text - Modified: 2007-11-21T22:50:56+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.95/code/README.text#L10-L20`. ``` FeedWordPress ============= * Author: [Charles Johnson](http://www.radgeek.com/contact) * Version: 0.95 * 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 . Basic Concepts -------------- FeedWordPress is written as a plugin for [WordPress 1.5][]. 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 treat 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. If you need to add, remove, or change information for any contributors, you can do so easily 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, delete, and modify Contributors; users with an access level of 6 or greater can change syndication options. When FeedWordPress looks for new posts, it does so by retrieving 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). __Feed settings:__ All of the information for a syndicated feed is stored in the WordPress Links database. Feeds in the category to be syndicated (by default, "Contributors") use several fields of the standard WordPress Link record: - The RSS URI is used to store the URI for the feed to be syndicated. (Note that this is *not* the same as the Link URI. The Link URI points to the human-readable *front page* of the website that the feed syndicates.) - The Link URI is used to store a URI to the human-readable front page (*not* the feed!) of the syndicated website. FeedWordPress automatically updates this URI using the URI that is reported by the newsfeed whenever it checks the feed for new posts, so if the page moves this will be reflected automatically on your Contributors links list. - The Link Name is used to store the title of the syndicated website. By default, FeedWordPress automatically updates the name of the link whenever it checks for new posts, using the title that the newsfeed reports (so that if a Contributor changes the title of her website, this is reflected automatically on your Contributors links list). This behavior can be turned off for all feeds through the settings in Options --> Syndication. The default behavior can be overridden for specific feeds using the feed setting `hardcode name`. - The Short Description is used to store the tagline of the syndicated website. By default, FeedWordPress automatically updates the description whenever it checks for new posts, using the tagline or description that the newsfeed reports (so that if a Contributor changes the tagline of her website, this is reflected automatically on your Contributors links list). his behavior can be turned off for all feeds through the settings in Options --> Syndication. The default behavior can be overridden for specific feeds using the feed setting `hardcode description`. - 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 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. The Link Notes section can be used to add, remove, and change custom feed settings. For example, if you want to *add* the feed setting for `unfamiliar author` with the value `filter`, you can do so by going to Links --> Syndicated, clicking the "Edit" link for the feed that you wish to add this setting for, and then adding the following, on a line by itself, to the Link Notes section: unfamiliar author: filter To remove the setting, follow the same procedure, but find the line for the feed setting that you want to remove and remove it. To change the value, simply change the text that follows after the colon. Most settings in the Link Notes have no effect on FeedWordPress, but you can use them to store information for templates to retrieve using the `get_feed_meta()` template function in a post context (see Template API below). 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 something like this to each feed's Link Notes, on a line by itself: 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 settings with special effects on FeedWordPress are `cats`, `hardcode name`, `hardcode description`, `hardcode categories`, `post status`, `comment status`, `ping status`, `unfamiliar author`, and `unfamiliar categories`. For descriptions of their effects, see Special Feed Settings below. ### 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, such as `is_syndicated()`, `the_syndication_source()`, `the_syndication_source_link()`, and `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 below. ### 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 `cats` feed setting. 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 categories that they were placed in on Alas, A Blog), you could do this by going to Links --> Syndicated, clicking the "Edit" link for Alas, A Blog, and adding the following line to the Link Notes section: cats: Pacific Northwest:Cartoonists (The colon separates one category name from the next.) 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:__ By default, if one of the category names that a newsfeed provides is unfamiliar -- that is, if there is not yet any category with that name (or with that name as an alias) in your WordPress database -- 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, using either the global settings in Options --> Syndication or the `unfamiliar categories` feed setting (see Feed Settings above), so that unfamiliar categories will not be added to the database. If you choose to disable the creation of new categories, 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. One of the uses of this feature is filtering 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 adding the following line to the Link Notes section of the feed(s) that you want to filter: unfamiliar categories: filter 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 below) 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 first name, (3) their nickname, (4) their full name, or (5) 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 `unfamiliar author` feed setting (see Feed Settings above), 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 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 adding the following line to the Link Notes section of the feed(s) that you want to filter: unfamiliar author: filter 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 below) that manipulates the `['author_name']` or `['dc']['creator']` elements of a syndicated item. Special Feed Settings --------------------- Most feed settings (see Feed Settings above) have no effect on FeedWordPress itself, but can be useful because they can be accessed from templates using the `get_feed_meta()` template function in a post context (see Feed Settings above for an example). However, you can use some feed settings to affect how FeedWordPress will process posts from that particular feed. Currently, these 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. Note that by default, FeedWordPress will place them in those categories *in addition to* any categories that the author of the post put them in on her own website. If you want to place posts from a feed *only* in the categories you explicitly set, then you should use the `cats` setting together with the `unfamiliar categories` setting. (See Categories above and `unfamiliar categories` below for the nitty-gritty.) - `hardcode name: (yes|no)` By default, FeedWordPress updates the value of the Link Name field automatically to reflect the title that is reported by a syndicated feed--so that if one of your contributors changes the title of her website, the change will be reflected on your Contributors list after the next update. If you want to stop this behavior (so that you can set the title of a Contributor link manually -- e.g. so that you can use an abbreviated form for reasons of space), you can change the default behavior for *all* feeds using the settings in Options --> Syndication. If you want to override the default behavior for only *one* feed, you can use the `hardcode name` feed setting. If FeedWordPress updates the title of all feeds by default, but you wish to use a manually-set title for one particular feed, you can add a line like this to the Link Notes section of the feed that you want to manually set the title for: hardcode name: yes Similarly, if FeedWordPress uses your manually-entered titles for all feeds by default, but you wish to use an automatically updated title for one particular feed, you can add a line like this to the Link Notes section of the feed that you want to manually set the title for: hardcode name: no If `hardcode name` is absent, or set to a value other than `yes` or `no`, FeedWordPress will follow the default behavior set under Options --> Syndication. - `hardcode description: (yes|no)` 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--so that if one of your contributors changes the tagline for her website, the change will be reflected on your Contributors list after the next update. If you want to stop this behavior (so that you can set the taglien of a Contributor link manually -- e.g. so that you can use it to provide information of another sort or use an abbreviated form for reasons of space), you can change the default behavior for *all* feeds using the settings in Options --> Syndication. If you want to override the default behavior for only *one* feed, you can use the `hardcode description` feed setting. If FeedWordPress updates the description of all feeds by default, but you wish to use a manually-set description for one particular feed, you can add a line like this to the Link Notes section of that particular feed: hardcode description: yes Similarly, if FeedWordPress uses your manually-entered descriptions for all feeds by default, but you wish to use an automatically updated description for one particular feed, you can add a line like this to the Link Notes section of that particular feed: hardcode description: no If `hardcode description` is absent, or set to a value other than `yes` or `no`, FeedWordPress will follow the default behavior set under Options --> Syndication. - `hardcode categories: (yes|no)` **This setting has been deprecated.** If set to `yes` it is now treated as equivalent to `unfamiliar categories: default`. (See below.) - `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. - `unfamiliar authors: (create|default|filter)` By default, FeedWordPress creates new author accounts whenever it finds a new post that is by an author whose name is not already in the WordPress database, and uses that account for this post and any future posts by an author of that name. FeedWordPress also allows you to attribute posts by unfamiliar authors to a *default* user account (currently, this means the System Administrator account), *instead of* creating a new author, or simply not to syndicate posts by unfamiliar authors (thus only syndicating posts by authors who are already in the database). Which of these FeedWordPress does by default can be set using the settings in Options --> Syndicated. You can also override the default behavior for specific feeds by adding the `unfamiliar author` feed setting to the Link Notes section of a feed. For example, to ensure that FeedWordPress filters out posts by unfamiliar authors for one particular feed, add the setting: unfamiliar author: filter To ensure that FeedWordPress assigns posts by unfamiliar authors to the default user account instead of creating a new user account, add the setting: unfamiliar author: default If you changed the default behavior under Options --> Syndicated but want to ensure that FeedWordPress creates new author accounts for unfamiliar authors on one specific feed, add the setting: unfamiliar author: create If the setting is anything other than `create`, `default`, or `filter`, FeedWordPress will ignore the setting and follow the default behavior that you specified under Options --> Syndication. - `unfamiliar categories: (create|default|filter)` By default, FeedWordPress creates categories whenever it finds a new post that is placed in categories whose names are not already in the WordPress database. FeedWordPress allows you to change this behavior, so that it will *not* create new category names. It also allows you to choose whether or not posts must match *at least one* familiar category to be syndicated at all. Which of these FeedWordPress does by default can be set using the settings in Options --> Syndicated. You can also override the default behavior for specific feeds by adding the `unfamiliar categories` feed setting to the Link Notes section of a feed. For example, to ensure that, when adding new posts from *one particular feed*, FeedWordPress does *not* create new categories, and filters out any posts that don't match *at least one* of the categories that you have already defined, add the setting: unfamiliar categories: filter To ensure that FeedWordPress does *not* create new categories, but *will* still syndicate categories even if they don't match any of the pre-defined categories, add the following to the feed settings: unfamiliar categories: default If you changed the default behavior under Options --> Syndicated but want to ensure that FeedWordPress creates new categories for posts from one particular feed, add the setting: unfamiliar categories: create If the setting is anything other than `create`, `default`, or `filter`, FeedWordPress will ignore the setting and follow the default behavior that you specified under Options --> Syndication. 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 ```