feedwordpress / README.text

README.text in FeedWordPress 0.981, at README.text

514 lines 26.4 KB

Raw Download Zip

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