PluginProbe
FeedWordPress / 0.95
FeedWordPress v0.95
trunk 0.8 0.9 0.91 0.95 0.96 0.97 0.98 0.981 0.99 0.991 0.992 0.993 2008.1030 2008.1101 2008.1105 2008.1214 2009.0612 2009.0613 2009.0618 2009.0707 2009.1111 2009.1112 2010.0127 2010.0528 All 65 releases
← All changes | README.text +401 -306 0.98 → 0.95 View file →
@@ -1,273 +1,192 @@
1 1 FeedWordPress
2 2 =============
3 3
4 -* Author: [Charles Johnson](http://radgeek.com/contact)
5 -* Version: 0.98
4 +* Author: [Charles Johnson](http://www.radgeek.com/contact)
5 +* Version: 0.95
6 6 * Project URI: <http://projects.radgeek.com/feedwordpress>
7 -* License: GPL 2. See License below for copyright jots and tittles.
7 +* License: GPL. See License below for copyright jots and tittles.
8 8
9 9 Introduction
10 10 ------------
11 -FeedWordPress is an Atom/RSS aggregator for the WordPress weblog software. It
12 -syndicates content from newsfeeds that you choose into your WordPress webblog;
13 -if you syndicate several newsfeeds then you can use WordPress's posts database
14 -and templating engine as the back-end of an aggregation ("planet") website. I
15 -originally developed it because I needed a more flexible replacement for
16 -[Planet][] to use at [Feminist Blogs][].
11 +FeedWordPress is an Atom/RSS aggregator for WordPress. It syndicates content
12 +from newsfeeds that you select into your WordPress blog; if you syndicate
13 +several newsfeeds then you can WordPress's posts database and templating engine
14 +as the back-end of an aggregation ("planet") website. I originally developed it
15 +because I needed a more flexible replacement for [Planet][] to use at
16 +[Feminist Blogs][].
17 17
18 18 [Planet]: http://www.planetplanet.org/ "Planet Planet"
19 19 [Feminist Blogs]: http://www.feministblogs.org/
20 20
21 21 FeedWordPress is designed with flexibility, ease of use, and ease of
22 -configuration in mind. You'll need a working installation of WordPress (version
23 -[2.0][] or [1.5][]), and also FTP or SFTP access to your web host. The ability
24 -to create cron jobs on your web host would be very helpful but it's not
25 -absolutely necessary. You *don't* need to tweak any plain-text configuration
26 -files and you *don't* need shell access to your web host to make it work.
27 -(Although, I should point out, web hosts that *don't* offer shell access are
28 -*bad web hosts*.)
22 +configuration in mind. You'll need a working installation of [WordPress 1.5][]
23 +and FTP or SFTP access to your web host. The ability to create cron jobs on your
24 +web host would be very helpful but it's not absolutely necessary. You *don't*
25 +need to tweak any plain-text configuration files and you *don't* need shell
26 +access to your web host to make it work. (Although, I should point out, web
27 +hosts that *don't* offer shell access are *bad web hosts*.)
29 28
30 - [2.0]: http://wordpress.org/development/2005/12/wp2/
31 - [1.5]: http://wordpress.org/development/2005/02/strayhorn/
29 + [WordPress 1.5]: http://wordpress.org/development/2005/02/strayhorn/
32 30
33 -Installation
34 -### Requirements ###
31 +Installation & Requirements
32 +---------------------------
33 +You'll need a website with WordPress 1.5 installed and configured and FTP or
34 +SFTP access to your web space. You'll probably also want to have either (1)
35 +the ability to create cron jobs on your web host, or (2) a computer of your
36 +own that has always-on Internet access.
35 37
36 -To use version 0.98 of FeedWordPress, you will need:
37 -
38 -1. an installed configured copy of WordPress 2.0.x or 1.5.x. (FeedWordPress
39 - *will not work* with WP 1.2 or WP MU development builds.)
40 -
41 -2. FTP or SFTP access to your web host
42 -
43 -And you'll probably also want to have either:
44 -
45 -1. the ability to create cron jobs on your web host, or at least
46 -
47 -2. a computer of your own and always-on Internet access
48 -
49 -### Installation ###
50 -
51 -#### Upgrades ####
52 -
53 -To *upgrade* an existing installation of FeedWordPress to version 0.98:
54 -
55 -1. Download the FeedWordPress archive in zip or gzipped tar format and
56 - extract the files on your computer. Replace your existing FeedWordPress
57 - files with the new files. Be sure to upgrade `rss-functions.php` if you
58 - use the optional MagpieRSS upgrade, or don't use it yet but do want to
59 - syndicate Atom 1.0 feeds.
60 -
61 -2. If you are upgrading from version 0.96 or earlier, **immediately** log
62 - in to the WordPress Dashboard, and go to Options --> Syndicated. Follow
63 - the directions to launch the database upgrade procedure. The new
64 - versions of FeedWordPress incorporate some long-needed improvements, but
65 - old meta-data needs to be updated to prevent duplicate posts and other
66 - possible maladies. If you're upgrading an existing installation, updates
67 - and FeedWordPress template functions *will not work* until you've done
68 - the upgrade.
69 -
70 -3. Take a coffee break while the upgrade runs. It should, hopefully, finish
71 - within a few minutes even on relatively large databases.
72 -
73 -4. `update-feeds.php` has been overhauled to improve performance and ease
74 - of use, and also to make errors easier to detect and eliminate. The
75 - overhaul doesn't require any changes to your set up *if* you used
76 - XML-RPC pings, or command-line PHP, to do scheduled updates. It *does*
77 - affect you if you used curl or some other tool to send HTTP requests to
78 - `update-feeds.php`: your old cron job will probably not work anymore.
79 - See [Setting Up Feed Updates][] below to get scheduled updates back on
80 - track.
81 -
82 -5. Enjoy your new installation of FeedWordPress.
83 -
84 -#### New Installations ####
85 -
86 -1. Install `feedwordpress.php` in your WordPress `plugins` directory
87 - and `update-feeds.php` in your WordPress `wp-content` directory.
38 +1. Install `feedwordpress.php` in your WordPress `plugins` directory and
39 + `update.php` in your WordPress `wp-content` directory.
88 40
89 41 2. (Optional) Upgrade the copy of MagpieRSS packaged with WordPress by
90 42 installing the new `rss-functions.php` (archived in
91 43 `OPTIONAL/wp-includes`) into your WordPress `wp-includes` directory.
92 - Upgrading MagpieRSS is necessary if you want to take advantage of
93 - support for Atom 1.0, multiple post categories, RSS enclosures, and
94 - multiple character encodings. (Note, however, that support for
95 - transliterating between character encodings is a very complex and
96 - iffy prospect in some PHP environments, so if you intend to use
97 - a lot of feeds with alternate encodings you should make sure that
98 - your installation of PHP is up-to-date and that you keep a copy of
99 - the old MagpieRSS around to compare results.)
100 44
101 -3. Log in to the WordPress Dashboard and activate the FeedWordPress
102 - plugin.
45 +3. Log in to the WordPress Dashboard and activate the FeedWordPress plugin.
46 + Go to Options --> Syndication to set up initial settings for the
47 + syndication link category ("Contributors") by default and the RPC secret
48 + word (blank by default, but you should probably set it to something.)
103 49
104 -4. While you're at the Dashboard, once the plugin is activated, you can
105 - go to Options --> Syndication and set (1) the link category that
106 - FeedWordPress will syndicate links from (by default, "Contributors"),
107 - and (2) a "secret word" for your RPC-XML updating interface. This
108 - provides some light security by keeping passing ruffians from saying
109 - "Update all the feeds" at will to your FeedWordPress installation.
50 +4. Set up links for syndication from the WordPress Dashboard using
51 + Links --> Syndicated or Links --> Import.
110 52
111 -5. Go to Links --> Syndicated to set up the list of sites that you want
112 - FeedWordPress to syndicate onto your blog. (If you have the feeds you
113 - want to aggregate in a service such as Bloglines, you may prefer to
114 - export them to an OPML file and use WordPress's Links --> Import to
115 - import them into the contributors category.)
53 +5. FeedWordPress is now *ready* to feed syndicated content into WordPress.
54 + In order for it to actually receive that content, either (1) have your
55 + contributors add WordPress's XML-RPC URI to their blog's list of URIs
56 + to ping when they update posts, (2) set up a cron job to check in on all
57 + the feeds on a regular basis, or (3) both. If you do (2), you can either
58 + set up a job to run `php update-feeds.php` on your web host, or set one
59 + up on any computer with always-on Internet access to request
60 + `update-feeds.php` over the web.
61 +
62 + If your copy of WordPress is installed at <http://www.zyx.com/blog>, and
63 + you set the secret word for XML-RPC pings to "foo", then your XML-RPC
64 + URI will be <http://www.zyx.com/blog/xmlrpc.php>, and the URI to request
65 + for `update-feeds.php` to update all feeds will be
66 + <http://www.zyx.com/blog/wp-content/update-feeds.php?shibboleth=foo>
116 67
117 -#### Setting Up Feed Updates ####
68 +For detailed installation instructions, point your web browser to
69 +<http://projects.radgeek.com/feedwordpress/install>.
118 70
119 -FeedWordPress is now ready to accept posts from its syndication sources.
120 -Unfortunately, it doesn't yet know *when* to go get them. (**This may be true
121 -even if you are upgrading an existing installation of FeedWordPress:** your old
122 -cron job will still work if you used command-line PHP or blogging software pings
123 -to do updates, but it will need to be fixed if you used curl or another tool to
124 -send HTTP requests to `update-feeds.php`.)
71 +Basic Concepts
72 +--------------
73 +FeedWordPress is written as a plugin for [WordPress 1.5][]. It is designed to
74 +store all the data it needs within the WordPress database and to make that data
75 +easy to manage from within the WordPress Dashboard.
125 76
126 -You can load in syndicated posts for the first time by pointing your web browser
127 -to `update-feeds.php`. If you have WordPress installed at, say,
128 -<http://www.zyx.com/blog> then you should point your browser to
129 -<http://www.zyx.com/blog/wp-content/update-feeds.php> and log in as any user in
130 -the user database. (You may want to create a new "dummy" user for doing
131 -scheduled updates, using **Users --> Authors & Users --> Add New User**. Tell
132 -FeedWordPress to update all feeds, and you'll get the first wave of posts
133 -imported into the database.
77 +### Contributors / Newsfeeds ###
134 78
135 -Congratulations! You should now have an aggregator site full of delicious
136 -syndicated content hot off of the newswires. Now you just need a way to *keep*
137 -the content freshly updated. Unless you enjoy manually browsing to
138 -`update-feeds.php` every hour on the hour, you'll probably want to do this by
139 -setting up your site for automated updates.
79 +FeedWordPress uses the WordPress Links database to keep a list of the feeds from
80 +which it will syndicate content. WordPress allows you to place links in
81 +categories; FeedWordPress will treat all and only the links in one category
82 +(by default, this is a category named "Contributors"; you can change the
83 +category that FeedWordPress will use using Options --> Syndication).
140 84
141 -You can pull that off in one of two ways, or by a mixture of both:
142 -
143 -1. **The Blogging Software Ping Method:** You can get all of your
144 - contributors to add you to the list of URIs that they notify of updates:
145 - while FeedWordPress is activated, it will accept XML-RPC "recently
146 - updated" pings in the standard format accepted by Weblogs.com,
147 - Ping-O-Matic, Technorati, and other services. Most blogging software
148 - allows users to add a URI to the list of URIs that get pinged on each
149 - update. (See, for example, Options --> Writing --> Update Services in
150 - WordPress, or Configuration --> Preferences --> Publicity / Remote
151 - Interfaces / TrackBack in Movable Type.)
152 -
153 - If you can get a contributor to add your XML-RPC URI to her
154 - services-to-ping list (if you have WordPress installed at
155 - <http://www.zyx.com/blog>, say, the URI to add should be
156 - <http://www.zyx.com/blog/xmlrpc.php>), then whenever she updates her
157 - blog, her blogging software will ping your FeedWordPress installation,
158 - and FeedWordPress will look up her feed to grab the new posts off of
159 - it.
85 +From WordPress's perspective, the list of Contributors are normal links, and
86 +they can be manipulated like other links through the WordPress Dashboard. If
87 +you need to add, remove, or change information for any contributors, you can
88 +do so easily under Links --> Syndicated. If you want to distribute the labor of
89 +adding, updating, and managing feeds, you can use the WordPress login and
90 +access privileges system. Users with an access level of 5 or greater can add,
91 +delete, and modify Contributors; users with an access level of 6 or greater can
92 +change syndication options.
160 93
161 -2. **The Scheduled Update Job Method:** You may very well not be able to
162 - get all your contributors to add your site to their blogging software's
163 - ping list, and even if you do you may want to have a back-up option to
164 - catch updates later even if the ping fails to go through on one
165 - particular occasion. You'll need to create a scheduled job to
166 - periodically check for updates on *all* the feeds. You'll need either
167 - (a) the ability to create cron jobs on your web host or (b) access to
168 - another computer with a reliable, always-on Internet connection.
169 -
170 - If you *can* create a crontab on your web host, then the best thing to
171 - do is to create a cron job that will run update-feeds.php through the
172 - PHP command-line interface. For example, if you have WordPress installed
173 - in `~/www/wp` (where ~ is your home directory), you might insert the
174 - following line into your crontab:
175 -
176 - 25 * * * * cd $HOME/www/wp/wp-content ; php -q update-feeds.php
94 +When FeedWordPress looks for new posts, it does so by retrieving one or all of
95 +the links from the Contributors category (depending on whether it has been told
96 +to scan for new posts on one or all of the feeds).
177 97
178 - If you *don't* have access to (a), you can still save the day using
179 - another computer with always-on Internet access that sends a POST
180 - request to the `update-feeds.php` URI on a regular schedule. So, for
181 - example, if you have WordPress installed at <http://www.zyx.com/blog>,
182 - and you have a dummy user in your WordPress database with the login name
183 - 'login' and the password 'pass', then you could add the following line
184 - to the crontab on a home Linux box:
185 -
186 - 25 * * * * curl --user login:pass http://www.zyx.com/blog/wp-content/update-feeds.php -d update=quiet
98 +__Feed settings:__ All of the information for a syndicated feed is stored in
99 +the WordPress Links database. Feeds in the category to be syndicated (by
100 +default, "Contributors") use several fields of the standard WordPress Link
101 +record:
187 102
188 - The `-d update=quiet` switch ensures that (1) `update-feeds.php` will
189 - receive an HTTP POST request rather than an HTTP GET request (which
190 - is important, since it won't take any actions with side-effects -- such
191 - as checking for new posts -- unless it receives an HTTP POST); it also
192 - tells it to suppress the HTML output that it would generate for normal
193 - web browsers, and only to output text if it encounters errors (this will
194 - keep the number of e-mails you receive from the Cron Daemon to a
195 - minimum).
103 +- The RSS URI is used to store the URI for the feed to be syndicated.
104 + (Note that this is *not* the same as the Link URI. The Link URI points
105 + to the human-readable *front page* of the website that the feed
106 + syndicates.)
196 107
197 - If you are using Windows XP and have a version of curl (such as the
198 - version included in [Cygwin][]), you can create a Scheduled Task to
199 - similar effect.
108 +- The Link URI is used to store a URI to the human-readable front page
109 + (*not* the feed!) of the syndicated website. FeedWordPress automatically
110 + updates this URI using the URI that is reported by the newsfeed whenever
111 + it checks the feed for new posts, so if the page moves this will be
112 + reflected automatically on your Contributors links list.
200 113
201 - [Cygwin]: http://www.cygwin.com/
114 +- The Link Name is used to store the title of the syndicated website.
115 + By default, FeedWordPress automatically updates the name of the link
116 + whenever it checks for new posts, using the title that the
117 + newsfeed reports (so that if a Contributor changes the title of her
118 + website, this is reflected automatically on your Contributors links
119 + list). This behavior can be turned off for all feeds through the
120 + settings in Options --> Syndication. The default behavior can be
121 + overridden for specific feeds using the feed setting
122 + `hardcode name`.
202 123
203 -Basic Concepts
204 -FeedWordPress is written as a plugin for the WordPress weblog software. It is
205 -designed to store all the data it needs within the WordPress database and to
206 -make that data easy to manage from within the WordPress Dashboard.
124 +- The Short Description is used to store the tagline of the syndicated
125 + website. By default, FeedWordPress automatically updates the description
126 + whenever it checks for new posts, using the tagline or description that
127 + the newsfeed reports (so that if a Contributor changes the tagline of
128 + her website, this is reflected automatically on your Contributors links
129 + list). his behavior can be turned off for all feeds through the
130 + settings in Options --> Syndication. The default behavior can be
131 + overridden for specific feeds using the feed setting
132 + `hardcode description`.
207 133
208 -### Contributors / Newsfeeds ###
134 +- The Link Notes are used to store a collection of manually-encoded and
135 + automatically-generated settings that apply to this feed. The format of
136 + settings in Link Notes is:
137 +
138 + key1: value1
139 + key2: value2
140 + feed/key1: value1
141 + feed/key2: value2
142 +
143 + And so on. Values that are prefixed by 'feed/' are automatically
144 + generated from feed data every time the feed syndicated by this link is
145 + checked for updates. Values without the prefix are set manually by the
146 + user.
209 147
210 -FeedWordPress uses the WordPress Links database to keep a list of the feeds from
211 -which it will syndicate content. WordPress allows you to place links in
212 -categories; FeedWordPress will make use of all and only the links in one
213 -category (by default, this is a category named "Contributors"; you can change
214 -the category that FeedWordPress will use using **Options --> Syndication**).
148 +The Link Notes section can be used to add, remove, and change custom feed
149 +settings. For example, if you want to *add* the feed setting for
150 +`unfamiliar author` with the value `filter`, you can do so by going to Links -->
151 +Syndicated, clicking the "Edit" link for the feed that you wish to add this
152 +setting for, and then adding the following, on a line by itself, to the Link
153 +Notes section:
215 154
216 -From WordPress's perspective, the list of Contributors are normal links, and
217 -they can be manipulated like other links through the WordPress Dashboard.
218 -However, FeedWordPress provides a nicer interface for adding, removing, or
219 -changing information for the Contributor Links from the WordPress Dashboard,
220 -under **Links --> Syndicated**.
155 + unfamiliar author: filter
221 156
222 -If you want to distribute the labor of adding, updating, and managing feeds
223 -between several people, you can use the WordPress login andaccess privileges
224 -system. Any users with an access level of 5 or greater can add, delete, and
225 -modify Contributors; users with an access level of 6 or greater can change
226 -syndication options.
157 +To remove the setting, follow the same procedure, but find the line for the
158 +feed setting that you want to remove and remove it. To change the value, simply
159 +change the text that follows after the colon.
227 160
228 -When FeedWordPress looks for new posts, it retrieves one or all of the links
229 -from the Contributors category (depending on whether it has been told to scan
230 -for new posts on one or all of the feeds), determines which of them should be
231 -polled for updates (based on how long it has been since the last time each feed
232 -was polled for updates), and then uses an HTTP conditional GET to check for
233 -updates at the "RSS URI" for each Link that it selects. Any new posts are added
234 -to the database, and old posts that have been updated since the last poll are
235 -updated to reflect the new version.
161 +Most settings in the Link Notes have no effect on FeedWordPress, but you can use
162 +them to store information for templates to retrieve using the `get_feed_meta()`
163 +template function in a post context (see Template API below). For example, many
164 +aggregator sites use a "face" image for each feed to visually distinguish posts
165 +from different feeds. To implement a face feature, you could add something
166 +like this to each feed's Link Notes, on a line by itself:
236 167
237 -__Feed settings:__ All of the information for a syndicated feed is stored in the
238 -WordPress Links database, and can be easily edited using an interface that
239 -FeedWordPress provides under **Links --> Syndicated**. (If you're curious about
240 -the technical details of how the information is stored, you can find out more
241 -under [API: How feed information is stored][].)
168 + face: http://www.zyx.com/mugs/ugly
242 169
243 -You can use a feed's **Edit** link under **Links --> Syndicated** to affect how
244 -FeedWordPress prcesses posts from that feed. (Most of these options can either
245 -be set for *one particular feed* using **Links --> Syndicated --> Edit**, or set
246 -as the default for *all feeds* using **Options --> Syndication**.) The **Edit**
247 -link also allows you to set **Custom Feed Settings** for use in templates,
248 -through the use of the [`get_feed_meta()`][get_feed_meta] template function in a
249 -post context (see [Template API][]). For example, many aggregator sites use a
250 -"face" image for each feed to visually distinguish posts from different feeds.
251 -To implement a face feature, you could add a custom setting for each Contributor
252 -Link, with the key of "face" and a URI such as "http://www.zyx.com/mugs/ugly"
253 -for the value. (The URI should be changed out for each feed to point to the
254 -appropriate image, of course.) Then, to use the setting from within a template,
255 -add something like:
170 +The URI should be changed out for each feed to point to the appropriate image,
171 +of course. Then, to use the setting from within a template:
256 172
257 - // In a post context
258 - <?php $img = get_feed_meta('face'); if (strlen($img) > 0): ?>
259 - <img src="<?=$img?>" alt="" />
260 - <?php endif; ?>
173 + // In a post context
174 + <?php $img = get_feed_meta('face'); if (strlen($img) > 0): ?>
175 + <img src="<?=$img?>" alt="" />
176 + <?php endif; ?>
261 177
262 178 ... which will display the image, if any, whose URI is set in the "face" setting
263 179 for the feed that post comes from. If there is no "face" setting for a
264 -particular feed, [`get_feed_meta()`][get_feed_meta] will return an empty string
265 -and no image will be displayed.
180 +particular feed, ``get_feed_meta()`` will return an empty string and no image
181 +will be displayed.
266 182
267 - [API: How feed information is stored]: http://projects.radgeek.com/feedwordpress/api#how-feed-information-is-stored
183 +Not all feed settings are only for templates. Some affect how FeedWordPress
184 +processes posts from that feed. Currently, the settings with special effects
185 +on FeedWordPress are `cats`, `hardcode name`, `hardcode description`,
186 +`hardcode categories`, `post status`, `comment status`, `ping status`,
187 +`unfamiliar author`, and `unfamiliar categories`. For descriptions of their
188 +effects, see Special Feed Settings below.
268 189
269 190 ### Syndicated Posts ###
270 191
271 192 Whenever FeedWordPress updates, it scans one or more of the feeds in its
@@ -275,16 +194,14 @@
275 194 database. Syndicated posts are displayed on your WordPress pages like any other
276 195 posts: they can be listed in archives by category, author, or date; they can be
277 196 found with the search box; and they are included in the newsfeed of your blog.
278 197
279 -In your WordPress templates (**Presentation --> Theme Editor**) you can access
280 -special information about syndicated posts using [functions provided by
281 -FeedWordPress][Template API], such as [`is_syndicated()`][is_syndicated],
282 -[`the_syndication_source()`][the_syndication_source],
283 -[`the_syndication_source_link()`][the_syndication_source_link], and
284 -[`get_feed_meta()`][get_feed_meta]. For example, here is the template code that
285 -I use (in a post context) to display both the author's name and the original
286 -source of the post in the templates for [Feminist Blogs][]:
198 +In your WordPress templates (Presentation --> Theme Editor) you can access
199 +special information about syndicated posts using functions provided by
200 +FeedWordPress, such as `is_syndicated()`, `the_syndication_source()`,
201 +`the_syndication_source_link()`, and `get_feed_meta()`. For example, here is
202 +the template code that I use (in a post context) to display both the author's
203 +name and the original source of the post in the templates for [Feminist Blogs][]:
287 204
288 205 <cite class="feed">from <?php the_author_posts_link()?><?php
289 206 if (is_syndicated() and (get_the_author() !== get_syndication_source())):
290 207 echo ' @ <a href="'; the_syndication_source_link(); echo '">';
@@ -291,9 +208,9 @@
291 208 the_syndication_source();
292 209 echo '</a>';
293 210 endif; ?></cite>
294 211
295 -For more information on template functions, see [Template API][].
212 +For more information on template functions, see Template API below.
296 213
297 214 ### Categories ###
298 215
299 216 WordPress allows for posts to be placed in *categories*. Each syndicated post
@@ -303,31 +220,34 @@
303 220
304 221 1. Categories (or "tags") that the original author placed the post in on
305 222 her blog
306 223
307 -2. Categories that you set explicitly for each feed using the
308 - **Categories** checkbox under **Links --> Syndicated --> Edit**. For
309 - example, if you wanted all the posts from Alas, A Blog to be placed in
310 - the "Pacific Northwest" category and the "Cartoonists" category (*in
311 - addition to* any other categories that they were placed in on Alas, A
312 - Blog), you could do this by creating the categories, going to **Links
313 - --> Syndicated**, clicking the "Edit" link for Alas, A Blog, and
314 - checking those two categories under the checkbox captioned "Categories."
224 +2. Categories that you set explicitly for each feed using the `cats`
225 + feed setting. For example, if you wanted all the posts from Alas, A Blog
226 + to be placed in the "Pacific Northwest" category and the "Cartoonists"
227 + category (in addition to any categories that they were placed in on
228 + Alas, A Blog), you could do this by going to Links --> Syndicated,
229 + clicking the "Edit" link for Alas, A Blog, and adding the following line
230 + to the Link Notes section:
231 +
232 + cats: Pacific Northwest:Cartoonists
315 233
234 + (The colon separates one category name from the next.)
235 +
316 236 Given the list of category names, FeedWordPress looks for categories in the
317 237 WordPress database with the same name as either (1) the category name, or
318 238 (2) one of the "aliases" listed in the category description.
319 239
320 -__Aliases:__ Different often authors use slightly different names for categories
321 -that mean the same thing (contributors to Feminist Blogs, for example, used
322 -categories including "Feminism", "feministy stuff", "Women's Issues", "Gender
323 -Issues", "Gender Equality", and so on). If you want FeedWordPress to treat one
324 -category name as a synonym for another, you can do so by creating an "alias" for
325 -the category. For example, to make FeedWordPress treat posts that are placed in
326 -the category "feministy stuff" as if they had been placed in the category
327 -"Feminism", go to **Manage --> Categories**, find the category "Feminism" and
328 -click the "Edit" link for it, and then add the following to the Description
329 -field, on a line by itself:
240 +__Aliases:__ Different often authors use slightly different names for
241 +categories that mean the same thing (contributors to Feminist Blogs, for
242 +example, used categories including "Feminism", "feministy stuff",
243 +"Women's Issues", "Gender Issues", "Gender Equality", and so on). If you want
244 +FeedWordPress to treat one category name as a synonym for another, you can
245 +do so by creating an "alias" for the category. For example, to make
246 +FeedWordPress treat posts that are placed in the category "feministy stuff" as
247 +if they had been placed in the category "Feminism", go to Manage --> Categories,
248 +find the category "Feminism" and click the "Edit" link for it, and then add
249 +the following to the Description field, on a line by itself:
330 250
331 251 a.k.a.: feministy stuff
332 252
333 253 You can add as many aliases as you like. You can also add any other text that
@@ -333,38 +253,38 @@
333 253 You can add as many aliases as you like. You can also add any other text that
334 254 you like to the Description without interfering with FeedWordPress's ability to
335 255 use the aliases. Each alias must be on a line by itself.
336 256
337 -__Unfamiliar categories:__ If one of the category names that a newsfeed provides
338 -is *unfamiliar* -- that is, if there is not yet any category in your WordPress
339 -database that either has that name, or uses that name as an alias -- then by
340 -default FeedWordPress will *automatically create* a new category with that name
341 -and place the current post in it. The default behavior can be changed so that
342 -unfamiliar categories will *not* be added to the database, using the
343 -**Unfamiliar categories** setting, either for *all* feeds (under **Options -->
344 -Syndication**) or for *one particular feed* (under **Links --> Syndicated**).
257 +__Unfamiliar categories:__ By default, if one of the category names that a
258 +newsfeed provides is unfamiliar -- that is, if there is not yet any category
259 +with that name (or with that name as an alias) in your WordPress database --
260 +then by default FeedWordPress will *automatically create* a new category with
261 +that name and place the current post in it. The default behavior can be changed,
262 +using either the global settings in Options --> Syndication or the
263 +`unfamiliar categories` feed setting (see Feed Settings above), so that unfamiliar
264 +categories will not be added to the database. If you choose to disable the
265 +creation of new categories, you can also choose whether or not FeedWordPress
266 +should syndicate posts that do not match *any* of the categories that are
267 +currently in the database.
345 268
346 -If you choose to disable the creation of new categories, either for all feeds or
347 -for one particular feed, then you can also choose whether or not FeedWordPress
348 -should syndicate posts that do not match *any* of the categories that are
349 -currently in the database. This allows you to do some simple filtering of posts
350 -by category: if you want to your blog to syndicate only the posts in one
351 -particular category from a feed that has several categories, you could do so by
352 -creating a category by that name, adding the new feed(s), and then setting
353 -**Unfamiliar categories** under **Links --> Syndicated --> Edit** to "don't
354 -create new categories and don't syndicate posts unless they match at least one
355 -familiar category".
269 +One of the uses of this feature is filtering posts by category: if you want to
270 +your blog to syndicate only the posts in one particular category from a feed
271 +that has several categories, you could do so by creating a category by that
272 +name, adding the new feed(s), and then adding the following line to the Link
273 +Notes section of the feed(s) that you want to filter:
356 274
275 + unfamiliar categories: filter
276 +
357 277 Since only posts in categories that are in your database will be included, and
358 278 only the category or categories that you wanted posts from has been added to
359 -your database, this will filter out all the posts that aren't in the category or
360 -categories that you defined ahead of time. (Similarly, you could set up
279 +your database, this will filter out all the posts that aren't in the category
280 +or categories that you defined ahead of time. (Similarly, you could set up
361 281 FeedWordPress so that *all* the feeds are filtered by author by creating the set
362 282 of users named after the authors you want to syndicate, and then setting the
363 -default behavior for *all* feeds at **Options --> Syndication**).
283 +default behavior for *all* feeds at Options --> Syndication).
364 284
365 285 If you need a category filter with more complex logic, you can always create a
366 -`syndicated_item` filter in PHP (see [Plugin API][]) that manipulates the
286 +`syndicated_item` filter in PHP (see Plugin API below) that manipulates the
367 287 `['categories']` array of a syndicated item.
368 288
369 289 ### Authors ###
370 290
@@ -372,10 +292,10 @@
372 292 (If a feed doesn't, then FeedWordPress will create an author's name based on
373 293 the title of the feed from which the item was taken.) This information is used
374 294 to determine the WordPress user that the post will be attributed to. Given the
375 295 name of the author, FeedWordPress looks for authors in the WordPress database
376 -with the same name as either (1) their login, (2) their display name, (3) their
377 -e-mail address (if given), or (4) one of the "aliases" listed in the
296 +with the same name as either (1) their login, (2) their first name, (3) their
297 +nickname, (4) their full name, or (5) one of the "aliases" listed in the
378 298 user's profile.
379 299
380 300 __Aliases:__ If there is an author who posts under more than one name (for
381 301 example, one of our contributors at [Feminist Blogs][] posts on several
@@ -382,13 +302,13 @@
382 302 different blogs, sometimes using her full name and sometimes using only her
383 303 first name), then you can ensure that FeedWordPress will attribute those posts
384 304 to the same author by creating "aliases" for the author. For example, to make
385 305 FeedWordPress treat posts by "Joseph Cardinal Ratzinger" and posts by "Pope
386 -Benedict XVI" as having the same author, go to **Users --> Authors & Users**,
387 -click on the "Edit" link for Pope Benedict XVI, and add a line like this to the
306 +Benedict XVI" as having the same author, go to Users --> Authors & Users, click
307 +on the "Edit" link for Pope Benedict XVI, and add a line like this to the
388 308 Profile text:
389 309
390 - a.k.a.: Joseph Cardinal Ratzinger
310 + a.k.a.: Joseph Cardinal Ratzinger
391 311
392 312 You can add as many aliases as you like. You can also add any other text that
393 313 you like to the Profile without interfering with FeedWordPress's ability to use
394 314 the aliases. Each alias must be on a line by itself.
@@ -397,31 +317,207 @@
397 317 unfamiliar -- that is, if there is no-one with that name registered in the
398 318 WordPress author's database -- then by default FeedWordPress will automatically
399 319 create a new user account with the given name and attribute the post to the new
400 320 user. The default behavior can be changed, using either the global settings in
401 -**Options --> Syndication** or the [feed settings][] under **Links -->
402 -Syndicated --> Edit**, so that posts by unfamiliar authors will either be
403 -attributed to a default author (instead of creating a new user account to
404 -attribute them to), or filtered out and not syndicated at all.
321 +Options --> Syndication or the `unfamiliar author` feed setting (see Feed
322 +Settings above), so that posts by unfamiliar authors will either be attributed
323 +to a default author (instead of creating a new user account to attribute them
324 +to), or filtered out and not syndicated at all.
405 325
406 -One of the uses of this feature is to filtering posts by author: if you want to
326 +One of the uses of this feature is filtering posts by author: if you want to
407 327 your blog to syndicate only the posts by one particular author from a feed that
408 328 has several authors, you could do so by creating a user account with that
409 -author's name, adding the new feed(s), and then setting **Unfamiliar authors**
410 -under **Links --> Syndicated --> Edit** to "don't syndicate the post". Since
411 -only posts by authors that are in your database will be included, and only the
412 -author that you wanted posts from has been added to your database, this will
329 +author's name, adding the new feed(s), and then adding the following line to the
330 +Link Notes section of the feed(s) that you want to filter:
331 +
332 + unfamiliar author: filter
333 +
334 +Since only posts by authors that are in your database will be included, and only
335 +the author that you wanted posts from has been added to your database, this will
413 336 filter out posts by anyone else on the feeds with that setting. (Similarly, you
414 337 could set up FeedWordPress so that *all* the feeds are filtered by author by
415 338 creating the set of users named after the authors you want to syndicate, and
416 -then setting the default behavior for *all* feeds at **Options -->
417 -Syndication**).
339 +then setting the default behavior for *all* feeds at Options --> Syndication).
418 340
419 341 If you need an author filter with more complex logic than this allows, you can
420 -always create a `syndicated_item` filter in PHP (see [Plugin API][]) that
342 +always create a `syndicated_item` filter in PHP (see Plugin API below) that
421 343 manipulates the `['author_name']` or `['dc']['creator']` elements of a
422 344 syndicated item.
423 345
346 +Special Feed Settings
347 +---------------------
348 +Most feed settings (see Feed Settings above) have no effect on FeedWordPress
349 +itself, but can be useful because they can be accessed from templates using the
350 +`get_feed_meta()` template function in a post context (see Feed Settings above
351 +for an example). However, you can use some feed settings to affect how
352 +FeedWordPress will process posts from that particular feed. Currently, these
353 +special settings are:
354 +
355 +- `cats:` a colon-separated list of default categories for any post coming
356 + from this feed. So, for example, a this line in its Notes section:
357 +
358 + cats: computers:web
359 +
360 + ... will make FeedWordPress place any posts syndicated from that feed in
361 + the "computers" and "web" categories. Note that by default,
362 + FeedWordPress will place them in those categories *in addition to* any
363 + categories that the author of the post put them in on her own website.
364 + If you want to place posts from a feed *only* in the categories you
365 + explicitly set, then you should use the `cats` setting together with
366 + the `unfamiliar categories` setting. (See Categories above and
367 + `unfamiliar categories` below for the nitty-gritty.)
368 +
369 +- `hardcode name: (yes|no)`
370 +
371 + By default, FeedWordPress updates the value of the Link Name field
372 + automatically to reflect the title that is reported by a syndicated
373 + feed--so that if one of your contributors changes the title of her
374 + website, the change will be reflected on your Contributors list after
375 + the next update. If you want to stop this behavior (so that you can
376 + set the title of a Contributor link manually -- e.g. so that you can use
377 + an abbreviated form for reasons of space), you can change the default
378 + behavior for *all* feeds using the settings in Options --> Syndication.
379 + If you want to override the default behavior for only *one* feed, you
380 + can use the `hardcode name` feed setting. If FeedWordPress updates the
381 + title of all feeds by default, but you wish to use a manually-set title
382 + for one particular feed, you can add a line like this to the Link Notes
383 + section of the feed that you want to manually set the title for:
384 +
385 + hardcode name: yes
386 +
387 + Similarly, if FeedWordPress uses your manually-entered titles for all
388 + feeds by default, but you wish to use an automatically updated title for
389 + one particular feed, you can add a line like this to the Link Notes
390 + section of the feed that you want to manually set the title for:
391 +
392 + hardcode name: no
393 +
394 + If `hardcode name` is absent, or set to a value other than `yes` or
395 + `no`, FeedWordPress will follow the default behavior set under
396 + Options --> Syndication.
397 +
398 +- `hardcode description: (yes|no)`
399 +
400 + By default, FeedWordPress updates the value of the Link Description
401 + field automatically to reflect the tagline or description that is
402 + reported by a syndicated feed--so that if one of your contributors
403 + changes the tagline for her website, the change will be reflected on
404 + your Contributors list after the next update. If you want to stop this
405 + behavior (so that you can set the taglien of a Contributor link manually
406 + -- e.g. so that you can use it to provide information of another sort or
407 + use an abbreviated form for reasons of space), you can change the
408 + default behavior for *all* feeds using the settings in Options -->
409 + Syndication. If you want to override the default behavior for only *one*
410 + feed, you can use the `hardcode description` feed setting. If
411 + FeedWordPress updates the description of all feeds by default, but you
412 + wish to use a manually-set description for one particular feed, you can
413 + add a line like this to the Link Notes section of that particular feed:
414 +
415 + hardcode description: yes
416 +
417 + Similarly, if FeedWordPress uses your manually-entered descriptions for
418 + all feeds by default, but you wish to use an automatically updated
419 + description for one particular feed, you can add a line like this to the
420 + Link Notes section of that particular feed:
421 +
422 + hardcode description: no
423 +
424 + If `hardcode description` is absent, or set to a value other than `yes`
425 + or `no`, FeedWordPress will follow the default behavior set under
426 + Options --> Syndication.
427 +
428 +- `hardcode categories: (yes|no)`
429 +
430 + **This setting has been deprecated.** If set to `yes` it is now treated
431 + as equivalent to `unfamiliar categories: default`. (See below.)
432 +
433 +- `post status:` sets the default post status for posts from this feed
434 + This can be 'publish', 'draft', or 'private'. By default, it is set to
435 + 'publish' (syndicated posts go online immediately).
436 +
437 +- `comment status:` sets the default status for comments on posts
438 + syndicated from this feed. By default, all comments on syndicated posts
439 + are closed, but you can set it to 'open', 'closed', or 'registered_only'
440 + for particular feeds.
441 +
442 +- `ping status:` sets the default status for receiving TrackBack and
443 + PingBack pings on posts syndicated from this feed. By default,
444 + syndicated posts are closed to pings, but you can set this to 'open' or
445 + 'closed' for particular feeds.
446 +
447 +- `unfamiliar authors: (create|default|filter)`
448 +
449 + By default, FeedWordPress creates new author accounts whenever it finds
450 + a new post that is by an author whose name is not already in the
451 + WordPress database, and uses that account for this post and any future
452 + posts by an author of that name. FeedWordPress also allows you to
453 + attribute posts by unfamiliar authors to a *default* user account
454 + (currently, this means the System Administrator account), *instead of*
455 + creating a new author, or simply not to syndicate posts by unfamiliar
456 + authors (thus only syndicating posts by authors who are already in the
457 + database).
458 +
459 + Which of these FeedWordPress does by default can be set using the
460 + settings in Options --> Syndicated. You can also override the default
461 + behavior for specific feeds by adding the `unfamiliar author` feed
462 + setting to the Link Notes section of a feed. For example, to ensure that
463 + FeedWordPress filters out posts by unfamiliar authors for one particular
464 + feed, add the setting:
465 +
466 + unfamiliar author: filter
467 +
468 + To ensure that FeedWordPress assigns posts by unfamiliar authors to the
469 + default user account instead of creating a new user account, add the
470 + setting:
471 +
472 + unfamiliar author: default
473 +
474 + If you changed the default behavior under Options --> Syndicated but
475 + want to ensure that FeedWordPress creates new author accounts for
476 + unfamiliar authors on one specific feed, add the setting:
477 +
478 + unfamiliar author: create
479 +
480 + If the setting is anything other than `create`, `default`, or `filter`,
481 + FeedWordPress will ignore the setting and follow the default behavior
482 + that you specified under Options --> Syndication.
483 +
484 +- `unfamiliar categories: (create|default|filter)`
485 +
486 + By default, FeedWordPress creates categories whenever it finds a new
487 + post that is placed in categories whose names are not already in the
488 + WordPress database. FeedWordPress allows you to change this behavior,
489 + so that it will *not* create new category names. It also allows you to
490 + choose whether or not posts must match *at least one* familiar category
491 + to be syndicated at all.
492 +
493 + Which of these FeedWordPress does by default can be set using the
494 + settings in Options --> Syndicated. You can also override the default
495 + behavior for specific feeds by adding the `unfamiliar categories` feed
496 + setting to the Link Notes section of a feed. For example, to ensure
497 + that, when adding new posts from *one particular feed*, FeedWordPress
498 + does *not* create new categories, and filters out any posts that don't
499 + match *at least one* of the categories that you have already defined,
500 + add the setting:
501 +
502 + unfamiliar categories: filter
503 +
504 + To ensure that FeedWordPress does *not* create new categories, but
505 + *will* still syndicate categories even if they don't match any of the
506 + pre-defined categories, add the following to the feed settings:
507 +
508 + unfamiliar categories: default
509 +
510 + If you changed the default behavior under Options --> Syndicated but
511 + want to ensure that FeedWordPress creates new categories for posts
512 + from one particular feed, add the setting:
513 +
514 + unfamiliar categories: create
515 +
516 + If the setting is anything other than `create`, `default`, or `filter`,
517 + FeedWordPress will ignore the setting and follow the default behavior
518 + that you specified under Options --> Syndication.
519 +
424 520 Template API
425 521 ------------
426 522 When activated, FeedWordPress makes the following functions available for use by
427 523 themes/templates:
@@ -433,9 +529,9 @@
433 529 * ``get_syndication_permalink()``: in a post context, returns the URI of
434 530 the permalink for this post *on the website it was syndicated from*
435 531
436 532 * ``the_syndication_permalink()``: in a post context, outputs the value
437 - returned by [``get_syndication_permalink()``][get_syndication_permalink]
533 + returned by ``get_syndication_permalink()``
438 534
439 535 * ``get_syndication_source_link()``: in a post context, returns the URI of
440 536 the front page (*not* the feed) of the website this post was syndicated
441 537 from
@@ -440,10 +536,9 @@
440 536 the front page (*not* the feed) of the website this post was syndicated
441 537 from
442 538
443 539 * ``the_syndication_source_link()``: in a post context, outputs the URI
444 - returned by
445 - [``get_syndication_source_link()``][get_syndication_source_link]
540 + returned by ``get_syndication_source_link()``
446 541
447 542 * ``get_syndication_source()``: in a post context, returns the
448 543 human-readable title of the website that a syndicated post was
449 544 syndicated from
@@ -448,15 +543,15 @@
448 543 human-readable title of the website that a syndicated post was
449 544 syndicated from
450 545
451 546 * ``the_syndication_source()``: in a post context, outputs the value
452 - returned by [``get_syndication_source()``][get_syndication_source]
547 + returned by ``get_syndication_source()``
453 548
454 549 * ``get_syndication_feed():`` in a post context, returns the URI of the
455 550 feed (*not* the front page) that this post was syndicated from
456 551
457 552 * ``the_syndication_feed()``: in a post context, outputs the value
458 - returned by [``get_syndication_feed()``][get_syndication_feed]
553 + returned by ``get_syndication_feed()``
459 554
460 555 * ``get_feed_meta($key)``: in a post context, returns the value, if any,
461 556 of the feed setting ``$key`` for the feed that this post was syndicated
462 557 from
@@ -462,21 +557,21 @@
462 557 from
463 558
464 559 By default, FeedWordPress also places a filter on the standard functions
465 560 ``get_permalink()`` and ``the_permalink()`` that substitutes the URI returned by
466 -[``get_syndication_permalink()``][get_syndication_permalink] for the URI
467 -generated by WordPress. This means that by default the permalinks listed on your
468 -website and in your newsfeed will link to the location of the posts on the
469 -source website, *not* to their location on your website. You can switch this
470 -behavior on or off at **Options --> Syndication** in the WordPress Dashboard.
561 +``get_syndication_permalink()`` for the URI generated by WordPress. This means
562 +that by default the permalinks listed on your website and in your newsfeed will
563 +link to the location of the posts on the source website, *not* to their location
564 +on your website. You can switch this behavior on or off at Options -->
565 +Syndication in the WordPress Dashboard.
471 566
472 -Plugin API
567 +### Plugin API ###
568 +
473 569 FeedWordPress creates five hooks through the WordPress plugin architecture that
474 570 you can plug in to using PHP WordPress plugins, to supplement ordinary
475 571 FeedWordPress behavior, or to filter posts according to criteria that you set.
476 572 The hooks are the action ``feedwordpress_update``, the action
477 -``feedwordpress_check_feed``, the action ``feedwordpress_update_complete``, the
573 +``feedwordpress_check_feed``, the action ``feedwordpress_update_complete``, the
478 574 filter ``syndicated_item``, the filter ``syndicated_post``, the action
479 575 ``post_syndicated_item``, and the action ``update_syndicated_item``.
480 576
481 577 For more information, see <http://projects.radgeek.com/feedwordpress/api>.
@@ -486,9 +581,8 @@
486 581 The FeedWordPress plugin is copyright (c) 2005 by Charles Johnson. It uses code
487 582 derived or translated from:
488 583
489 584 - [wp-rss-aggregate.php][] by [Kellan Elliot-McCrea](kellan@protest.net)
490 -- [MagpieRSS][] by [Kellan Elliot-McCrea](kellan@protest.net)
491 585 - [HTTP Navigator 2][] by [Keyvan Minoukadeh](keyvan@k1m.com)
492 586 - [Ultra-Liberal Feed Finder][] by [Mark Pilgrim](mark@diveintomark.org)
493 587
494 588 according to the terms of the [GNU General Public License][].
@@ -493,11 +587,11 @@
493 587
494 588 according to the terms of the [GNU General Public License][].
495 589
496 590 This program is free software; you can redistribute it and/or modify it under
497 -the terms of the [GNU General Public License][] as published by the Free
498 -Software Foundation; either version 2 of the License, or (at your option) any
499 -later version.
591 +the terms of the [GNU General Public License][] as published by the Free Software
592 +Foundation; either version 2 of the License, or (at your option) any later
593 +version.
500 594
501 595 This program is distributed in the hope that it will be useful, but WITHOUT ANY
502 596 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
503 597 PARTICULAR PURPOSE. See the GNU General Public License for more details.
@@ -502,10 +596,8 @@
502 596 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
503 597 PARTICULAR PURPOSE. See the GNU General Public License for more details.
504 598
505 599 [wp-rss-aggregate.php]: http://laughingmeme.org/archives/002203.html
506 - [MagpieRSS]: http://magpierss.sourceforge.net/
507 600 [HTTP Navigator 2]: http://www.keyvan.net/2004/11/16/http-navigator/
508 601 [Ultra-Liberal Feed Finder]: http://diveintomark.org/projects/feed_finder/
509 -
510 602 [GNU General Public License]: http://www.gnu.org/copyleft/gpl.html
511 603