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