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