PluginProbe
FeedWordPress / 0.96
FeedWordPress v0.96
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 +564 -163 0.91 → 0.96 View file →
@@ -1,9 +1,9 @@
1 1 FeedWordPress
2 2 =============
3 3
4 4 * Author: [Charles Johnson](http://www.radgeek.com/contact)
5 -* Version: 0.91
5 +* Version: 0.96
6 6 * Project URI: <http://projects.radgeek.com/feedwordpress>
7 7 * License: GPL. See License below for copyright jots and tittles.
8 8
9 9 Introduction
@@ -9,23 +9,24 @@
9 9 Introduction
10 10 ------------
11 11 FeedWordPress is an Atom/RSS aggregator for WordPress. It syndicates content
12 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][].
13 +several newsfeeds then you can WordPress's posts database and templating
14 +engine as the back-end of an aggregation ("planet") website. I originally
15 +developed it because I needed a more flexible replacement for [Planet][] to
16 +use at [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 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*.)
22 +configuration in mind. You'll need a working installation of [WordPress
23 +1.5][] and FTP or SFTP access to your web host. The ability to create cron
24 +jobs on your web host would be very helpful but it's not absolutely
25 +necessary. You *don't* need to tweak any plain-text configuration files and
26 +you *don't* need shell access to your web host to make it work. (Although, I
27 +should point out, web hosts that *don't* offer shell access are *bad web
28 +hosts*.)
28 29
29 30 [WordPress 1.5]: http://wordpress.org/development/2005/02/strayhorn/
30 31
31 32 Installation & Requirements
@@ -34,203 +35,601 @@
34 35 SFTP access to your web space. You'll probably also want to have either (1)
35 36 the ability to create cron jobs on your web host, or (2) a computer of your
36 37 own that has always-on Internet access.
37 38
38 -1. Install `feedwordpress.php` in your WordPress `plugins` directory and
39 - `update.php` in your WordPress `wp-content` directory.
39 +1. Install `feedwordpress.php` in your WordPress `plugins` directory
40 + and `update.php` in your WordPress `wp-content` directory.
40 41
41 42 2. (Optional) Upgrade the copy of MagpieRSS packaged with WordPress by
42 43 installing the new `rss-functions.php` (archived in
43 44 `OPTIONAL/wp-includes`) into your WordPress `wp-includes` directory.
45 + Upgrading MagpieRSS is necessary if you want to take advantage of
46 + support for multiple post categories, RSS enclosures, and multiple
47 + character encodings. (Note, however, that support for
48 + transliterating between character encodings is a very complex and
49 + iffy prospect in some PHP environments, so if you intend to use
50 + a lot of feeds with alternate encodings you should make sure that
51 + your installation of PHP is up-to-date and that you keep a copy of
52 + the old MagpieRSS around to compare results.)
44 53
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.)
54 +3. Log in to the WordPress Dashboard and activate the FeedWordPress
55 + plugin. Go to Options --> Syndication to set up initial settings for
56 + the syndication link category ("Contributors") by default and the
57 + RPC secret word (blank by default, but you should probably set it to
58 + something.)
49 59
50 60 4. Set up links for syndication from the WordPress Dashboard using
51 61 Links --> Syndicated or Links --> Import.
52 62
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.
63 +5. FeedWordPress is now *ready* to feed syndicated content into
64 + WordPress. In order for it to actually receive that content, either
65 + (1) have your contributors add WordPress's XML-RPC URI to their
66 + blog's list of URIs to ping when they update posts, (2) set up a
67 + cron job to check in on all the feeds on a regular basis, or (3)
68 + both. If you do (2), you can either set up a job to run `php
69 + update-feeds.php` on your web host, or set one up on any computer
70 + with always-on Internet access to request `update-feeds.php` over
71 + the web.
61 72
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
73 + If your copy of WordPress is installed at <http://www.zyx.com/blog>,
74 + and you set the secret word for XML-RPC pings to "foo", then your
75 + XML-RPC URI will be <http://www.zyx.com/blog/xmlrpc.php>, and the
76 + URI to request for `update-feeds.php` to update all feeds will be
66 77 <http://www.zyx.com/blog/wp-content/update-feeds.php?shibboleth=foo>
67 78
68 79 For detailed installation instructions, point your web browser to
69 80 <http://projects.radgeek.com/feedwordpress/install>.
70 81
71 -Feed Settings
82 +Basic Concepts
83 +--------------
84 +FeedWordPress is written as a plugin for [WordPress 1.5][]. It is designed
85 +to store all the data it needs within the WordPress database and to make
86 +that data easy to manage from within the WordPress Dashboard.
72 87
73 -Once you have your links configured and regular feed updates scheduled, you can
74 -mostly leave FeedWordPress to run on its own. If you need to add, remove, or
75 -change information for any contributors, you can do so from the WordPress
76 -Dashboard under Links --> Syndicated. If you want to distribute the labor of
77 -adding, updating, and managing feeds, you can use the WordPress login and access
78 -privileges system. Users with an access level of 5 or greater can add or modify
79 -syndicated links, and change syndication options.
88 +### Contributors / Newsfeeds ###
80 89
81 -All the information for a syndicated feed is managed through the WordPress Links
82 -database. Feeds in the category to be syndicated (by default, "Contributors")
83 -use several fields of the standard WordPress Link record:
90 +FeedWordPress uses the WordPress Links database to keep a list of the feeds
91 +from which it will syndicate content. WordPress allows you to place links in
92 +categories; FeedWordPress will treat all and only the links in one category
93 +(by default, this is a category named "Contributors"; you can change the
94 +category that FeedWordPress will use using Options --> Syndication).
84 95
85 -- The Link URI is used to store a URI to the front page (*not* the feed!)
86 - of the syndicated website.
96 +From WordPress's perspective, the list of Contributors are normal links, and
97 +they can be manipulated like other links through the WordPress Dashboard. If
98 +you need to add, remove, or change information for any contributors, you can
99 +do so easily under Links --> Syndicated. If you want to distribute the labor
100 +of adding, updating, and managing feeds, you can use the WordPress login and
101 +access privileges system. Users with an access level of 5 or greater can
102 +add, delete, and modify Contributors; users with an access level of 6 or
103 +greater can change syndication options.
87 104
105 +When FeedWordPress looks for new posts, it does so by retrieving one or all
106 +of the links from the Contributors category (depending on whether it has
107 +been told to scan for new posts on one or all of the feeds).
108 +
109 +__Feed settings:__ All of the information for a syndicated feed is stored in
110 +the WordPress Links database. Feeds in the category to be syndicated (by
111 +default, "Contributors") use several fields of the standard WordPress Link
112 +record:
113 +
114 +- The RSS URI is used to store the URI for the feed to be syndicated.
115 + (Note that this is *not* the same as the Link URI. The Link URI
116 + points to the human-readable *front page* of the website that the
117 + feed syndicates.)
118 +
119 +- The Link URI is used to store a URI to the human-readable front page
120 + (*not* the feed!) of the syndicated website. FeedWordPress
121 + automatically updates this URI using the URI that is reported by the
122 + newsfeed whenever it checks the feed for new posts, so if the page
123 + moves this will be reflected automatically on your Contributors
124 + links list.
125 +
88 126 - The Link Name is used to store the title of the syndicated website.
127 + By default, FeedWordPress automatically updates the name of the link
128 + whenever it checks for new posts, using the title that the
129 + newsfeed reports (so that if a Contributor changes the title of her
130 + website, this is reflected automatically on your Contributors links
131 + list). This behavior can be turned off for all feeds through the
132 + settings in Options --> Syndication. The default behavior can be
133 + overridden for specific feeds using the feed setting
134 + `hardcode name`.
89 135
90 136 - The Short Description is used to store the tagline of the syndicated
91 - website.
137 + website. By default, FeedWordPress automatically updates the
138 + description whenever it checks for new posts, using the tagline or
139 + description that the newsfeed reports (so that if a Contributor
140 + changes the tagline of her website, this is reflected automatically
141 + on your Contributors links list). his behavior can be turned off for
142 + all feeds through the settings in Options --> Syndication. The
143 + default behavior can be overridden for specific feeds using the feed
144 + setting `hardcode description`.
92 145
93 -- The RSS URI is used to store the URI for the feed to be syndicated.
146 +- The Link Notes are used to store a collection of manually-encoded
147 + and automatically-generated settings that apply to this feed. The
148 + format of settings in Link Notes is:
94 149
95 -- The Link Notes are used to store a collection of manually-encoded and
96 - automatically-generated settings that apply to this feed. The format of
97 - settings in Link Notes is:
98 -
99 150 key1: value1
100 151 key2: value2
101 - key3: value3
102 152 feed/key1: value1
103 153 feed/key2: value2
104 154
105 155 And so on. Values that are prefixed by 'feed/' are automatically
106 - generated from feed data every time the feed syndicated by this link is
107 - checked for updates. Values without the prefix are set manually by the
108 - user.
156 + generated from feed data every time the feed syndicated by this link
157 + is checked for updates. Values without the prefix are set manually
158 + by the user.
109 159
110 -Most settings in the Link Notes have no effect on FeedWordPress, but can be
111 -accessed from templates using the ``get_feed_meta()`` template function in a
112 -post context. For example, many aggregator sites use a "face" image for each
113 -feed to visually distinguish posts from different feeds. To implement a face
114 -feature, you could add a line like this to each feed's Link Notes section:
160 +The Link Notes section can be used to add, remove, and change custom feed
161 +settings. For example, if you want to *add* the feed setting for `unfamiliar
162 +author` with the value `filter`, you can do so by going to Links -->
163 +Syndicated, clicking the "Edit" link for the feed that you wish to add this
164 +setting for, and then adding the following, on a line by itself, to the Link
165 +Notes section:
115 166
116 - face: http://www.zyx.com/mugs/ugly
167 + unfamiliar author: filter
117 168
118 -The URI should be changed out for each feed to point to the appropriate image,
119 -of course. Then, to use the setting from within a template:
169 +To remove the setting, follow the same procedure, but find the line for the
170 +feed setting that you want to remove and remove it. To change the value,
171 +simply change the text that follows after the colon.
120 172
121 - // In a post context
122 - <?php $img = get_feed_meta('face'); if (strlen($img) > 0): ?>
123 - <img src="<?=$img?>" alt="" />
124 - <?php endif; ?>
173 +Most settings in the Link Notes have no effect on FeedWordPress, but you can
174 +use them to store information for templates to retrieve using the
175 +`get_feed_meta()` template function in a post context (see Template API
176 +below). For example, many aggregator sites use a "face" image for each feed
177 +to visually distinguish posts from different feeds. To implement a face
178 +feature, you could add something like this to each feed's Link Notes, on a
179 +line by itself:
125 180
126 -... which will display the image, if any, whose URI is set in the "face" setting
127 -for the feed that post comes from. If there is no "face" setting for a
128 -particular feed, ``get_feed_meta()`` will return an empty string and no image
129 -will be displayed.
181 + face: http://www.zyx.com/mugs/ugly
130 182
183 +The URI should be changed out for each feed to point to the appropriate
184 +image, of course. Then, to use the setting from within a template:
185 +
186 + // In a post context
187 + <?php $img = get_feed_meta('face'); if (strlen($img) > 0): ?>
188 + <img src="<?=$img?>" alt="" />
189 + <?php endif; ?>
190 +
191 +... which will display the image, if any, whose URI is set in the "face"
192 +setting for the feed that post comes from. If there is no "face" setting for
193 +a particular feed, ``get_feed_meta()`` will return an empty string and no
194 +image will be displayed.
195 +
131 196 Not all feed settings are only for templates. Some affect how FeedWordPress
132 -processes posts from that feed. Currently, the special settings are:
197 +processes posts from that feed. Currently, the settings with special effects
198 +on FeedWordPress are `cats`, `hardcode name`, `hardcode description`,
199 +`hardcode categories`, `post status`, `comment status`, `ping status`,
200 +`unfamiliar author`, and `unfamiliar categories`. For descriptions of their
201 +effects, see Special Feed Settings below.
133 202
134 -- `cats:` a colon-separated list of default categories for any post coming
135 - from this feed. So, for example, a this line in its Notes section:
203 +### Syndicated Posts ###
136 204
205 +Whenever FeedWordPress updates, it scans one or more of the feeds in its
206 +Contributors list and adds any new posts that it finds to the WordPress
207 +database. Syndicated posts are displayed on your WordPress pages like any
208 +other posts: they can be listed in archives by category, author, or date;
209 +they can be found with the search box; and they are included in the newsfeed
210 +of your blog.
211 +
212 +In your WordPress templates (Presentation --> Theme Editor) you can access
213 +special information about syndicated posts using functions provided by
214 +FeedWordPress, such as `is_syndicated()`, `the_syndication_source()`,
215 +`the_syndication_source_link()`, and `get_feed_meta()`. For example, here is
216 +the template code that I use (in a post context) to display both the
217 +author's name and the original source of the post in the templates for
218 +[Feminist Blogs][]:
219 +
220 + <cite class="feed">from <?php the_author_posts_link()?><?php
221 + if (is_syndicated() and (get_the_author() !== get_syndication_source())):
222 + echo ' @ <a href="'; the_syndication_source_link(); echo '">';
223 + the_syndication_source();
224 + echo '</a>';
225 + endif; ?></cite>
226 +
227 +For more information on template functions, see Template API below.
228 +
229 +### Categories ###
230 +
231 +WordPress allows for posts to be placed in *categories*. Each syndicated
232 +post that FeedWordPress adds to the WordPress database is placed into a set
233 +of categories. FeedWordPress gets the list of category names to use from two
234 +sources:
235 +
236 +1. Categories (or "tags") that the original author placed the post in
237 + on her blog
238 +
239 +2. Categories that you set explicitly for each feed using the `cats`
240 + feed setting. For example, if you wanted all the posts from Alas, A
241 + Blog to be placed in the "Pacific Northwest" category and the
242 + "Cartoonists" category (in addition to any categories that they were
243 + placed in on Alas, A Blog), you could do this by going to Links -->
244 + Syndicated, clicking the "Edit" link for Alas, A Blog, and adding
245 + the following line to the Link Notes section:
246 +
247 + cats: Pacific Northwest:Cartoonists
248 +
249 + (The colon separates one category name from the next.)
250 +
251 +Given the list of category names, FeedWordPress looks for categories in the
252 +WordPress database with the same name as either (1) the category name, or
253 +(2) one of the "aliases" listed in the category description.
254 +
255 +__Aliases:__ Different often authors use slightly different names for
256 +categories that mean the same thing (contributors to Feminist Blogs, for
257 +example, used categories including "Feminism", "feministy stuff", "Women's
258 +Issues", "Gender Issues", "Gender Equality", and so on). If you want
259 +FeedWordPress to treat one category name as a synonym for another, you can
260 +do so by creating an "alias" for the category. For example, to make
261 +FeedWordPress treat posts that are placed in the category "feministy stuff"
262 +as if they had been placed in the category "Feminism", go to Manage -->
263 +Categories, find the category "Feminism" and click the "Edit" link for it,
264 +and then add the following to the Description field, on a line by itself:
265 +
266 + a.k.a.: feministy stuff
267 +
268 +You can add as many aliases as you like. You can also add any other text
269 +that you like to the Description without interfering with FeedWordPress's
270 +ability to use the aliases. Each alias must be on a line by itself.
271 +
272 +__Unfamiliar categories:__ By default, if one of the category names that a
273 +newsfeed provides is unfamiliar -- that is, if there is not yet any category
274 +with that name (or with that name as an alias) in your WordPress database --
275 +then by default FeedWordPress will *automatically create* a new category
276 +with that name and place the current post in it. The default behavior can be
277 +changed, using either the global settings in Options --> Syndication or the
278 +`unfamiliar categories` feed setting (see Feed Settings above), so that
279 +unfamiliar categories will not be added to the database. If you choose to
280 +disable the creation of new categories, you can also choose whether or not
281 +FeedWordPress should syndicate posts that do not match *any* of the
282 +categories that are currently in the database.
283 +
284 +One of the uses of this feature is filtering posts by category: if you want
285 +to your blog to syndicate only the posts in one particular category from a
286 +feed that has several categories, you could do so by creating a category by
287 +that name, adding the new feed(s), and then adding the following line to the
288 +Link Notes section of the feed(s) that you want to filter:
289 +
290 + unfamiliar categories: filter
291 +
292 +Since only posts in categories that are in your database will be included,
293 +and only the category or categories that you wanted posts from has been
294 +added to your database, this will filter out all the posts that aren't in
295 +the category or categories that you defined ahead of time. (Similarly, you
296 +could set up FeedWordPress so that *all* the feeds are filtered by author by
297 +creating the set of users named after the authors you want to syndicate, and
298 +then setting the default behavior for *all* feeds at Options -->
299 +Syndication).
300 +
301 +If you need a category filter with more complex logic, you can always create
302 +a `syndicated_item` filter in PHP (see Plugin API below) that manipulates
303 +the `['categories']` array of a syndicated item.
304 +
305 +### Authors ###
306 +
307 +Most newsfeeds include information about the author of the items on them.
308 +(If a feed doesn't, then FeedWordPress will create an author's name based on
309 +the title of the feed from which the item was taken.) This information is
310 +used to determine the WordPress user that the post will be attributed to.
311 +Given the name of the author, FeedWordPress looks for authors in the
312 +WordPress database with the same name as either (1) their login, (2) their
313 +first name, (3) their nickname, (4) their full name, or (5) one of the
314 +"aliases" listed in the user's profile.
315 +
316 +__Aliases:__ If there is an author who posts under more than one name (for
317 +example, one of our contributors at [Feminist Blogs][] posts on several
318 +different blogs, sometimes using her full name and sometimes using only her
319 +first name), then you can ensure that FeedWordPress will attribute those
320 +posts to the same author by creating "aliases" for the author. For example,
321 +to make FeedWordPress treat posts by "Joseph Cardinal Ratzinger" and posts
322 +by "Pope Benedict XVI" as having the same author, go to Users --> Authors &
323 +Users, click on the "Edit" link for Pope Benedict XVI, and add a line like
324 +this to the Profile text:
325 +
326 + a.k.a.: Joseph Cardinal Ratzinger
327 +
328 +You can add as many aliases as you like. You can also add any other text
329 +that you like to the Profile without interfering with FeedWordPress's
330 +ability to use the aliases. Each alias must be on a line by itself.
331 +
332 +__Unfamiliar authors:__ By default, if the author named by the newsfeed is
333 +unfamiliar -- that is, if there is no-one with that name registered in the
334 +WordPress author's database -- then by default FeedWordPress will
335 +automatically create a new user account with the given name and attribute
336 +the post to the new user. The default behavior can be changed, using either
337 +the global settings in Options --> Syndication or the `unfamiliar author`
338 +feed setting (see Feed Settings above), so that posts by unfamiliar authors
339 +will either be attributed to a default author (instead of creating a new
340 +user account to attribute them to), or filtered out and not syndicated at
341 +all.
342 +
343 +One of the uses of this feature is filtering posts by author: if you want to
344 +your blog to syndicate only the posts by one particular author from a feed
345 +that has several authors, you could do so by creating a user account with
346 +that author's name, adding the new feed(s), and then adding the following
347 +line to the Link Notes section of the feed(s) that you want to filter:
348 +
349 + unfamiliar author: filter
350 +
351 +Since only posts by authors that are in your database will be included, and
352 +only the author that you wanted posts from has been added to your database,
353 +this will filter out posts by anyone else on the feeds with that setting.
354 +(Similarly, you could set up FeedWordPress so that *all* the feeds are
355 +filtered by author by creating the set of users named after the authors you
356 +want to syndicate, and then setting the default behavior for *all* feeds at
357 +Options --> Syndication).
358 +
359 +If you need an author filter with more complex logic than this allows, you
360 +can always create a `syndicated_item` filter in PHP (see Plugin API below)
361 +that manipulates the `['author_name']` or `['dc']['creator']` elements of a
362 +syndicated item.
363 +
364 +Special Feed Settings
365 +---------------------
366 +Most feed settings (see Feed Settings above) have no effect on FeedWordPress
367 +itself, but can be useful because they can be accessed from templates using
368 +the `get_feed_meta()` template function in a post context (see Feed Settings
369 +above for an example). However, you can use some feed settings to affect how
370 +FeedWordPress will process posts from that particular feed. Currently, these
371 +special settings are:
372 +
373 +- `cats:` a colon-separated list of default categories for any post
374 + coming from this feed. So, for example, a this line in its Notes
375 + section:
376 +
137 377 cats: computers:web
138 378
139 - ... will make FeedWordPress place any posts syndicated from that feed in
140 - the "computers" and "web" categories (*in addition to*, not *instead of*
141 - any categories that are applied to the post in the feed)
379 + ... will make FeedWordPress place any posts syndicated from that
380 + feed in the "computers" and "web" categories. Note that by default,
381 + FeedWordPress will place them in those categories *in addition to*
382 + any categories that the author of the post put them in on her own
383 + website. If you want to place posts from a feed *only* in the
384 + categories you explicitly set, then you should use the `cats`
385 + setting together with the `unfamiliar categories` setting. (See
386 + Categories above and `unfamiliar categories` below for the
387 + nitty-gritty.)
142 388
143 389 - `hardcode name: (yes|no)`
144 390
145 - A yes/no setting. By default, FeedWordPress updates the value of the
146 - Link Name field automatically to reflect the title that is reported by a
147 - syndicated feed. (So, for example, if one of your contributors changes
148 - the title of her weblog, the change will be reflected on your
149 - Contributors list after the next update.) To manually set the Link Name
150 - and prevent your new name from being overridden by FeedWordPress (so as
151 - to, for example, use an abbreviated form of the site's title for reasons
152 - of space), change the Link Name to a title of your choosing and then add
153 - a line like this to the Link Notes section:
391 + By default, FeedWordPress updates the value of the Link Name field
392 + automatically to reflect the title that is reported by a syndicated
393 + feed--so that if one of your contributors changes the title of her
394 + website, the change will be reflected on your Contributors list
395 + after the next update. If you want to stop this behavior (so that
396 + you can set the title of a Contributor link manually -- e.g. so that
397 + you can use an abbreviated form for reasons of space), you can
398 + change the default behavior for *all* feeds using the settings in
399 + Options --> Syndication. If you want to override the default
400 + behavior for only *one* feed, you can use the `hardcode name` feed
401 + setting. If FeedWordPress updates the title of all feeds by default,
402 + but you wish to use a manually-set title for one particular feed,
403 + you can add a line like this to the Link Notes section of the feed
404 + that you want to manually set the title for:
154 405
155 406 hardcode name: yes
156 407
157 - If `hardcode name` is absent, or set to a value other than `yes`,
158 - FeedWordPress will take that as a 'no' and follow the default behavior.
408 + Similarly, if FeedWordPress uses your manually-entered titles for
409 + all feeds by default, but you wish to use an automatically updated
410 + title for one particular feed, you can add a line like this to the
411 + Link Notes section of the feed that you want to manually set the
412 + title for:
159 413
414 + hardcode name: no
415 +
416 + If `hardcode name` is absent, or set to a value other than `yes` or
417 + `no`, FeedWordPress will follow the default behavior set under
418 + Options --> Syndication.
419 +
160 420 - `hardcode description: (yes|no)`
161 421
162 - A yes/no setting. By default, FeedWordPress updates the value of the
163 - Link Description field automatically to reflect the tagline or
164 - description that is reported by a syndicated feed. To manually set the
165 - Link Description and prevent your new description from being overridden
166 - by FeedWordPress (so as to, for example, use an abbreviated form of the
167 - site's tagline for reasons of space), change the Link Description to a
168 - title of your choosing and then add a line like this to the Link Notes
169 - section:
422 + By default, FeedWordPress updates the value of the Link Description
423 + field automatically to reflect the tagline or description that is
424 + reported by a syndicated feed--so that if one of your contributors
425 + changes the tagline for her website, the change will be reflected on
426 + your Contributors list after the next update. If you want to stop
427 + this behavior (so that you can set the tagline of a Contributor link
428 + manually -- e.g. so that you can use it to provide information of
429 + another sort or use an abbreviated form for reasons of space), you
430 + can change the default behavior for *all* feeds using the settings
431 + in Options --> Syndication. If you want to override the default
432 + behavior for only *one* feed, you can use the `hardcode description`
433 + feed setting. If FeedWordPress updates the description of all feeds
434 + by default, but you wish to use a manually-set description for one
435 + particular feed, you can add a line like this to the Link Notes
436 + section of that particular feed:
437 +
438 + hardcode description: yes
170 439
171 - hardcode description: yes
440 + Similarly, if FeedWordPress uses your manually-entered descriptions
441 + for all feeds by default, but you wish to use an automatically
442 + updated description for one particular feed, you can add a line like
443 + this to the Link Notes section of that particular feed:
172 444
173 - If `hardcode description` is absent, or set to a value other than `yes`,
174 - FeedWordPress will take that as a 'no' and follow the default behavior.
445 + hardcode description: no
446 +
447 + If `hardcode description` is absent, or set to a value other than
448 + `yes` or `no`, FeedWordPress will follow the default behavior set
449 + under Options --> Syndication.
175 450
451 +- `hardcode url: (yes|no)`
452 +
453 + By default, FeedWordPress updates the value of the Link URI field
454 + automatically to reflect the link to the front page of the website
455 + you are syndicating, as reported by the syndicated feed--so that if
456 + one of your contributors changes the front page of her website (from
457 + <http://www.zyx.com/blog/> to <http://www.zyx.com/>, say), the
458 + change will be reflected on your Contributors list after the next
459 + update. If you want to stop this behavior (so that you can set the
460 + human-readable URI that a Contributor link points to manually), you
461 + can change the default behavior for *all* feeds using the settings
462 + in Options --> Syndication. If you want to override the default
463 + behavior for only *one* feed, you can use the `hardcode url` feed
464 + setting. If FeedWordPress updates the human-readable URI of all
465 + feeds by default, but you wish to use a manually-set URI for one
466 + particular feed, you can add a line like this to the Link Notes
467 + section of that particular feed:
468 +
469 + hardcode url: yes
470 +
471 + Similarly, if FeedWordPress uses your manually-entered URIs for all
472 + feeds by default, but you wish to use an automatically updated URI
473 + for one particular feed, you can add a line like this to the Link
474 + Notes section of that particular feed:
475 +
476 + hardcode url: no
477 +
478 + If `hardcode url` is absent, or set to a value other than `yes` or
479 + `no`, FeedWordPress will follow the default behavior set under
480 + Options --> Syndication.
481 +
176 482 - `hardcode categories: (yes|no)`
177 483
178 - A yes/no setting. FeedWordPress places each syndicated post in a set of
179 - categories within WordPress. It gets that list from two sources:
484 + **This setting has been deprecated.** If set to `yes` it is now
485 + treated as equivalent to `unfamiliar categories: default`. (See
486 + below.)
487 +
488 +- `post status: (publish|draft|private)`
489 +
490 + By default, FeedWordPress sets all new syndicated posts to be
491 + published immediately. If you want syndicated posts to have some
492 + other status (for example, to hold them as drafts for moderation, or
493 + to hold them as private posts), you can change the default behavior
494 + using Options --> Syndication. If you want to override the default
495 + post status for syndicated posts from *one particular feed*, you
496 + can do so using the `post status` feed setting. So, for example, if
497 + you have FeedWordPress set to publish new syndicated posts
498 + immediately, but you want posts from one particular feed to be put
499 + into the drafts pile for moderation, you can do so by placing the
500 + following line in the Link Notes section of that feed's Contributor
501 + link:
180 502
181 - 1. Categories that you set explicitly for each feed (see the `cats` setting above)
503 + post status: draft
504 +
505 +- `comment status: (open|closed)`
506 +
507 + By default, FeedWordPress sets all new syndicated posts to be
508 + closed for comments--if users want to comment on posts then it's
509 + often best for them to comment on the *original* website rather than
510 + your syndication site. But if you want syndicated posts to be open
511 + for comments, you can change the default behavior for all syndicated
512 + posts using the settings in Options --> Syndication. If you want to
513 + override the default comment status for *one particular feed*, you
514 + can do so using the `comment status` feed setting. So, for example,
515 + if you have FeedWordPress set not to open up new syndicated posts
516 + for comments, but you want posts from *one particular feed* to be
517 + opened for comments, then you can do so by placing the following
518 + line in the Link Notes section of that feed's Contributor link:
182 519
183 - 2. Categories that the original author placed the post in on her blog
520 + comment status: open
521 +
522 +- `ping status: (open|closed)`
523 +
524 + By default, FeedWordPress sets all new syndicated posts *not* to
525 + accept PingBack or TrackBack link notifications ("pings"). If you
526 + want syndicated posts on your syndication site to accept pings, you
527 + can change the default behavior for all syndicated posts using the
528 + settings in Options --> Syndication. If you want to override the
529 + default ping status for *one particular feed*, you can do so using
530 + the `ping status` feed setting. So, for example, if you have
531 + FeedWordPress set not to accept pings for new syndicated posts, but
532 + you want posts from *one particular feed* to accept pings, then you
533 + can do so by placing the following line in the Link Notes section of
534 + that feed's Contributor link:
535 +
536 + ping status: open
537 +
538 +- `unfamiliar authors: (create|default|filter)`
539 +
540 + By default, FeedWordPress creates new author accounts whenever it
541 + finds a new post that is by an author whose name is not already in
542 + the WordPress database, and uses that account for this post and any
543 + future posts by an author of that name. FeedWordPress also allows
544 + you to attribute posts by unfamiliar authors to a *default* user
545 + account (currently, this means the System Administrator account),
546 + *instead of* creating a new author, or simply not to syndicate posts
547 + by unfamiliar authors (thus only syndicating posts by authors who
548 + are already in the database).
549 +
550 + Which of these FeedWordPress does by default can be set using the
551 + settings in Options --> Syndication. You can also override the
552 + default behavior for specific feeds by adding the `unfamiliar
553 + author` feed setting to the Link Notes section of a feed. For
554 + example, to ensure that FeedWordPress filters out posts by
555 + unfamiliar authors for one particular feed, add the setting:
184 556
185 - If any of the categories on the list do not exist, they are created automatically.
557 + unfamiliar author: filter
186 558
187 - If you want the posts from a particular feed to be placed *only* in the
188 - categories that you set manually (see the `cats` setting above), and not
189 - in the categories that they are in on the Contributor's blog, then add
190 - a line like this to the Link Notes section:
559 + To ensure that FeedWordPress assigns posts by unfamiliar authors to
560 + the default user account instead of creating a new user account, add
561 + the setting:
191 562
192 - hardcode categories: yes
563 + unfamiliar author: default
193 564
194 - If `hardcode categories` is absent, or set to a value other than `yes`,
195 - FeedWordPress will take that as a 'no' and follow the default behavior.
565 + If you changed the default behavior under Options --> Syndication
566 + but want to ensure that FeedWordPress creates new author accounts
567 + for unfamiliar authors on one specific feed, add the setting:
568 +
569 + unfamiliar author: create
570 +
571 + If the setting is anything other than `create`, `default`, or
572 + `filter`, FeedWordPress will ignore the setting and follow the
573 + default behavior that you specified under Options --> Syndication.
196 574
197 -- `post status:` sets the default post status for posts from this feed
198 - This can be 'publish', 'draft', or 'private'. By default, it is set to
199 - 'publish' (syndicated posts go online immediately).
575 +- `unfamiliar categories: (create|default|filter)`
200 576
201 -- `comment status:` sets the default status for comments on posts
202 - syndicated from this feed. By default, all comments on syndicated posts
203 - are closed, but you can set it to 'open', 'closed', or 'registered_only'
204 - for particular feeds.
577 + By default, FeedWordPress creates categories whenever it finds a new
578 + post that is placed in categories whose names are not already in the
579 + WordPress database. FeedWordPress allows you to change this
580 + behavior, so that it will *not* create new category names. It also
581 + allows you to choose whether or not posts must match *at least one*
582 + familiar category to be syndicated at all.
205 583
206 -- `ping status:` sets the default status for receiving TrackBack and
207 - PingBack pings on posts syndicated from this feed. By default,
208 - syndicated posts are closed to pings, but you can set this to 'open' or
209 - 'closed' for particular feeds.
584 + Which of these FeedWordPress does by default can be set using the
585 + settings in Options --> Syndication. You can also override the
586 + default behavior for specific feeds by adding the `unfamiliar
587 + categories` feed setting to the Link Notes section of a feed. For
588 + example, to ensure that, when adding new posts from *one particular
589 + feed*, FeedWordPress does *not* create new categories, and filters
590 + out any posts that don't match *at least one* of the categories that
591 + you have already defined, add the setting:
592 +
593 + unfamiliar categories: filter
594 +
595 + To ensure that FeedWordPress does *not* create new categories, but
596 + *will* still syndicate categories even if they don't match any of
597 + the pre-defined categories, add the following to the feed settings:
598 +
599 + unfamiliar categories: default
600 +
601 + If you changed the default behavior under Options --> Syndication
602 + but want to ensure that FeedWordPress creates new categories for
603 + posts from one particular feed, add the setting:
604 +
605 + unfamiliar categories: create
210 606
607 + If the setting is anything other than `create`, `default`, or
608 + `filter`, FeedWordPress will ignore the setting and follow the
609 + default behavior that you specified under Options --> Syndication.
610 +
211 611 Template API
212 612 ------------
213 -When activated, FeedWordPress makes the following functions available for use by
214 -themes/templates:
613 +When activated, FeedWordPress makes the following functions available for
614 +use by themes/templates:
215 615
216 -* ``is_syndicated()``: in a post context, returns ``TRUE`` if the post was
217 - syndicated from another website, or ``FALSE`` if it was originally
218 - posted here
616 +* ``is_syndicated()``: in a post context, returns ``TRUE`` if the post
617 + was syndicated from another website, or ``FALSE`` if it was
618 + originally posted here
219 619
220 -* ``get_syndication_permalink()``: in a post context, returns the URI of
221 - the permalink for this post *on the website it was syndicated from*
620 +* ``get_syndication_permalink()``: in a post context, returns the URI
621 + of the permalink for this post *on the website it was syndicated from*
222 622
223 -* ``the_syndication_permalink()``: in a post context, outputs the value
224 - returned by ``get_syndication_permalink()``
623 +* ``the_syndication_permalink()``: in a post context, outputs the
624 + value returned by ``get_syndication_permalink()``
225 625
226 -* ``get_syndication_source_link()``: in a post context, returns the URI of
227 - the front page (*not* the feed) of the website this post was syndicated
228 - from
626 +* ``get_syndication_source_link()``: in a post context, returns the
627 + URI of the front page (*not* the feed) of the website this post was
628 + syndicated from
229 629
230 -* ``the_syndication_source_link()``: in a post context, outputs the URI
231 - returned by ``get_syndication_source_link()``
630 +* ``the_syndication_source_link()``: in a post context, outputs the
631 + URI returned by ``get_syndication_source_link()``
232 632
233 633 * ``get_syndication_source()``: in a post context, returns the
234 634 human-readable title of the website that a syndicated post was
235 635 syndicated from
@@ -237,57 +636,58 @@
237 636
238 637 * ``the_syndication_source()``: in a post context, outputs the value
239 638 returned by ``get_syndication_source()``
240 639
241 -* ``get_syndication_feed():`` in a post context, returns the URI of the
242 - feed (*not* the front page) that this post was syndicated from
640 +* ``get_syndication_feed():`` in a post context, returns the URI of
641 + the feed (*not* the front page) that this post was syndicated from
243 642
244 643 * ``the_syndication_feed()``: in a post context, outputs the value
245 644 returned by ``get_syndication_feed()``
246 645
247 -* ``get_feed_meta($key)``: in a post context, returns the value, if any,
248 - of the feed setting ``$key`` for the feed that this post was syndicated
249 - from
646 +* ``get_feed_meta($key)``: in a post context, returns the value, if
647 + any, of the feed setting ``$key`` for the feed that this post was
648 + syndicated from
250 649
251 650 By default, FeedWordPress also places a filter on the standard functions
252 -``get_permalink()`` and ``the_permalink()`` that substitutes the URI returned by
253 -``get_syndication_permalink()`` for the URI generated by WordPress. This means
254 -that by default the permalinks listed on your website and in your newsfeed will
255 -link to the location of the posts on the source website, *not* to their location
256 -on your website. You can switch this behavior on or off at Options -->
257 -Syndication in the WordPress Dashboard.
651 +``get_permalink()`` and ``the_permalink()`` that substitutes the URI
652 +returned by ``get_syndication_permalink()`` for the URI generated by
653 +WordPress. This means that by default the permalinks listed on your website
654 +and in your newsfeed will link to the location of the posts on the source
655 +website, *not* to their location on your website. You can switch this
656 +behavior on or off at Options --> Syndication in the WordPress Dashboard.
258 657
259 658 ### Plugin API ###
260 659
261 -FeedWordPress creates five hooks through the WordPress plugin architecture that
262 -you can plug in to using PHP WordPress plugins, to supplement ordinary
263 -FeedWordPress behavior, or to filter posts according to criteria that you set.
264 -The hooks are the action ``feedwordpress_update``, the action
265 -``feedwordpress_check_feed``, the action ``feedwordpress_update_complete``, the
266 -filter ``syndicated_item``, the filter ``syndicated_post``, the action
660 +FeedWordPress creates five hooks through the WordPress plugin architecture
661 +that you can plug in to using PHP WordPress plugins, to supplement ordinary
662 +FeedWordPress behavior, or to filter posts according to criteria that you
663 +set. The hooks are the action ``feedwordpress_update``, the action
664 +``feedwordpress_check_feed``, the action ``feedwordpress_update_complete``,
665 +the filter ``syndicated_item``, the filter ``syndicated_post``, the action
267 666 ``post_syndicated_item``, and the action ``update_syndicated_item``.
268 667
269 -For more information, see <http://projects.radgeek.com/feedwordpress/use>.
668 +For more information, see <http://projects.radgeek.com/feedwordpress/api>.
270 669
271 670 License
272 671 -------
273 -The FeedWordPress plugin is copyright (c) 2005 by Charles Johnson. It uses code
274 -derived or translated from:
672 +The FeedWordPress plugin is copyright (c) 2005 by Charles Johnson. It uses
673 +code derived or translated from:
275 674
276 -- [wp-rss-aggregate.php][] by [Kellan Elliot-McCrea](kellan@protest.net)
277 -- [HTTP Navigator 2][] by [Keyvan Minoukadeh](keyvan@k1m.com)
278 -- [Ultra-Liberal Feed Finder][] by [Mark Pilgrim](mark@diveintomark.org)
675 +- [wp-rss-aggregate.php][] by [Kellan Elliot-McCrea](mailto:kellan@protest.net)
676 +- [HTTP Navigator 2][] by [Keyvan Minoukadeh](mailto:keyvan@k1m.com)
677 +- [Ultra-Liberal Feed Finder][] by [Mark Pilgrim](mailto:mark@diveintomark.org)
279 678
280 679 according to the terms of the [GNU General Public License][].
281 680
282 -This program is free software; you can redistribute it and/or modify it under
283 -the terms of the [GNU General Public License][] as published by the Free Software
284 -Foundation; either version 2 of the License, or (at your option) any later
285 -version.
681 +This program is free software; you can redistribute it and/or modify it
682 +under the terms of the [GNU General Public License][] as published by the
683 +Free Software Foundation; either version 2 of the License, or (at your
684 +option) any later version.
286 685
287 -This program is distributed in the hope that it will be useful, but WITHOUT ANY
288 -WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
289 -PARTICULAR PURPOSE. See the GNU General Public License for more details.
686 +This program is distributed in the hope that it will be useful, but WITHOUT
687 +ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
688 +FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
689 +more details.
290 690
291 691 [wp-rss-aggregate.php]: http://laughingmeme.org/archives/002203.html
292 692 [HTTP Navigator 2]: http://www.keyvan.net/2004/11/16/http-navigator/
293 693 [Ultra-Liberal Feed Finder]: http://diveintomark.org/projects/feed_finder/