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

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

💖 Wiki::Toolkit::Feed::Atom — the manual, but make it cute ✨

okay bestie, so this is the page for Wiki::Toolkit::Feed::Atom(3pm) — a Perl module from the Wiki::Toolkit team, and honestly? it's giving "let my wiki have a feed" energy 🎀

🌸 NAME 🌸

Wiki::Toolkit::Feed::Atom — literally a Wiki::Toolkit plugin that outputs RecentChanges in Atom. that's the whole job. she does it well. 💅

🦋 DESCRIPTION 🦋

so basically this is an alternative way to get at the recent changes of a Wiki::Toolkit wiki. instead of RSS, she hands you the Atom Syndication Format, as described over at <http://www.atomenabled.org/developers/syndication/> ✨

and here's the tea: this module is a straight port of Wiki::Toolkit::Feed::RSS. like, same girl, different syndication format. no cap. 🔥

⭐ SYNOPSIS ⭐

here's the vibe, in code, exactly as written:

use Wiki::Toolkit;
use Wiki::Toolkit::Feed::Atom;

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

# Set up the RSS feeder with the mandatory arguments - see
# C<new()> below for more, optional, arguments.
my $atom = Wiki::Toolkit::Feed::Atom->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',
  atom_link => 'http://example.com/?action=rc;format=atom',
);

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

yes, that comment does say "RSS feeder" — we're keeping it real, that's what the original says 🫶

💜 METHODS 💜

🎀 "new()" 🎀

constructor time, bestie. look at her:

my $atom = Wiki::Toolkit::Feed::Atom->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',,
  atom_link => 'http://example.com/?action=rc;format=atom',

  # Optional arguments:
  site_description     => 'My wiki about my stuff',
  software_name        => $your_software_name,     # e.g. "Wiki::Toolkit"
  software_version     => $your_software_version,  # e.g. "0.73"
  software_homepage    => $your_software_homepage, # e.g. "http://search.cpan.org/dist/CGI-Wiki/"
  encoding             => 'UTF-8'
);

(that double comma after 'http://example.com/?RecentChanges' is canon, don't @ me 💀)

rules of the game, okay:

  • "wiki" must be a Wiki::Toolkit object. non-negotiable.
  • "make_node_url", if you supply it, must be a coderef.

the mandatory arguments are: 👑

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

the three optional arguments 🌸

  • software_name
  • software_version
  • software_homepage

are used to generate the "generator" part of the feed. cute, right?

the optional argument ✨

  • encoding

will be used to specify the character encoding in the feed. and if you don't set it? it defaults to the wiki store's encoding. she's got a fallback, she's prepared. 🎀

🍓 "recent_changes()" 🍓

the main character method, honestly. here she is in action:

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

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

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

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

# Personalise your feed further - consider only changes
# made by Fred to pages about bookshops.
print $atom->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. all of them. no partial matches, she's strict like that 🧚

Note: Many of the fields emitted by the Atom 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":

here's the metadata lowdown, bestie 👇

  • comment — a brief comment summarising the edit that has just been made; will be used in the summary 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 'No description given for change'.
  • 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 author for this item. Defaults to 'Anonymous'.

🦄 "generate_node_list_feed" 🦄

generate and return an Atom feed for a list of nodes. that's it, that's the whole deal. iconic behavior. ✨

🌈 "generate_node_name_distance_feed" 🌈

generates a very cut down atom feed — based just on the nodes, their locations (if given), and their distance from a reference location (if given). lowkey minimal, highkey useful. 💫

typically used on search feeds, iykyk.

👑 "feed_timestamp()" 👑

print $atom->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().

and like — 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. so yeah, she matters. 🫶

🌸 "parse_feed_timestamp" 🌸

takes a feed_timestamp and returns a Time::Piece object. that's the whole thing. short and slay. 💅

🎀 SEE ALSO 🎀

💖 MAINTAINER 💖

The Wiki::Toolkit team, http://www.wiki-toolkit.org/. they're the parents, they're keeping her fed and watered 🫶

Copyright 2006-2009 Earle Martin and the Wiki::Toolkit team. Copyright 2012 the Wiki::Toolkit team.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

🦋 THANKS 🦋

Kake Pugh for originally writing Wiki::Toolkit::Feed::RSS and indeed Wiki::Toolkit itself. absolute legend behaviour, we stan. 👑

and that's the page, bestie! ✨ this one's perl v5.32.0, dated 2021-01-04, from the docs that ship with Wiki::Toolkit::Feed::Atom — go forth and syndicate your recent changes responsibly 💅🎀🦋

📦 where this page comes from