Wiki::...d::RSS(3pm)

📦
version 0.86 · 3 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

Wiki::Toolkit::Feed::RSS — bestie, this is the module that spits out RecentChanges RSS feeds for a Wiki::Toolkit wiki. That's it, that's the whole job, and it does it slayfully. (You're reading the Wiki::...d::RSS(3pm) man page rn, iykyk.)

✨ DESCRIPTION ✨

Okay so picture this: you've got a wiki, you want people to be able to subscribe to what's changing on it. This module is your alternative access to the recent changes of a Wiki::Toolkit wiki, and it outputs RSS as described by the ModWiki proposal at <http://www.usemod.com/cgi-bin/mb.pl?ModWiki>. Yes, that's a link from the before-times. It still counts. 💅

🎀 SYNOPSIS 🎀

  use Wiki::Toolkit;
  use Wiki::Toolkit::Feed::RSS;

  my $wiki = CGI::Wiki->new( ... );  # See perldoc Wiki::Toolkit

  # Set up the RSS feeder with the mandatory arguments - see
  # C<new()> below for more, optional, arguments.
  my $rss = Wiki::Toolkit::Feed::RSS->new(
    wiki                => $wiki,
    site_name           => 'My Wiki',
    site_url            => 'http://example.com/',
    make_node_url       => sub
                           {
                             my ($node_name, $version) = @_;
                             return 'http://example.com/?id=' . uri_escape($node_name) . ';version=' . uri_escape($version);
                           },
    html_equiv_link     => 'http://example.com/?RecentChanges',
    encoding            => 'UTF-8'
  );

  print "Content-type: application/xml\n\n";
  print $rss->recent_changes;

Like, look at it. It's giving setup. 🌸

🦋 METHODS 🦋

🌟 "new()" 🌟

  my $rss = Wiki::Toolkit::Feed::RSS->new(
    # Mandatory arguments:
    wiki                 => $wiki,
    site_name            => 'My Wiki',
    site_url             => 'http://example.com/',
    make_node_url        => sub
                            {
                              my ($node_name, $version) = @_;
                              return 'http://example.com/?id=' . uri_escape($node_name) . ';version=' . uri_escape($version);
                            },
    html_equiv_link  => 'http://example.com/?RecentChanges',

    # Optional arguments:
    site_description     => 'My wiki about my stuff',
    interwiki_identifier => 'MyWiki',
    make_diff_url        => sub
                            {
                              my $node_name = shift;
                              return 'http://example.com/?diff=' . uri_escape($node_name)
                            },
    make_history_url     => sub
                            {
                              my $node_name = shift;
                              return 'http://example.com/?hist=' . uri_escape($node_name)
                            },
    software_name        => $your_software_name,     # e.g. "CGI::Wiki"
    software_version     => $your_software_version,  # e.g. "0.73"
    software_homepage    => $your_software_homepage, # e.g. "http://search.cpan.org/dist/Wiki-Toolkit/"
  );

Type check time, bestie — "wiki" must be a Wiki::Toolkit object. And "make_node_url", and "make_diff_url" and "make_history_url", if supplied, must be coderefs. No vibes-based input, sorry. 🙈

The mandatory arguments are, and I cannot stress this enough, mandatory:

  • wiki
  • site_name
  • site_url
  • make_node_url
  • html_equiv_link or recent_changes_link

The three optional arguments

  • software_name
  • software_version
  • software_homepage

are used to generate DOAP (Description Of A Project — see <http://usefulinc.com/doap>) metadata for the feed to show what generated it. Cute, right? It's the feed announcing its own origin story. ✨

The optional argument

  • encoding

will be used to specify the character encoding in the feed. If not set, will default to the wiki store's encoding. Easy.

🌈 "recent_changes()" 🌈

  $wiki->write_node(
                     'About This Wiki',
                     'blah blah blah',
                         $checksum,
                         {
                           comment  => 'Stub page, please update!',
                           username => 'Fred',
                         }
  );

  print "Content-type: application/xml\n\n";
  print $rss->recent_changes;

  # Or get something other than the default of the latest 15 changes.
  print $rss->recent_changes( items => 50 );
  print $rss->recent_changes( days => 7 );

  # Or ignore minor edits.
  print $rss->recent_changes( ignore_minor_edits => 1 );

  # Personalise your feed further - consider only changes
  # made by Fred to pages about bookshops.
  print $rss->recent_changes(
             filter_on_metadata => {
                         username => 'Fred',
                         category => 'Bookshops',
                       },
              );

If you're using "filter_on_metadata", heads up: only changes satisfying all criteria will be returned. It's an AND situation, not an OR situation. 🫶

Note: Many of the fields emitted by the RSS generator are taken from the node metadata. The form of this metadata is not mandated by Wiki::Toolkit. Your wiki application should make sure to store some or all of the following metadata when calling "write_node":
  • comment — a brief comment summarising the edit that has just been made; will be used in the RDF description for this item. Defaults to the empty string.
  • username — an identifier for the person who made the edit; will be used as the Dublin Core contributor for this item, and also in the RDF description. Defaults to the empty string.
  • host — the hostname or IP address of the computer used to make the edit; if no username is supplied then this will be used as the Dublin Core contributor for this item. Defaults to the empty string.
  • major_change — true if the edit was a major edit and false if it was a minor edit; used for the importance of the item. Defaults to true (ie if "major_change" was not defined or was explicitly stored as "undef").

💜 "feed_timestamp()" 💜

  print $rss->feed_timestamp();

Returns the timestamp of the feed in POSIX::strftime style ("Tue, 29 Feb 2000 12:34:56 GMT"), which is equivalent to the timestamp of the most recent item in the feed. Takes the same arguments as recent_changes(). You will most likely need this to print a Last-Modified HTTP header so user-agents can determine whether they need to reload the feed or not. Very demure, very cache-friendly. 🎀

🧚 "generate_node_list_feed" 🧚

Generate and return an RSS feed for a list of nodes. That's literally the whole thing, it's an icon.

🍓 "generate_node_name_distance_feed" 🍓

Generate a very cut down rss feed, based just on the nodes, their locations (if given), and their distance from a reference location (if given).

Typically used on search feeds. 🔥

⭐ "feed_timestamp" ⭐

Generate the timestamp for the RSS, based on the newest node (if available). Will return a timestamp for now if no node dates are available.

🌸 "parse_feed_timestamp" 🌸

Take a feed_timestamp and return a Time::Piece object. Glow-up from timestamp string to actual object, we love to see it.

👑 SEE ALSO 👑

🫶 MAINTAINER 🫶

The Wiki::Toolkit project. Originally by Kake Pugh <kake@earth.li>. Respect the origin story, fr fr.

Copyright 2003-4 Kake Pugh. Copyright 2005 Earle Martin. Copyright 2006-2009 the Wiki::Toolkit team.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Slay, and also, legally binding. 💅

🌟 THANKS 🌟

The members of the Semantic Web Interest Group channel on irc.freenode.net, #swig, were very useful in the development of this module. Shoutout to the group chat that made it all happen. 😭💖

That's the whole page, bestie — no cap, nothing skipped. This manual page is from perl v5.32.0, dated 2021-01-04, and it's the Wiki::...d::RSS(3pm) page you just read cover to cover. Go forth and feed. 🌈✨

📦 where this page comes from