feedwordpress / README.text

README.text in FeedWordPress 0.98, at README.text

512 lines 26.2 KB

Raw Download Zip

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