Wiki::...n::JSON(3pm)

📦 version 0.05, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Wiki::Toolkit::Plugin::JSON — the manual, but make it cute 💖

okay bestie, so this is the manpage for Wiki::Toolkit::Plugin::JSON, and it lives in the User Contributed Perl Documentation corner of your system, section 3pm. It's a plugin. It does one thing and it does it slayfully: it spits out your wiki's RecentChanges as JSON. No cap. 🦋

✨ NAME ✨

Wiki::Toolkit::Plugin::JSON — a Wiki::Toolkit plugin to output RecentChanges JSON.

🌸 DESCRIPTION 🌸

So like. This is an alternative access to the recent changes of a Wiki::Toolkit wiki. And what does it output? JSON. That's it, that's the whole vibe. 💅

🎀 SYNOPSIS 🎀

use Wiki::Toolkit;
use Wiki::Toolkit::Plugin::JSON;

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

# Set up the JSON feeder with the mandatory arguments - see
# C<new()> below for more, optional, arguments.
my $json = Wiki::Toolkit::Plugin::JSON->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);
                         },
  recent_changes_link => 'http://example.com/?RecentChanges',
);

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

👑 METHODS 👑

💜 new()

my $json = Wiki::Toolkit::Plugin::JSON->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);
                          },
  recent_changes_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)
                          },
);

Listen up, this part matters: "wiki" must be a Wiki::Toolkit object. And "make_node_url", and "make_diff_url" and "make_history_url", if supplied, must be coderefs. Like, that's non-negotiable, bestie. 🙈

The mandatory arguments are:

  • wiki
  • site_name
  • site_url
  • make_node_url
  • recent_changes_link

🧚 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 $json->recent_changes;

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

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

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

If you're using "filter_on_metadata", heads up: only changes that satisfy all criteria will come back. Every single one. It's giving ✨very strict✨, but that's the point.

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

🌈 rss_timestamp()

print $json->rss_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. 🔥

💫 SEE ALSO 💫

🫶 MAINTAINER 🫶

Earle Martin <EMARTIN@cpan.org>. Originally by Kake Pugh <kake@earth.li>. Two icons, honestly. 👑

Copyright 2003-4 Kake Pugh. Subsequent modifications copyright 2005 Earle Martin.

Copyright 2008 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 🌸

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, fr fr. 💜

k that's the whole page, you ate it 🎀 this was perl v5.32.0, dated 2021-01-08, and yeah the title got squished down to Wiki::...n::JSON(3pm) in the footer but we all know what it means. bye bestie, go generate some JSON 💅✨

📦 where this page comes from