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