OpenGuides::JSON(3pm)

📦
version 0.84 · 3 versions
, in debian bookworm, ubuntu jammy, ubuntu noble

💖✨ OpenGuides::JSON ✨💖

okay so this is the manual page for OpenGuides::JSON, aka the (3pm) one, aka the plugin that makes OpenGuides spit out JSON. bestie. it's giving "the wiki, but machine-readable" 🦋

and before we even get to the official sections, the page opens with a lil two-item teaser list, so here it is, no gatekeeping:

  • emit_json — Renders the given node as JSON
  • output_as_json — Renders the given arbitary data as JSON

(that's literally what it says, "arbitary" and all. we don't fix typos here, we honour them 🙈)

🎀 NAME 🎀

OpenGuides::JSON — An OpenGuides plugin to output JSON. that's it, that's the whole name. short. iconic. periodt 💅

🌸 DESCRIPTION 🌸

so like, this module does all the JSON stuff for OpenGuides. every last bit of it. it's not a standalone lil guy you install on its own — it's distributed and installed as part of the OpenGuides project, and it is not intended for independent installation.

and real talk: this documentation is probably only useful to OpenGuides developers. if that's not you, that's okay, you can still read it, i'm not gonna stop you 🫶

🌈 SYNOPSIS 🌈

here's the vibe, in code:

use Wiki::Toolkit;
use OpenGuides::Config;
use OpenGuides::JSON;

my $wiki = Wiki::Toolkit->new( ... );
my $config = OpenGuides::Config->new( file => "wiki.conf" );
my $json_writer = OpenGuides::JSON->new( wiki   => $wiki,
                                     config => $config );

# JSON version of a node.
print "Content-Type: application/javascript\n\n";
print $json_writer->emit_json( node => "Masala Zone, N1 0NU" );

# Ten most recent changes.
print "Content-Type: application/javascript\n";
print "Last-Modified: " . $self->json_timestamp( items => 10 ) . "\n\n";
print $json_writer->make_recentchanges_json( items => 10 );

look at her go. three use lines and suddenly you're emitting JSON 🧚

👑 METHODS 👑

the main character section. every method, right here, no skips.

🌟 new

my $json_writer = OpenGuides::JSON->new( wiki   => $wiki,
                                       config => $config );

wiki must be a Wiki::Toolkit object and config must be an OpenGuides::Config object. both arguments are mandatory, no vibes-only construction, sorry 💀

🌟 emit_json

$wiki->write_node( "Masala Zone, N1 0NU",
                 "Quick and tasty Indian food",
                 $checksum,
                 { comment  => "New page",
                   username => "Kake",
                   locale   => "Islington" }
);

print "Content-Type: application/javascript\n\n";
print $json_writer->emit_json( node => "Masala Zone, N1 0NU" );

Note: some of the fields emitted by the JSON generator are taken straight from the node metadata. and the form of that metadata is not mandated by Wiki::Toolkit — so your wiki application should make sure to store some or all of the following metadata when calling write_node:

  • postcode — The postcode or zip code of the place discussed by the node. Defaults to the empty string.
  • city — The name of the city that the node is in. If not supplied, then the value of default_city in the config object supplied to new, if available, otherwise the empty string.
  • country — The name of the country that the node is in. If not supplied, then the value of default_country in the config object supplied to new will be used, if available, otherwise the empty string.
  • username — An identifier for the person who made the latest edit to the node. This person will be listed as a contributor (Dublin Core). Defaults to empty string.
  • locale — The value of this can be a scalar or an arrayref, since some places have a plausible claim to being in more than one locale. Each of these is put in as a "Neighbourhood" attribute.
  • phone — Only one number supported at the moment. No validation.
  • website — No validation.
  • opening_hours_text — A freeform text field.

like. phone said "no validation" and website said "no validation" and honestly? same energy 🙈

🌟 json_maker

Returns a raw Wiki::Toolkit::Plugin::JSON object created with the values you invoked this module with. that's it. a lil object, made of your choices 💜

🌟 make_prefs_json

my $json_writer = OpenGuides::JSON->new( wiki   => $wiki,
                                         config => $config );
print $json_writer->make_prefs_json();

Retrieves the preferences from any stored preferences cookie, supplies defaults for any preferences not set, returns the result as JSON. cookie in, JSON out, slay 🍓

🌟 make_recentchanges_json

# Ten most recent changes.
print "Content-Type: application/javascript\n";
print "Last-Modified: " . $json_writer->json_timestamp( items => 10 ) . "\n\n";
print $json_writer->make_recentchanges_json( items => 10 );

# All the changes made by bob in the past week, ignoring minor edits.

my %args = (
             days               => 7,
             ignore_minor_edits => 1,
             filter_on_metadata => { username => "bob" },
           );

print "Content-Type: application/javascript\n";
print "Last-Modified: " . $json_writer->json_timestamp( %args ) . "\n\n";
print $json_writer->make_recentchanges_json( %args );

you can pull the ten most recent changes, or you can get specific — a time window, a ignore_minor_edits flag, and a filter_on_metadata hashref. bob's week, no minor edits. we see you, bob 👀

🌟 json_timestamp

print "Last-Modified: " . $json_writer->json_timestamp( %args ) . "\n\n";

Returns the timestamp of the RSS 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 make_recentchanges_json(). 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. caching, but make it polite ✨

🦋 SEE ALSO 🦋

💜 AUTHOR 💜

The OpenGuides Project (openguides-dev@openguides.org) 🫶

Copyright (C) 2003-2013 The OpenGuides Project. All Rights Reserved.

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

⭐ CREDITS ⭐

Code in this module is mostly pirated from OpenGuides::RDF, those authors deserve all the credit. Chris Prather did the pirating. "pirated" is their word, not mine, but honestly? iconic behaviour 🏴‍☠️💅

and that's the whole page bestie, you made it to the end 🎉

perl v5.32.0, dated 2021-01-30, and this manual page is OpenGuides::JSON(3pm) — mwah, go emit some JSON 💖

📦 where this page comes from