From Jimbojw.com

The WikiArticleFeeds Extension allows editors to author their own RSS and Atom feeds. It does this by interpreting article sections as feed items.

Note: This is the polar opposite of XFeed, which uses magpieRSS to embed existing RSS feeds into wiki pages.

It is released under The MIT License.

Compatibility

This extension requires:

• MediaWiki 1.6 or higher
• PHP 4, 5 or higher

Installation

To install this extension:

1. Download WikiArticleFeeds, and be sure to rename the downloaded file to WikiArticleFeeds.php.
2. Drop this script in $IP/extensions

   Note: $IP is your MediaWiki install dir.

3. Enable the extension by adding this line to your LocalSettings.php:

   require_once('extensions/WikiArticleFeeds.php');

That's it!

Configuration (optional)

The following instructions are totally optional, and are not required to get WikiArticleFeeds up and running.

Force Item Links Back to Page Section

By default, feed item links are determined by scanning for the first link in the rendered section text (see the section on automatic linking for details).

If you'd rather have item links always go back to the page and section from which the item was created, you may do so by adding the following to your LocalSettings.php:

$wgForceArticleFeedSectionLinks = true;

Note: This feature has been available since version 0.4

Usage

Once installed, you (or more importantly, editors of your wiki) may begin feeding pages immediately, no further system configuration is required.

What does it do?

Very simply, this extension permits authorship of real actual feeds. Until now the only feeds which were available from MediaWiki were those coming from Special:Recentchanges, or more recently article's history pages.

By marking portions of pages with custom tags, editors can signal where RSS/Atom content begins and ends. The extension takes care of the rest!

If an article contains a feed section, links titled 'rss' and 'atom' will appear in the Toolbox. Additionally, because the appropriate <meta> tags are supplied, your browser may show a feed icon in the address bar.

Note: In the Monobook (default) skin, the Toolbox is in the left-hand sidebar column, towards the bottom.

What does it not do?

This extension does not convert existing RSS/Atom feeds into wiki content. Quite the opposite.

If you're looking for an RSS-to-Wiki aggregator, check out XFeed - which will embed information from an RSS feed into a wiki page.

Interactive Quickstart

This section aims to get you up-to-speed quickly on how to create your own feeds.

First Feed - First Item

To put a feed in a page, enter something like the following:

<startFeed />

Description of my feed.

=== Item A ===

Here is the content for Item A.

--~~~~

<endFeed />

This creates a feed with the description "Description of my feed." The feed has a single item, titled "Item A", which contains the body text "Here is the content for Item A".

--[[User:Anon|Anon]] 08:42, 4 December 2006 (MST)

This is the recommended method syntax for creating feeds.

Adding Items

To add items to an existing feed (like the one in the previous example), simply add another wiki section between the startFeed and endFeed tags.

Continuing the previous example, you might enter:

<startFeed />

Description of my feed.

=== Item B ===

Brand New! I just made a new Item!

--~~~~

=== Item A ===

Here is the content for Item A.

--[[User:Anon|Anon]] 08:42, 4 December 2006 (MST)

<endFeed />

Note "Item B", which now appears above the old "Item A". You are encouraged to put new feed items at the top of the feed since this will most closely match the generated feed as well as reader expectations.

That's it! For more detailed information regarding the extension's functionality, see the Technical Details section.

FeedBurner Integration

As of version 0.5 and above, WikiArticleFeeds supports integration with FeedBurner.com.

Here are the steps to set up your feed to be managed by FeedBurner:

1. Create a feed by the normal means oulined in this document.
2. Log into FeedBurner.com (you may have to create an account).
3. Add a new feed to your account where the URL is that which is generated by WikiArticleFeeds (either the RSS or Atom feeds will do).
4. During the feed-adding process, FeedBurner will prompt you for a feed name to make the URL pretty. Enter what you like, but remember what it was as you'll need this shortly.
5. Finally, edit the article in your wiki that you've just "burned" and add the following:

   <feedBurner name="yourFeedsName" />

   Where yourFeedsName is the name you just specified.

Note that you can put the <feedBurner> tag anywhere in the article text you wish - though it's customary to put it right before the first <startFeed> tag.

Tagging and Filtering

As of version 0.6, WikiArticleFeeds supports tagging by way of either the >itemTags< tag or {{itemTags}} parser function.

To tag a feed item, insert either the <itemTags> tag, or the a call to the {{itemTags}} parser function somewhere between the opening header of the item (== Item Title ==) and the header of the next item.

For example, to mark an item about dogs and cats, you could do any of the following:

<itemTags>dogs, cats</itemTags>
{{#itemTags:dogs, cats}}
{{#itemTags:dogs|cats}}

Note: You may or may not need the leading '#' symbol in function declarations - this will depend on your installed MediaWiki version and current settings.

Tagging an item does nothing to the finished page other than add an HTML comment indicating the tag. Also, it will not affect the feed directly as this does not inject real actual RSS or Atom categories.

However, you can filter a feed by the item tags. For example consider the following URL:

http://jimbojw.com/wiki/index.php?title=Blog&action=feed

This will generate a feed of the page called Blog, containing all items therein. Now consider this variant:

http://jimbojw.com/wiki/index.php?title=Blog&action=feed&tags=mediawiki

This will also generate a feed, but it will only contain items which have been tagged as 'mediawiki' articles.

Technical Details

As opposed to the Interactive Quickstart, this section aims to give a deeper explanation of what's going on in the extension.

Basics

As previously discussed, for an article to be considered a feed, it must have a feed section.

To delimit a section use the <startFeed /><tt> and <tt><endFeed /> tags respectively. These tags are merely flags, and any attributes specified, or content inside the tags themselves will be ignored.

For example, the following segment contains two feed items.

<startFeed />
=== More Rain ===

Nope. Today it was rainy, again. Blah.

=== Not Sunny Today ===

Not quite rainy, just foggy, maybe it'll get better?

<endFeed />

Note that the choice of level-3 heading ('<tt>===') is purely coincidental. Any normal heading depth is acceptable - from '=' (1) to '======' (6) as long as they're consistent within the feed block.

Mixed Level Headings

Having a mix of level headings is ok, but only the sections highest level heading (lowest number) will be considered feed items.

For example, the following is perfectly legitimate:

<startFeed />
=== More Rain ===

Nope. Today it was rainy, again. Blah.

==== This is not a new Item ====

This text and the preceding heading both belong to the "More Rain" item.

=== Not Sunny Today ===

Not quite rainy, just foggy, maybe it'll get better?

<endFeed />

Attribution

To give credit to the author of an item, the only thing that's required is a single instance of the default signature - "~~~~". This will be converted by MediaWiki at submit-time into the fully expanded user name and date of submission.

WikiArticleFeeds is smart enough to know that if it sees such a construct, it should treat this as a declaration of the Author and Date.

Although attribution is certainly not required, you are strongly recommended to follow this convention. Externally, it aids the reader of the feed by providing more meta-data about the item. Internally, it permits aggregation to operate more smoothly (see next section).

Aggregation

WikiArticleFeeds can combine or aggregate feeds. For example, consider the following wiki markup:

<startFeed />
=== More Rain ===

Nope. Today it was rainy, again. Blah.

--[[User:Anon|Anon]] 08:42, 4 December 2006 (MST)

<endFeed />

...

<startFeed />
=== Not Sunny Today ===

Not quite rainy, just foggy, maybe it'll get better?

--[[User:Anon|Anon]] 09:56, 3 December 2006 (MST)

<endFeed />

When this page is converted into a single feed, both the "Not Sunny Today" and "More Rain" items will appear, in reverse chronological order (newest first).

Although this particular use case may not seem too exciting, it does permit the pulling together of feeds on separate pages via MediaWiki Template notation (also sometimes referred to as Transclusion).

For example, consider the following three articles:

Rainy Feed

<startFeed />
=== More Rain ===

Nope. Today it was rainy, again. Blah.

--[[User:Anon|Anon]] 08:42, 4 December 2006 (MST)

=== Not Sunny Today ===

Not quite rainy, just foggy, maybe it'll get better?

--[[User:Anon|Anon]] 09:56, 3 December 2006 (MST)

<endFeed />

Sunshiny Feed

<startFeed />
=== More Sunshiny ===

Just another beautiful day.

--[[User:Anon|Anon]] 06:37, 18 August 2006 (MST)

=== Hoping for more Sun ===

Hope it's nice out tomorrow, too cloudy today ...

--[[User:Anon|Anon]] 10:08, 14 August 2006 (MST)

<endFeed />

Aggregate Feed

== Rainy Feed ==

Contents of the Rainy Feed:
{{:Rainy Feed}}

== Sunshiny Feed ==

Contents of the Sunshiny Feed ==
{{:Sunshiny Feed}}

As you can imagine, rendering the article "Aggregate Feed" as an RSS or Atom feed will result in a combination of all items in both "Rainy Feed" and "Sunshiny Feed".

Automatic Linking

There are two options for automatically creating the feed's link URL. First, if there are no URLs, or the only URLs in the feed text itself are part of the attribution, then the feed URL will be simply a link to the item in the page.

Note: This behavior can be disabled by setting $wgForceArticleFeedSectionLinks to true in LocalSettings.php. See the installation section for details.

So for example, this feed's url:

== Some Item ==

Some blog text.

--[[User:Anon|Anon]] 10:08, 14 August 2006 (MST)

Would be equivalent to the wiki link "[[#Some Item]]".

The other method of auto-linking is based on non-attribution links. The first non-attribution link found in the feed text becomes the feed item URL.

So this example:

== Some Item ==

Checkout my new [[Main Page]] - it's great! (Oh, and while you're at it, check out the [[Announcements]]).

--[[User:Anon|Anon]] 10:08, 14 August 2006 (MST)

Would be equivalent to the wiki link "[[Main Page]]".

Comments

Leave a comment

or, read what others have said ...