• Template API
• Plugin API
• How feed information is stored
  • Special Feed Settings

Template API

When activated, FeedWordPress makes the following functions available for use by themes/templates:

• is_syndicated(): in a post context, returns TRUE if the post was syndicated from another website, or FALSE if it was originally posted here

• get_syndication_permalink(): in a post context, returns the URI of the permalink for this post on the website it was syndicated from

• the_syndication_permalink(): in a post context, outputs the value returned by get_syndication_permalink()

• get_syndication_source_link(): in a post context, returns the URI of the front page (not the feed) of the website this post was syndicated from

• the_syndication_source_link(): in a post context, outputs the URI returned by get_syndication_source_link()

• get_syndication_source(): in a post context, returns the human-readable title of the website that a syndicated post was syndicated from

• the_syndication_source(): in a post context, outputs the value returned by get_syndication_source()

• get_syndication_feed(): in a post context, returns the URI of the feed (not the front page) that this post was syndicated from

• the_syndication_feed(): in a post context, outputs the value returned by get_syndication_feed()

• get_feed_meta($key): in a post context, returns the value, if any, of the feed setting $key for the feed that this post was syndicated from

By default, FeedWordPress also places a filter on the standard functions get_permalink() and the_permalink() that substitutes the URI returned by get_syndication_permalink() for the URI generated by WordPress. This means that by default the permalinks listed on your website and in your newsfeed will link to the location of the posts on the source website, not to their location on your website. You can switch this behavior on or off at Options –> Syndication in the WordPress Dashboard.

Plugin API

FeedWordPress creates the following hooks using the WordPress plugin architecture. You can exploit these to write PHP plugins that alter FeedWordPress’s behavior or filter incoming posts:

• feedwordpress_update: an action invoked just before FeedWordPress begins to check one or more newsfeeds for updates. Hooked in functions receive as an argument the URI of the blog or newsfeed that FeedWordPress is updating.

• feedwordpress_check_feed: an action invoked just before FeedWordPress checks an individual newsfeed for updates. Hooked in functions receive as an argument an associative array of data about the feed. $feed['name'] contains the (human-readable) name of the newsfeed; $feed['url'] contains the URI about to be checked; etc.

• feedwordpress_update_complete: an action invoked when FeedWordPress has finished checking all of the feeds that it needs to check in the most recent update round. Hooked in functions receive as an argument an array containing the number of new posts added and the number of posts updated.

• syndicated_item: a filter applied to each item coming off the Atom/RSS newsfeed. Filter functions receive as an argument an associative array representing the contents of the item (in the format returned by MagpieRSS). They should return either the item–with any changes that you would like reflected when it is converted into a post for WordPress’s database–or NULL. If NULL is returned, FeedWordPress will filter this item out and skip ahead to the next one.

• syndicated_post: a filter applied to each potential post for the WordPress database. Hooked in functions receive as an argument an associative array representing the contents of the post. Filter functions should return either the post–with any changes you would like reflected when it is inserted into the database–or NULL. If NULL is returned, FeedWordPress will filter this item out and skip ahead to the next post.

• post_syndicated_item: an action that is invoked whenever FeedWordPress has completed inserting a new post into the WordPress database. Receives the numerical ID of the new post as an argument.

• update_syndicated_item: an action that is invoked whenever FeedWordPress has completed updating a previously existing post in the WordPress database. Receives the numerical ID of the updated post as an argument.

How feed information is stored

All of the information for a syndicated feed is stored in the WordPress Links database. Feeds in the category to be syndicated (by default, “Contributors”) use several fields of the standard WordPress Link record. Under ordinary circumstances you should never need to manage Contributor Links directly using the Links –> Manage Links interface: FeedWordPress provides a humane and much more useful interface for setting feed options under Links –> Syndicated. However, if you should need to access this information from a filter script or you want to hack the WordPress source or you just like nerding around without any clear purpose, here is how feed information is stored:

• The RSS URI (link_rss in the database table) is used to store the URI for the feed to be syndicated. (Note that this is not the same as the Link URI. The Link URI points to the human-readable front page of the website that the feed syndicates.)

• The Link URI (link_url in the database table) is used to store a URI to the human-readable front page (not the feed!) of the syndicated website. FeedWordPress automatically updates this URI using the URI that is reported by the newsfeed whenever it checks the feed for new posts, so if the page moves this will be reflected automatically on your Contributors links list.

• The Link Name (link_name in the database table) is used to store the title of the syndicated website. By default, FeedWordPress automatically updates the name of the link whenever it checks for new posts, using the title that the newsfeed reports (so that if a Contributor changes the title of her website, this is reflected automatically on your Contributors links list). This behavior can be turned off for all feeds through the settings in Options –> Syndication. The default behavior can be overridden for specific feeds using the feed setting hardcode name

• The Short Description (link_description in the database table) is used to store the tagline of the syndicated website. By default, FeedWordPress automatically updates the description whenever it checks for new posts, using the tagline or description that the newsfeed reports (so that if a Contributor changes the tagline of her website, this is reflected automatically on your Contributors links list). This behavior can be turned off for all feeds through the settings in Options –> Syndication. The default behavior can be overridden for specific feeds using the feed setting hardcode description.

• The Link Notes (link_notes in the database table) are used to store a collection of manually-encoded and automatically-generated settings that apply to this feed. The format of settings in Link Notes is:

  key1: value1
  key2: value2
  feed/key1: value1
  feed/key2: value2
  

  And so on. Values that are prefixed by ‘feed/’ are automatically generated from feed data every time the feed syndicated by this link is checked for updates. Values without the prefix are set manually by the user.

  Values are encoded using the PHP function addcslashes() to preserve special characters in the value (such as the newline character, \n) without wreaking havoc on the parser. So, for example, when the cats setting stores a newline-separated list of categories, the line added to the Link notes field is a single line such as this:

  cats: computers\nweb
  

  Where \n is the literal strong backslash-n, not a newline. When FeedWordPress retrieves the setting for internal use or for a plugin or template, however, it will unescape the string using stripcslashes, so that your script will see the list as separated by actual newlines, not the \n escape sequence.

Special Feed Settings

Not all feed settings are only for templates. Some affect how FeedWordPress processes posts from that feed. Currently, the settings with special effects on FeedWordPress are cats, hardcode name, hardcode description, hardcode categories, post status, comment status, ping status, unfamiliar author, and unfamiliar categories. If you are hacking around with filters or with the FeedWordPress source, and need to deal directly with feed settings from a program, here is what these special settings mean:

• cats: a list, with elements separated by colons (’:') or escaped newlines (’\n’), of default categories to be applied to any post coming from this feed. So, for example, a this line in its Notes section:

  cats: computers\nweb
  

  … will make FeedWordPress place any posts syndicated from that feed in the “computers” and “web” categories. Note that by default, FeedWordPress will place them in those categories in addition to any categories that the author of the post put them in on her own website. If you want to place posts from a feed only in the categories you explicitly set, then you should use the cats setting together with the unfamiliar categories setting. (See Categories and unfamiliar categories below for the nitty-gritty.) Support for colon-separated lists is included to maintain backward compatibility with previous versions of FeedWordPress, but colon-separated lists will be automatically converted to newline-separated lists and support for colon-separated lists will be dropped in future versions.

• hardcode name: (yes|no)

  By default, FeedWordPress updates the value of the Link Name field automatically to reflect the title that is reported by a syndicated feed–so that if one of your contributors changes the title of her website, the change will be reflected on your Contributors list after the next update. If you want to stop this behavior (so that you can set the title of a Contributor link manually — e.g. so that you can use an abbreviated form for reasons of space), you can change the default behavior for all feeds using the settings in Options –> Syndication. If you want to override the default behavior for only one feed, you can use the hardcode name feed setting. If FeedWordPress updates the title of all feeds by default, but you wish to use a manually-set title for one particular feed, you can add a line like this to the Link Notes section of the feed that you want to manually set the title for:

  hardcode name: yes
  

  Similarly, if FeedWordPress uses your manually-entered titles for all feeds by default, but you wish to use an automatically updated title for one particular feed, you can add a line like this to the Link Notes section of the feed that you want to manually set the title for:

  hardcode name: no
  

  If hardcode name is absent, or set to a value other than yes or no, FeedWordPress will follow the default behavior set under Options –> Syndication.

• hardcode description: (yes|no)

  By default, FeedWordPress updates the value of the Link Description field automatically to reflect the tagline or description that is reported by a syndicated feed–so that if one of your contributors changes the tagline for her website, the change will be reflected on your Contributors list after the next update. If you want to stop this behavior (so that you can set the tagline of a Contributor link manually – e.g. so that you can use it to provide information of another sort or use an abbreviated form for reasons of space), you can change the default behavior for all feeds using the settings in Options –> Syndication. If you want to override the default behavior for only one feed, you can use the hardcode description feed setting. If FeedWordPress updates the description of all feeds by default, but you wish to use a manually-set description for one particular feed, you can add a line like this to the Link Notes section of that particular feed:

  hardcode description: yes
  

  Similarly, if FeedWordPress uses your manually-entered descriptions for all feeds by default, but you wish to use an automatically updated description for one particular feed, you can add a line like this to the Link Notes section of that particular feed:

  hardcode description: no
  

  If hardcode description is absent, or set to a value other than yes or no, FeedWordPress will follow the default behavior set under Options –> Syndication.

• hardcode url: (yes|no)

  By default, FeedWordPress updates the value of the Link URI field automatically to reflect the link to the front page of the website you are syndicating, as reported by the syndicated feed–so that if one of your contributors changes the front page of her website (from http://www.zyx.com/blog/ to http://www.zyx.com/, say), the change will be reflected on your Contributors list after the next update. If you want to stop this behavior (so that you can set the human-readable URI that a Contributor link points to manually), you can change the default behavior for all feeds using the settings in Options –> Syndication. If you want to override the default behavior for only one feed, you can use the hardcode url feed setting. If FeedWordPress updates the human-readable URI of all feeds by default, but you wish to use a manually-set URI for one particular feed, you can add a line like this to the Link Notes section of that particular feed:

  hardcode url: yes
  

  Similarly, if FeedWordPress uses your manually-entered URIs for all feeds by default, but you wish to use an automatically updated URI for one particular feed, you can add a line like this to the Link Notes section of that particular feed:

  hardcode url: no
  

  If hardcode url is absent, or set to a value other than yes or no, FeedWordPress will follow the default behavior set under Options –> Syndication.

• hardcode categories: (yes|no)

  This setting has been deprecated. If set to yes it is now treated as equivalent to unfamiliar categories: default.

• post status: (publish|draft|private)

  By default, FeedWordPress sets all new syndicated posts to be published immediately. If you want syndicated posts to have some other status (for example, to hold them as drafts for moderation, or to hold them as private posts), you can change the default behavior using Options –> Syndication. If you want to override the default post status for syndicated posts from one particular feed, you can do so using the post status feed setting. So, for example, if you have FeedWordPress set to publish new syndicated posts immediately, but you want posts from one particular feed to be put into the drafts pile for moderation, you can do so by placing the following line in the Link Notes section of that feed’s Contributor link:

  post status: draft
  

• comment status: (open|closed)

  By default, FeedWordPress sets all new syndicated posts to be closed for comments–if users want to comment on posts then it’s often best for them to comment on the original website rather than your syndication site. But if you want syndicated posts to be open for comments, you can change the default behavior for all syndicated posts using the settings in Options –> Syndication. If you want to override the default comment status for one particular feed, you can do so using the comment status feed setting. So, for example, if you have FeedWordPress set not to open up new syndicated posts for comments, but you want posts from one particular feed to be opened for comments, then you can do so by placing the following line in the Link Notes section of that feed’s Contributor link:

  comment status: open
  

• ping status: (open|closed)

  By default, FeedWordPress sets all new syndicated posts not to accept PingBack or TrackBack link notifications (”pings”). If you want syndicated posts on your syndication site to accept pings, you can change the default behavior for all syndicated posts using the settings in Options –> Syndication. If you want to override the default ping status for one particular feed, you can do so using the ping status feed setting. So, for example, if you have FeedWordPress set not to accept pings for new syndicated posts, but you want posts from one particular feed to accept pings, then you can do so by placing the following line in the Link Notes section of that feed’s Contributor link:

  ping status: open
  

• unfamiliar author: (create|default|filter)

  By default, FeedWordPress creates new author accounts whenever it finds a new post that is by an author whose name is not already in the WordPress database, and uses that account for this post and any future posts by an author of that name. FeedWordPress also allows you to attribute posts by unfamiliar authors to a default user account (currently, this means the System Administrator account), instead of creating a new author, or simply not to syndicate posts by unfamiliar authors (thus only syndicating posts by authors who are already in the database).

  Which of these FeedWordPress does by default can be set using the settings in Options –> Syndication. You can also override the default behavior for specific feeds by adding the unfamiliar author feed setting to the Link Notes section of a feed. For example, to ensure that FeedWordPress filters out posts by unfamiliar authors for one particular feed, add the setting:

  unfamiliar author: filter
  

  To ensure that FeedWordPress assigns posts by unfamiliar authors to the default user account instead of creating a new user account, add the setting:

  unfamiliar author: default
  

  If you changed the default behavior under Options –> Syndication but want to ensure that FeedWordPress creates new author accounts for unfamiliar authors on one specific feed, add the setting:

  unfamiliar author: create
  

  If the setting is anything other than create, default, or filter, FeedWordPress will ignore the setting and follow the default behavior that you specified under Options –> Syndication.

• unfamiliar categories: (create|default|filter)

  By default, FeedWordPress creates categories whenever it finds a new post that is placed in categories whose names are not already in the WordPress database. FeedWordPress allows you to change this behavior, so that it will not create new category names. It also allows you to choose whether or not posts must match at least one familiar category to be syndicated at all.

  Which of these FeedWordPress does by default can be set using the settings in Options –> Syndication. You can also override the default behavior for specific feeds by adding the unfamiliar categories feed setting to the Link Notes section of a feed. For example, to ensure that, when adding new posts from one particular feed, FeedWordPress does not create new categories, and filters out any posts that don’t match at least one of the categories that you have already defined, add the setting:

  unfamiliar categories: filter
  

  To ensure that FeedWordPress does not create new categories, but will still syndicate categories even if they don’t match any of the pre-defined categories, add the following to the feed settings:

  unfamiliar categories: default
  

  If you changed the default behavior under Options –> Syndication but want to ensure that FeedWordPress creates new categories for posts from one particular feed, add the setting:

  unfamiliar categories: create
  

  If the setting is anything other than create, default, or filter, FeedWordPress will ignore the setting and follow the default behavior that you specified under Options –> Syndication.