feedwordpress / README.text

README.text in FeedWordPress 0.99, at README.text

508 lines 26.3 KB

Raw Download Zip

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