PluginProbe
FeedWordPress / 0.91
FeedWordPress v0.91
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 +180 -389 0.99 → 0.91 View file →
@@ -1,423 +1,215 @@
1 1 FeedWordPress
2 2 =============
3 3
4 -* Author: [Charles Johnson](http://radgeek.com/contact)
5 -* Version: 0.99
4 +* Author: [Charles Johnson](http://www.radgeek.com/contact)
5 +* Version: 0.91
6 6 * Project URI: <http://projects.radgeek.com/feedwordpress>
7 -* License: GPL 2. See License below for copyright jots and tittles.
7 +* License: GPL. See License below for copyright jots and tittles.
8 8
9 9 Introduction
10 10 ------------
11 -FeedWordPress is an Atom/RSS aggregator for the WordPress weblog software. It
12 -syndicates content from newsfeeds that you choose into your WordPress webblog;
13 -if you syndicate several newsfeeds then you can use WordPress's posts database
14 -and templating engine as the back-end of an aggregation ("planet") website. I
15 -originally developed it because I needed a more flexible replacement for
16 -[Planet][] to use at [Feminist Blogs][].
11 +FeedWordPress is an Atom/RSS aggregator for WordPress. It syndicates content
12 +from newsfeeds that you select into your WordPress blog; if you syndicate
13 +several newsfeeds then you can WordPress's posts database and templating engine
14 +as the back-end of an aggregation ("planet") website. I originally developed it
15 +because I needed a more flexible replacement for [Planet][] to use at
16 +[Feminist Blogs][].
17 17
18 18 [Planet]: http://www.planetplanet.org/ "Planet Planet"
19 19 [Feminist Blogs]: http://www.feministblogs.org/
20 20
21 21 FeedWordPress is designed with flexibility, ease of use, and ease of
22 -configuration in mind. You'll need a working installation of WordPress (version
23 -[2.3][], [2.2][], [2.1][], [2.0][] or [1.5][]), and also FTP or SFTP access to
24 -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*.)
22 +configuration in mind. You'll need a working installation of [WordPress 1.5][]
23 +and FTP or SFTP access to your web host. The ability to create cron jobs on your
24 +web host would be very helpful but it's not absolutely necessary. You *don't*
25 +need to tweak any plain-text configuration files and you *don't* need shell
26 +access to your web host to make it work. (Although, I should point out, web
27 +hosts that *don't* offer shell access are *bad web hosts*.)
29 28
30 - [2.3]: http://codex.wordpress.org/Version_2.3
31 - [2.2]: http://codex.wordpress.org/Version_2.2
32 - [2.1]: http://codex.wordpress.org/Version_2.1
33 - [2.0]: http://codex.wordpress.org/Version_2.0
34 - [1.5]: http://codex.wordpress.org/Version_1.5
29 + [WordPress 1.5]: http://wordpress.org/development/2005/02/strayhorn/
35 30
36 -Installation
37 -### Requirements ###
31 +Installation & Requirements
32 +---------------------------
33 +You'll need a website with WordPress 1.5 installed and configured and FTP or
34 +SFTP access to your web space. You'll probably also want to have either (1)
35 +the ability to create cron jobs on your web host, or (2) a computer of your
36 +own that has always-on Internet access.
38 37
39 -To use version 0.99 of FeedWordPress, you will need:
40 -
41 -1. an installed and configured copy of WordPress 2.3.x, 2.2.x, 2.1.x,
42 - 2.0.x, or 1.5.x. (FeedWordPress currently *will not work* with older
43 - versions of WordPress, or with WordPress MU.)
44 -
45 -2. FTP or SFTP access to your web host
46 -
47 -### Installation ###
48 -
49 -#### Upgrades ####
50 -
51 -To *upgrade* an existing installation of FeedWordPress to version 0.99:
52 -
53 -1. Download the FeedWordPress archive in zip or gzipped tar format and
54 - extract the files on your computer.
55 -
56 -2. If you are upgrading from version 0.98 or earlier, then you need to
57 - create a new directory named `feedwordpress` in the `wp-content/plugins`
58 - directory of your WordPress installation, and you also need to *delete*
59 - your existing `wp-content/update-feeds.php` and
60 - `wp-content/plugins/feedwordpress.php` files. The file structure for
61 - FeedWordPress has changed and the files from your old version will not
62 - be overwritten, which could cause conflicts if you leave them in place.
63 -
64 -3. Upload the new PHP files to `wp-content/plugins/feedwordpress`,
65 - overwriting any existing FeedWordPress files that are there. Also be
66 - sure to upgrade `wp-includes/rss.php` and
67 - `wp-includes/rss-functions.php` if you use the optional MagpieRSS
68 - upgrade, or don't use it yet but do want to syndicate Atom 1.0 feeds.
69 -
70 -3. If you are upgrading from version 0.96 or earlier, **immediately** log
71 - in to the WordPress Dashboard, and go to Options --> Syndicated. Follow
72 - the directions to launch the database upgrade procedure. The new
73 - versions of FeedWordPress incorporate some long-needed improvements, but
74 - old meta-data needs to be updated to prevent duplicate posts and other
75 - possible maladies. If you're upgrading an existing installation, updates
76 - and FeedWordPress template functions *will not work* until you've done
77 - the upgrade. Then take a coffee break while the upgrade runs. It should,
78 - hopefully, finish within a few minutes even on relatively large
79 - databases.
80 -
81 -4. If you are upgrading from version 0.98 or earlier, note that the old
82 - `update-feeds.php` has been eliminated in favor of a (hopefully) more
83 - humane method for automatic updating. If you used a cron job for
84 - scheduled updates, it will not work anymore, but there is another,
85 - simpler method which will. See [Setting Up Feed Updates][] below to get
86 - scheduled updates back on track.
87 -
88 -5. Enjoy your new installation of FeedWordPress.
89 -
90 -#### New Installations ####
91 -
92 -1. Download the FeedWordPress archive in zip or gzipped tar format and
93 - extract the files on your computer.
94 -
95 -2. Create a new directory named `feedwordpress` in the `wp-content/plugins`
96 - directory of your WordPress installation. Use an FTP or SFTP client to
97 - upload the contents of the `wp-content/plugins/feedwordpress` directory
98 - in the FeedWordPress archive to the new directory that you just created
99 - on your web host.
100 -
101 -3. (Optional) Upgrade the copy of MagpieRSS packaged with WordPress by
102 - installing the new `rss.php` and `rss-functions.php` (archived in
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
103 43 `OPTIONAL/wp-includes`) into your WordPress `wp-includes` directory.
104 - Upgrading MagpieRSS is necessary if you want to take advantage of
105 - support for Atom 1.0, multiple post categories, RSS enclosures, and
106 - multiple character encodings. (Note, however, that support for
107 - transliterating between character encodings is a very complex and
108 - iffy prospect in some PHP environments, so if you intend to use
109 - a lot of feeds with alternate encodings you should make sure that
110 - your installation of PHP is up-to-date and that you keep a copy of
111 - the old MagpieRSS around to compare results.)
112 44
113 -4. Log in to the WordPress Dashboard and activate the FeedWordPress
114 - plugin.
45 +3. Log in to the WordPress Dashboard and activate the FeedWordPress plugin.
46 + Go to Options --> Syndication to set up initial settings for the
47 + syndication link category ("Contributors") by default and the RPC secret
48 + word (blank by default, but you should probably set it to something.)
115 49
116 -5. While you're at the Dashboard, once the plugin is activated, you can
117 - go to **Syndication --> Options** and set (1) the link category that
118 - FeedWordPress will syndicate links from (by default, "Contributors"),
119 - and (2) whether FeedWordPress will use automatic updates or only
120 - manual updates.
50 +4. Set up links for syndication from the WordPress Dashboard using
51 + Links --> Syndicated or Links --> Import.
121 52
122 -5. Go to the main **Syndication** page to set up the list of sites that
123 - you want FeedWordPress to syndicate onto your blog. (If you have the
124 - feeds you want to aggregate in a service such as Bloglines,
125 - you may prefer to export them to an OPML file and use WordPress's
126 - **Blogroll --> Import Links** to import them into the contributors
127 - category.)
53 +5. FeedWordPress is now *ready* to feed syndicated content into WordPress.
54 + In order for it to actually receive that content, either (1) have your
55 + contributors add WordPress's XML-RPC URI to their blog's list of URIs
56 + to ping when they update posts, (2) set up a cron job to check in on all
57 + the feeds on a regular basis, or (3) both. If you do (2), you can either
58 + set up a job to run `php update-feeds.php` on your web host, or set one
59 + up on any computer with always-on Internet access to request
60 + `update-feeds.php` over the web.
61 +
62 + If your copy of WordPress is installed at <http://www.zyx.com/blog>, and
63 + you set the secret word for XML-RPC pings to "foo", then your XML-RPC
64 + URI will be <http://www.zyx.com/blog/xmlrpc.php>, and the URI to request
65 + for `update-feeds.php` to update all feeds will be
66 + <http://www.zyx.com/blog/wp-content/update-feeds.php?shibboleth=foo>
128 67
129 -#### Setting Up Feed Updates ####
68 +For detailed installation instructions, point your web browser to
69 +<http://projects.radgeek.com/feedwordpress/install>.
130 70
131 -FeedWordPress is now ready to accept posts from its syndication sources. The
132 -next thing to do is to make sure it knows *when* to go get them.
71 +Feed Settings
72 +-------------
133 73
134 -**N.B.:** If you are upgrading from version 0.981 or earlier of FeedWordPress,
135 -the system for checking for new posts has been overhauled, hopefully making it
136 -more humane, and also easier to use for people who do not have access to task
137 -scheduling tools such as `cron`. You will need to re-read this section and
138 -change your set-up accordingly.
74 +Once you have your links configured and regular feed updates scheduled, you can
75 +mostly leave FeedWordPress to run on its own. If you need to add, remove, or
76 +change information for any contributors, you can do so from the WordPress
77 +Dashboard under Links --> Syndicated. If you want to distribute the labor of
78 +adding, updating, and managing feeds, you can use the WordPress login and access
79 +privileges system. Users with an access level of 5 or greater can add or modify
80 +syndicated links, and change syndication options.
139 81
140 -FeedWordPress allows you to choose whether it will check for new posts
141 -automatically, or only when you manually request for it to check. By default,
142 -FeedWordPress opts for the **manual** option -- so that you can get your feeds
143 -set up properly before FeedWordPress begins importing new posts. If you want
144 -to use automatically scheduled updates, remember to enable them in
145 -**Syndication --> Options** after you finish setting up FeedWordPress.
82 +All the information for a syndicated feed is managed through the WordPress Links
83 +database. Feeds in the category to be syndicated (by default, "Contributors")
84 +use several fields of the standard WordPress Link record:
146 85
147 -##### Manual Feed Updates #####
86 +- The Link URI is used to store a URI to the front page (*not* the feed!)
87 + of the syndicated website.
148 88
149 -To manually check for new posts, log in to the WordPress Dashboard and go to the
150 -main page under **Syndication**. You can use the "Update feeds now" button to
151 -check for new posts on feeds that are due for a scheduled update, or use the
152 -checkboxes and "Update Checked Feeds" button to force FeedWordPress to check one
153 -or more specific feeds for new posts. FeedWordPress will check the selected
154 -feed or feeds for new posts, and import any new content available.
89 +- The Link Name is used to store the title of the syndicated website.
155 90
156 -##### Automatic Feed Updates #####
91 +- The Short Description is used to store the tagline of the syndicated
92 + website.
157 93
158 -If you choose an automatic update schedule, then FeedWordPress will
159 -automatically check for new posts based on a schedule you determine. When
160 -automatic updates are enabled, FeedWordPress will check for new posts when
161 -(1) at least ten minutes have passed since the last update, and (2) a viewer
162 -visits your FeedWordPress-enabled blog. (If you want the interval of time to
163 -be shorter or longer, you can change the interval in the Dashboard under
164 -**Syndication --> Options**.)
94 +- The RSS URI is used to store the URI for the feed to be syndicated.
95 +
96 +- The Link Notes are used to store a collection of manually-encoded and
97 + automatically-generated settings that apply to this feed. The format of
98 + settings in Link Notes is:
99 +
100 + key1: value1
101 + key2: value2
102 + key3: value3
103 + feed/key1: value1
104 + feed/key2: value2
105 +
106 + And so on. Values that are prefixed by 'feed/' are automatically
107 + generated from feed data every time the feed syndicated by this link is
108 + checked for updates. Values without the prefix are set manually by the
109 + user.
165 110
166 -Note that this is not quite the same thing as precisely scheduled updating.
167 -If you get at least one viewer every ten minutes, then FeedWordPress will be
168 -regularly checking for new posts on schedule; if not, not. But for a relatively
169 -active aggregator blog this is probably close enough for government work.
111 +Most settings in the Link Notes have no effect on FeedWordPress, but can be
112 +accessed from templates using the ``get_feed_meta()`` template function in a
113 +post context. For example, many aggregator sites use a "face" image for each
114 +feed to visually distinguish posts from different feeds. To implement a face
115 +feature, you could add a line like this to each feed's Link Notes section:
170 116
171 -However, if you want to ensure regular updates, and you have access to a
172 -task-scheduling tool such as `cron`, you can use it to schedule regular
173 -checks for updates on a fixed schedule. For example, using `cron`, you can
174 -easily ensure that FeedWordPress checks for new posts regularly by adding the
175 -following line to your crontab, substituting the actual address of your
176 -WordPress installation for "http://www.zyx.com/blog/":
117 + face: http://www.zyx.com/mugs/ugly
177 118
178 - */15 * * * * curl http://www.zyx.com/blog/ > /dev/null
119 +The URI should be changed out for each feed to point to the appropriate image,
120 +of course. Then, to use the setting from within a template:
179 121
180 -If you don't have direct access to `cron` or a similar scheduling tool, you
181 -can use online tools such as [WebCron](http://www.webcron.org/?lang=en) to
182 -schedule a regular fetch of your blog's front page to much the same effect.
122 + // In a post context
123 + <?php $img = get_feed_meta('face'); if (strlen($img) > 0): ?>
124 + <img src="<?=$img?>" alt="" />
125 + <?php endif; ?>
183 126
184 -##### Feed Updates using XML-RPC #####
185 -
186 -FeedWordPress also allows syndicated blogs to notify you of updates using the
187 -XML-RPC "recently updated" pings (in the standard format accepted by
188 -Weblogs.com, Ping-O-Matic, Technorati, and other blogging services). Most
189 -blogging software allows users to add a URI to the list of URIs that get pinged
190 -with each new update -- see, for example, **Options --> Writing --> Update
191 -Services** in WordPress, or **Configuration --> Preferences --> Publicity /
192 -Remote Interfaces / TrackBack** in Movable Type. If you can get a contributor
193 -to add your XML-RPC URI to her list of update services to ping, then whenever
194 -she updates her blog, her blogging software will notify your FeedWordPress
195 -installation, and FeedWordPress will look up her feed to grab the new posts off
196 -of it. (If you have WordPress installed at <http://www.zyx.com/blog>, say, the
197 -URI for her to ping should be <http://www.zyx.com/blog/xmlrpc.php>).
198 -
199 -Basic Concepts
200 -FeedWordPress is written as a plugin for the WordPress weblog software. It is
201 -designed to store all the data it needs within the WordPress database and to
202 -make that data easy to manage from within the WordPress Dashboard.
203 -
204 -### Contributors / Newsfeeds ###
205 -
206 -FeedWordPress uses the WordPress Links database to keep a list of the feeds from
207 -which it will syndicate content. WordPress allows you to place links in
208 -categories; FeedWordPress will make use of all and only the links in one
209 -category (by default, this is a category named "Contributors"; you can change
210 -the category that FeedWordPress will use using **Options --> Syndication**).
211 -
212 -From WordPress's perspective, the list of Contributors are normal links, and
213 -they can be manipulated like other links through the WordPress Dashboard.
214 -However, FeedWordPress provides a nicer interface for adding, removing, or
215 -changing information for the Contributor Links from the WordPress Dashboard,
216 -under **Links --> Syndicated**.
217 -
218 -If you want to distribute the labor of adding, updating, and managing feeds
219 -between several people, you can use the WordPress login andaccess privileges
220 -system. Any users with an access level of 5 or greater can add, delete, and
221 -modify Contributors; users with an access level of 6 or greater can change
222 -syndication options.
223 -
224 -When FeedWordPress looks for new posts, it retrieves one or all of the links
225 -from the Contributors category (depending on whether it has been told to scan
226 -for new posts on one or all of the feeds), determines which of them should be
227 -polled for updates (based on how long it has been since the last time each feed
228 -was polled for updates), and then uses an HTTP conditional GET to check for
229 -updates at the "RSS URI" for each Link that it selects. Any new posts are added
230 -to the database, and old posts that have been updated since the last poll are
231 -updated to reflect the new version.
232 -
233 -__Feed settings:__ All of the information for a syndicated feed is stored in the
234 -WordPress Links database, and can be easily edited using an interface that
235 -FeedWordPress provides under **Links --> Syndicated**. (If you're curious about
236 -the technical details of how the information is stored, you can find out more
237 -under [API: How feed information is stored][].)
238 -
239 -You can use a feed's **Edit** link under **Links --> Syndicated** to affect how
240 -FeedWordPress prcesses posts from that feed. (Most of these options can either
241 -be set for *one particular feed* using **Links --> Syndicated --> Edit**, or set
242 -as the default for *all feeds* using **Options --> Syndication**.) The **Edit**
243 -link also allows you to set **Custom Feed Settings** for use in templates,
244 -through the use of the [`get_feed_meta()`][get_feed_meta] template function in a
245 -post context (see [Template API][]). For example, many aggregator sites use a
246 -"face" image for each feed to visually distinguish posts from different feeds.
247 -To implement a face feature, you could add a custom setting for each Contributor
248 -Link, with the key of "face" and a URI such as "http://www.zyx.com/mugs/ugly"
249 -for the value. (The URI should be changed out for each feed to point to the
250 -appropriate image, of course.) Then, to use the setting from within a template,
251 -add something like:
252 -
253 - // In a post context
254 - <?php $img = get_feed_meta('face'); if (strlen($img) > 0): ?>
255 - <img src="<?=$img?>" alt="" />
256 - <?php endif; ?>
257 -
258 127 ... which will display the image, if any, whose URI is set in the "face" setting
259 128 for the feed that post comes from. If there is no "face" setting for a
260 -particular feed, [`get_feed_meta()`][get_feed_meta] will return an empty string
261 -and no image will be displayed.
129 +particular feed, ``get_feed_meta()`` will return an empty string and no image
130 +will be displayed.
262 131
263 - [API: How feed information is stored]: http://projects.radgeek.com/feedwordpress/api#how-feed-information-is-stored
132 +Not all feed settings are only for templates. Some affect how FeedWordPress
133 +processes posts from that feed. Currently, the special settings are:
264 134
265 -### Syndicated Posts ###
135 +- `cats:` a colon-separated list of default categories for any post coming
136 + from this feed. So, for example, a this line in its Notes section:
266 137
267 -Whenever FeedWordPress updates, it scans one or more of the feeds in its
268 -Contributors list and adds any new posts that it finds to the WordPress
269 -database. Syndicated posts are displayed on your WordPress pages like any other
270 -posts: they can be listed in archives by category, author, or date; they can be
271 -found with the search box; and they are included in the newsfeed of your blog.
138 + cats: computers:web
272 139
273 -In your WordPress templates (**Presentation --> Theme Editor**) you can access
274 -special information about syndicated posts using [functions provided by
275 -FeedWordPress][Template API], such as [`is_syndicated()`][is_syndicated],
276 -[`the_syndication_source()`][the_syndication_source],
277 -[`the_syndication_source_link()`][the_syndication_source_link], and
278 -[`get_feed_meta()`][get_feed_meta]. For example, here is the template code that
279 -I use (in a post context) to display both the author's name and the original
280 -source of the post in the templates for [Feminist Blogs][]:
140 + ... will make FeedWordPress place any posts syndicated from that feed in
141 + the "computers" and "web" categories (*in addition to*, not *instead of*
142 + any categories that are applied to the post in the feed)
281 143
282 - <cite class="feed">from <?php the_author_posts_link()?><?php
283 - if (is_syndicated() and (get_the_author() !== get_syndication_source())):
284 - echo ' @ <a href="'; the_syndication_source_link(); echo '">';
285 - the_syndication_source();
286 - echo '</a>';
287 - endif; ?></cite>
144 +- `hardcode name: (yes|no)`
288 145
289 -For more information on template functions, see [Template API][].
146 + A yes/no setting. By default, FeedWordPress updates the value of the
147 + Link Name field automatically to reflect the title that is reported by a
148 + syndicated feed. (So, for example, if one of your contributors changes
149 + the title of her weblog, the change will be reflected on your
150 + Contributors list after the next update.) To manually set the Link Name
151 + and prevent your new name from being overridden by FeedWordPress (so as
152 + to, for example, use an abbreviated form of the site's title for reasons
153 + of space), change the Link Name to a title of your choosing and then add
154 + a line like this to the Link Notes section:
290 155
291 -### Categories ###
156 + hardcode name: yes
157 +
158 + If `hardcode name` is absent, or set to a value other than `yes`,
159 + FeedWordPress will take that as a 'no' and follow the default behavior.
292 160
293 -WordPress allows for posts to be placed in *categories*. Each syndicated post
294 -that FeedWordPress adds to the WordPress database is placed into a set of
295 -categories. FeedWordPress gets the list of category names to use from two
296 -sources:
161 +- `hardcode description: (yes|no)`
297 162
298 -1. Categories (or "tags") that the original author placed the post in on
299 - her blog
163 + A yes/no setting. By default, FeedWordPress updates the value of the
164 + Link Description field automatically to reflect the tagline or
165 + description that is reported by a syndicated feed. To manually set the
166 + Link Description and prevent your new description from being overridden
167 + by FeedWordPress (so as to, for example, use an abbreviated form of the
168 + site's tagline for reasons of space), change the Link Description to a
169 + title of your choosing and then add a line like this to the Link Notes
170 + section:
171 +
172 + hardcode description: yes
173 +
174 + If `hardcode description` is absent, or set to a value other than `yes`,
175 + FeedWordPress will take that as a 'no' and follow the default behavior.
300 176
301 -2. Categories that you set explicitly for each feed using the
302 - **Categories** checkbox under **Links --> Syndicated --> Edit**. For
303 - example, if you wanted all the posts from Alas, A Blog to be placed in
304 - the "Pacific Northwest" category and the "Cartoonists" category (*in
305 - addition to* any other categories that they were placed in on Alas, A
306 - Blog), you could do this by creating the categories, going to **Links
307 - --> Syndicated**, clicking the "Edit" link for Alas, A Blog, and
308 - checking those two categories under the checkbox captioned "Categories."
177 +- `hardcode categories: (yes|no)`
309 178
310 -Given the list of category names, FeedWordPress looks for categories in the
311 -WordPress database with the same name as either (1) the category name, or
312 -(2) one of the "aliases" listed in the category description.
179 + A yes/no setting. FeedWordPress places each syndicated post in a set of
180 + categories within WordPress. It gets that list from two sources:
181 +
182 + 1. Categories that you set explicitly for each feed (see the `cats` setting above)
183 +
184 + 2. Categories that the original author placed the post in on her blog
185 +
186 + If any of the categories on the list do not exist, they are created automatically.
187 +
188 + If you want the posts from a particular feed to be placed *only* in the
189 + categories that you set manually (see the `cats` setting above), and not
190 + in the categories that they are in on the Contributor's blog, then add
191 + a line like this to the Link Notes section:
192 +
193 + hardcode categories: yes
194 +
195 + If `hardcode categories` is absent, or set to a value other than `yes`,
196 + FeedWordPress will take that as a 'no' and follow the default behavior.
313 197
314 -__Aliases:__ Different often authors use slightly different names for categories
315 -that mean the same thing (contributors to Feminist Blogs, for example, used
316 -categories including "Feminism", "feministy stuff", "Women's Issues", "Gender
317 -Issues", "Gender Equality", and so on). If you want FeedWordPress to treat one
318 -category name as a synonym for another, you can do so by creating an "alias" for
319 -the category. For example, to make FeedWordPress treat posts that are placed in
320 -the category "feministy stuff" as if they had been placed in the category
321 -"Feminism", go to **Manage --> Categories**, find the category "Feminism" and
322 -click the "Edit" link for it, and then add the following to the Description
323 -field, on a line by itself:
198 +- `post status:` sets the default post status for posts from this feed
199 + This can be 'publish', 'draft', or 'private'. By default, it is set to
200 + 'publish' (syndicated posts go online immediately).
324 201
325 - a.k.a.: feministy stuff
202 +- `comment status:` sets the default status for comments on posts
203 + syndicated from this feed. By default, all comments on syndicated posts
204 + are closed, but you can set it to 'open', 'closed', or 'registered_only'
205 + for particular feeds.
326 206
327 -You can add as many aliases as you like. You can also add any other text that
328 -you like to the Description without interfering with FeedWordPress's ability to
329 -use the aliases. Each alias must be on a line by itself.
207 +- `ping status:` sets the default status for receiving TrackBack and
208 + PingBack pings on posts syndicated from this feed. By default,
209 + syndicated posts are closed to pings, but you can set this to 'open' or
210 + 'closed' for particular feeds.
330 211
331 -__Unfamiliar categories:__ If one of the category names that a newsfeed provides
332 -is *unfamiliar* -- that is, if there is not yet any category in your WordPress
333 -database that either has that name, or uses that name as an alias -- then by
334 -default FeedWordPress will *automatically create* a new category with that name
335 -and place the current post in it. The default behavior can be changed so that
336 -unfamiliar categories will *not* be added to the database, using the
337 -**Unfamiliar categories** setting, either for *all* feeds (under **Options -->
338 -Syndication**) or for *one particular feed* (under **Links --> Syndicated**).
339 -
340 -If you choose to disable the creation of new categories, either for all feeds or
341 -for one particular feed, then you can also choose whether or not FeedWordPress
342 -should syndicate posts that do not match *any* of the categories that are
343 -currently in the database. This allows you to do some simple filtering of posts
344 -by category: if you want to your blog to syndicate only the posts in one
345 -particular category from a feed that has several categories, you could do so by
346 -creating a category by that name, adding the new feed(s), and then setting
347 -**Unfamiliar categories** under **Links --> Syndicated --> Edit** to "don't
348 -create new categories and don't syndicate posts unless they match at least one
349 -familiar category".
350 -
351 -Since only posts in categories that are in your database will be included, and
352 -only the category or categories that you wanted posts from has been added to
353 -your database, this will filter out all the posts that aren't in the category or
354 -categories that you defined ahead of time. (Similarly, you could set up
355 -FeedWordPress so that *all* the feeds are filtered by author by creating the set
356 -of users named after the authors you want to syndicate, and then setting the
357 -default behavior for *all* feeds at **Options --> Syndication**).
358 -
359 -If you need a category filter with more complex logic, you can always create a
360 -`syndicated_item` filter in PHP (see [Plugin API][]) that manipulates the
361 -`['categories']` array of a syndicated item.
362 -
363 -### Authors ###
364 -
365 -Most newsfeeds include information about the author of the items on them.
366 -(If a feed doesn't, then FeedWordPress will create an author's name based on
367 -the title of the feed from which the item was taken.) This information is used
368 -to determine the WordPress user that the post will be attributed to. Given the
369 -name of the author, FeedWordPress looks for authors in the WordPress database
370 -with the same name as either (1) their login, (2) their display name, (3) their
371 -e-mail address (if given), or (4) one of the "aliases" listed in the
372 -user's profile.
373 -
374 -__Aliases:__ If there is an author who posts under more than one name (for
375 -example, one of our contributors at [Feminist Blogs][] posts on several
376 -different blogs, sometimes using her full name and sometimes using only her
377 -first name), then you can ensure that FeedWordPress will attribute those posts
378 -to the same author by creating "aliases" for the author. For example, to make
379 -FeedWordPress treat posts by "Joseph Cardinal Ratzinger" and posts by "Pope
380 -Benedict XVI" as having the same author, go to **Users --> Authors & Users**,
381 -click on the "Edit" link for Pope Benedict XVI, and add a line like this to the
382 -Profile text:
383 -
384 - a.k.a.: Joseph Cardinal Ratzinger
385 -
386 -You can add as many aliases as you like. You can also add any other text that
387 -you like to the Profile without interfering with FeedWordPress's ability to use
388 -the aliases. Each alias must be on a line by itself.
389 -
390 -__Unfamiliar authors:__ By default, if the author named by the newsfeed is
391 -unfamiliar -- that is, if there is no-one with that name registered in the
392 -WordPress author's database -- then by default FeedWordPress will automatically
393 -create a new user account with the given name and attribute the post to the new
394 -user. The default behavior can be changed, using either the global settings in
395 -**Options --> Syndication** or the [feed settings][] under **Links -->
396 -Syndicated --> Edit**, so that posts by unfamiliar authors will either be
397 -attributed to a default author (instead of creating a new user account to
398 -attribute them to), or filtered out and not syndicated at all.
399 -
400 -One of the uses of this feature is to filtering posts by author: if you want to
401 -your blog to syndicate only the posts by one particular author from a feed that
402 -has several authors, you could do so by creating a user account with that
403 -author's name, adding the new feed(s), and then setting **Unfamiliar authors**
404 -under **Links --> Syndicated --> Edit** to "don't syndicate the post". Since
405 -only posts by authors that are in your database will be included, and only the
406 -author that you wanted posts from has been added to your database, this will
407 -filter out posts by anyone else on the feeds with that setting. (Similarly, you
408 -could set up FeedWordPress so that *all* the feeds are filtered by author by
409 -creating the set of users named after the authors you want to syndicate, and
410 -then setting the default behavior for *all* feeds at **Options -->
411 -Syndication**).
412 -
413 -If you need an author filter with more complex logic than this allows, you can
414 -always create a `syndicated_item` filter in PHP (see [Plugin API][]) that
415 -manipulates the `['author_name']` or `['dc']['creator']` elements of a
416 -syndicated item.
417 -
418 212 Template API
419 213 ------------
420 214 When activated, FeedWordPress makes the following functions available for use by
421 215 themes/templates:
@@ -429,9 +221,9 @@
429 221 * ``get_syndication_permalink()``: in a post context, returns the URI of
430 222 the permalink for this post *on the website it was syndicated from*
431 223
432 224 * ``the_syndication_permalink()``: in a post context, outputs the value
433 - returned by [``get_syndication_permalink()``][get_syndication_permalink]
225 + returned by ``get_syndication_permalink()``
434 226
435 227 * ``get_syndication_source_link()``: in a post context, returns the URI of
436 228 the front page (*not* the feed) of the website this post was syndicated
437 229 from
@@ -436,10 +228,9 @@
436 228 the front page (*not* the feed) of the website this post was syndicated
437 229 from
438 230
439 231 * ``the_syndication_source_link()``: in a post context, outputs the URI
440 - returned by
441 - [``get_syndication_source_link()``][get_syndication_source_link]
232 + returned by ``get_syndication_source_link()``
442 233
443 234 * ``get_syndication_source()``: in a post context, returns the
444 235 human-readable title of the website that a syndicated post was
445 236 syndicated from
@@ -444,15 +235,15 @@
444 235 human-readable title of the website that a syndicated post was
445 236 syndicated from
446 237
447 238 * ``the_syndication_source()``: in a post context, outputs the value
448 - returned by [``get_syndication_source()``][get_syndication_source]
239 + returned by ``get_syndication_source()``
449 240
450 241 * ``get_syndication_feed():`` in a post context, returns the URI of the
451 242 feed (*not* the front page) that this post was syndicated from
452 243
453 244 * ``the_syndication_feed()``: in a post context, outputs the value
454 - returned by [``get_syndication_feed()``][get_syndication_feed]
245 + returned by ``get_syndication_feed()``
455 246
456 247 * ``get_feed_meta($key)``: in a post context, returns the value, if any,
457 248 of the feed setting ``$key`` for the feed that this post was syndicated
458 249 from
@@ -458,33 +249,32 @@
458 249 from
459 250
460 251 By default, FeedWordPress also places a filter on the standard functions
461 252 ``get_permalink()`` and ``the_permalink()`` that substitutes the URI returned by
462 -[``get_syndication_permalink()``][get_syndication_permalink] for the URI
463 -generated by WordPress. This means that by default the permalinks listed on your
464 -website and in your newsfeed will link to the location of the posts on the
465 -source website, *not* to their location on your website. You can switch this
466 -behavior on or off at **Options --> Syndication** in the WordPress Dashboard.
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.
467 258
468 -Plugin API
259 +### Plugin API ###
260 +
469 261 FeedWordPress creates five hooks through the WordPress plugin architecture that
470 262 you can plug in to using PHP WordPress plugins, to supplement ordinary
471 263 FeedWordPress behavior, or to filter posts according to criteria that you set.
472 264 The hooks are the action ``feedwordpress_update``, the action
473 -``feedwordpress_check_feed``, the action ``feedwordpress_update_complete``, the
265 +``feedwordpress_check_feed``, the action ``feedwordpress_update_complete``, the
474 266 filter ``syndicated_item``, the filter ``syndicated_post``, the action
475 267 ``post_syndicated_item``, and the action ``update_syndicated_item``.
476 268
477 -For more information, see <http://projects.radgeek.com/feedwordpress/api>.
269 +For more information, see <http://projects.radgeek.com/feedwordpress/use>.
478 270
479 271 License
480 272 -------
481 -The FeedWordPress plugin is copyright (c) 2005-2007 by Charles Johnson. It uses
482 -code derived or translated from:
273 +The FeedWordPress plugin is copyright (c) 2005 by Charles Johnson. It uses code
274 +derived or translated from:
483 275
484 276 - [wp-rss-aggregate.php][] by [Kellan Elliot-McCrea](kellan@protest.net)
485 -- [MagpieRSS][] by [Kellan Elliot-McCrea](kellan@protest.net)
486 277 - [HTTP Navigator 2][] by [Keyvan Minoukadeh](keyvan@k1m.com)
487 278 - [Ultra-Liberal Feed Finder][] by [Mark Pilgrim](mark@diveintomark.org)
488 279
489 280 according to the terms of the [GNU General Public License][].
@@ -489,11 +279,11 @@
489 279
490 280 according to the terms of the [GNU General Public License][].
491 281
492 282 This program is free software; you can redistribute it and/or modify it under
493 -the terms of the [GNU General Public License][] as published by the Free
494 -Software Foundation; either version 2 of the License, or (at your option) any
495 -later version.
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.
496 286
497 287 This program is distributed in the hope that it will be useful, but WITHOUT ANY
498 288 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
499 289 PARTICULAR PURPOSE. See the GNU General Public License for more details.
@@ -498,10 +288,8 @@
498 288 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
499 289 PARTICULAR PURPOSE. See the GNU General Public License for more details.
500 290
501 291 [wp-rss-aggregate.php]: http://laughingmeme.org/archives/002203.html
502 - [MagpieRSS]: http://magpierss.sourceforge.net/
503 292 [HTTP Navigator 2]: http://www.keyvan.net/2004/11/16/http-navigator/
504 293 [Ultra-Liberal Feed Finder]: http://diveintomark.org/projects/feed_finder/
505 -
506 294 [GNU General Public License]: http://www.gnu.org/copyleft/gpl.html
507 295