OpenGuides(3pm)

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

💖 OpenGuides — the manual, but make it slay 💖

okay bestie, welcome to OpenGuides(3pm) — a Perl module from the User Contributed Perl Documentation section, and honestly? she's iconic. let's get into it 🫶

✨ NAME ✨

OpenGuides — a complete web application for managing a collaboratively-written guide to a city or town. no cap, that's literally what it is. 💅

🌸 DESCRIPTION 🌸

So the OpenGuides software gives you the framework for a collaboratively-written city guide. It's giving wiki, but — plot twist — it stores somewhat more structured data, which means you can annotate your wiki pages with stuff like category, location, and much more. ✨

It also comes with searching facilities, including the absolute banger that is "find me everything within a certain distance of this place". And every single page includes a link to a machine-readable (RDF) version of the page. every page. periodt. 💖

👑 METHODS 👑

new

my $config = OpenGuides::Config->new( file => "wiki.conf" );
my $guide = OpenGuides->new( config => $config );

that's the constructor, bestie. build your config, hand it over, boom — you have a guide. 🎀

wiki

An accessor. Returns the underlying Wiki::Toolkit object. 🦋

config

An accessor. Returns the underlying OpenGuides::Config object. ✨

locator

An accessor. Returns the underlying Wiki::Toolkit::Plugin::Locator::UK object. 🌈

differ

An accessor. Returns the underlying Wiki::Toolkit::Plugin::Diff object. 💜

display_node

# Print node to STDOUT.
$guide->display_node(
                        id      => "Calthorpe Arms",
                        version => 2,
                    );

# Or return output as a string (useful for writing tests).
$guide->display_node(
                        id            => "Calthorpe Arms",
                        return_output => 1,
                    );

# Return output as a string with HTTP headers omitted (for tests).
$guide->display_node(
                        id            => "Calthorpe Arms",
                        return_output => 1,
                        noheaders     => 1,
                    );

# Or return the hash of variables that will be passed to the template
# (not including those set additionally by OpenGuides::Template).
$guide->display_node(
                        id             => "Calthorpe Arms",
                        return_tt_vars => 1,
                    );

If you leave version out, she'll just assume you want the latest version. main character behaviour. 💅

Heads up bestie: if you pass the return_output parameter and your node is a redirecting node, this method will fake the redirect and return the output that will actually end up in the user's browser. If instead you want to see the HTTP headers that will be printed in order to perform the redirect, pass the intercept_redirect parameter as well. The intercept_redirect parameter has no effect if the node isn't a redirect, or if the return_output parameter is omitted. 😭

(At the moment, return_tt_vars acts as if the intercept_redirect parameter was passed. lowkey quirky of her, but okay.)

The noheaders parameter only takes effect if return_output is true and intercept_redirect is false or omitted. fr fr.

If you have specified the host_checker_module option in your wiki.conf, this method will attempt to call the <blacklisted_host> method of that module to determine whether the host requesting the node has been blacklisted. If this method returns true, then the blacklisted_host.tt template will be used to display an error message. 🚫

The blacklisted_host method will be passed a scalar containing the host's IP address. 🧚

display_random_page

$guide->display_random_page;

Displays a random page. chaotic. love that for us. 🎲

As with other methods, the return_output parameter can be used to return the output instead of printing it to STDOUT. You can also restrict it to a given category and/or locale by supplying appropriate parameters:

$guide->display_random_page(
                             category => "pubs",
                             locale   => "bermondsey",
                           );

The values of these parameters are case-insensitive. 💖

You can make sure this method never returns pages that are themselves categories and/or locales by setting random_page_omits_categories and/or random_page_omits_locales in your wiki.conf. ✨

display_edit_form

$guide->display_edit_form(
                           id => "Vivat Bacchus",
                           vars => \%vars,
                           content => $content,
                           metadata => \%metadata,
                           checksum => $checksum
                         );

Displays an edit form for the specified node. As with other methods, the return_output parameter can be used to return the output instead of printing it to STDOUT. 🦋

If this is to redisplay an existing edit, the content, metadata and checksum may be supplied in those arguments. 🌸

Extra template variables may be supplied in the vars argument. ✨

preview_edit

$guide->preview_edit(
                      id      => "Vivat Bacchus",
                      cgi_obj => $q,
                    );

Preview the edited version of the specified node. As with other methods, the return_output parameter can be used to return the output instead of printing it to STDOUT. 👀

display_prefs_form

$guide->display_prefs_form;

Displays a form that lets the user view and set their preferences. The return_output and return_tt_vars parameters can be used to return the output or template variables, instead of printing the output to STDOUT. The noheaders parameter can also be used in conjunction with return_output, if you wish to omit all HTTP headers. 🎀

display_recent_changes

$guide->display_recent_changes;

As with other methods, the return_output parameter can be used to return the output instead of printing it to STDOUT. 🔥

display_diffs

$guide->display_diffs(
                         id            => "Home Page",
                         version       => 6,
                         other_version => 5,
                     );

# Or return output as a string (useful for writing tests).
my $output = $guide->display_diffs(
                                      id            => "Home Page",
                                      version       => 6,
                                      other_version => 5,
                                      return_output => 1,
                                  );

# Or return the hash of variables that will be passed to the template
# (not including those set additionally by OpenGuides::Template).
my %vars = $guide->display_diffs(
                                    id             => "Home Page",
                                    version        => 6,
                                    other_version  => 5,
                                    return_tt_vars => 1,
                                );

the diff queen. she compares versions and she does it beautifully. 💜

find_within_distance

$guide->find_within_distance(
                                id => $node,
                                metres => $q->param("distance_in_metres")
                            );

yes, this is the "what's near me" one and it ate. 📍✨

$guide->show_backlinks( id => "Calthorpe Arms" );

As with other methods, parameters return_tt_vars and return_output can be used to return these things instead of printing the output to STDOUT. 🫶

show_index

# Show everything in Category: Pubs.
$guide->show_index(
                      cat => "pubs",
                  );

# Show all pubs in Holborn.
$guide->show_index(
                      cat => "pubs",
                      loc => "holborn",
                  );

# RDF version of things in Locale: Holborn.
$guide->show_index(
                      loc  => "Holborn",
                      format => "rdf",
                  );

# RSS / Atom version (recent changes style).
$guide->show_index(
                      loc    => "Holborn",
                      format => "rss",
                  );

# Or return output as a string (useful for writing tests).
$guide->show_index(
                      cat           => "pubs",
                      return_output => 1,
                  );

# Return output as a string with HTTP headers omitted (for tests).
$guide->show_index(
                      cat           => "pubs",
                      return_output => 1,
                      noheaders     => 1,
                  );

# Or return the template variables (again, useful for writing tests).
$guide->show_index(
                      cat            => "pubs",
                      format         => "map"
                      return_tt_vars => 1,
                  );

If neither cat or loc is supplied, then all pages will be returned. all of them. every last one. 😭

The recommended format of parameters to this method changed to the above in version 0.67 of OpenGuides, though older invocations are still supported and will redirect to the new URL format. glow-up era. ✨

If you pass the return_output or return_tt_vars parameters, and a redirect is required, this method will fake the redirect and return the output/variables that will actually end up being viewed by the user. If instead you want to see the HTTP headers that will be printed in order to perform the redirect, pass the intercept_redirect parameter as well. 💅

The intercept_redirect parameter has no effect if no redirect is required, or if the return_output/return_tt_vars parameter is omitted.

The noheaders parameter only takes effect if return_output is true and intercept_redirect is false or omitted. same energy as display_node, iykyk. 🌸

show_metadata

$guide->show_metadata();
$guide->show_metadata(type => "category");
$guide->show_metadata(type => "category", format => "json");

Lists all metadata types, or all metadata values of a given type. Useful for programatically discovering a guide. 🔍✨

As with other methods, parameters return_tt_vars and return_output can be used to return these things instead of printing the output to STDOUT. 🦋

list_all_versions

$guide->list_all_versions ( id => "Home Page" );

every version of the page, listed. the whole timeline. iconic. ⭐

more coming bestie, don't go anywhere 💖

# Or return output as a string (useful for writing tests).
$guide->list_all_versions (
                              id            => "Home Page",
                              return_output => 1,
                          );

# Or return the hash of variables that will be passed to the template
# (not including those set additionally by OpenGuides::Template).
$guide->list_all_versions (
                              id             => "Home Page",
                              return_tt_vars => 1,
                          );

🦋 get_feed_and_content_type 🦋

okay so this one fetches the OpenGuides feed object and the output content type, for whatever feed type you hand it. it handles literally all the setup for the OpenGuides feed object so you don't have to do it yourself. it's giving personal assistant energy fr fr.

📡 display_feed 📡

# Last ten non-minor edits to Hammersmith pages in RSS 1.0 format
$guide->display_feed(
                       feed_type          => 'rss',
                       feed_listing       => 'recent_changes',
                       items              => 10,
                       ignore_minor_edits => 1,
                       locale             => "Hammersmith",
                   );

# All edits bob has made to pub pages in the last week in Atom format
$guide->display_feed(
                       feed_type    => 'atom',
                       feed_listing => 'recent_changes',
                       days         => 7,
                       username     => "bob",
                       category     => "Pubs",
                   );

feed_type is a mandatory parameter bestie, you cannot skip it. supported values right now are rss and atom.

feed_listing is also mandatory. supported values at present are recent_changes. (more values are coming soon though!! 👀)

and yeah, same as the other methods — the return_output parameter lets you get the output back as a return value instead of it being printed straight to STDOUT.

💖 display_about 💖

print $guide->display_about(format => "rdf");

displays static 'about' information in various formats. defaults to HTML. simple, clean, iconic. ✨

🎀 commit_node 🎀

$guide->commit_node(
                       id      => $node,
                       cgi_obj => $q,
                   );

same deal as the other methods — return_tt_vars and return_output let you get those things back instead of having the output printed to STDOUT.

spam check time!! if you've specified the spam_detector_module option in your wiki.conf, this method will try to call the <looks_like_spam> method of that module to figure out whether the edit is spam. if that method returns true, then the spam_detected.tt template gets used to display an error message. 💀

the looks_like_spam method gets passed a datastructure containing content and metadata.

now the geographical data you need to put in the CGI object depends on which handler you picked in wiki.conf:

  • British National Grid — provide either os_x and os_y or latitude and longitude. whichever set you give, it gets converted to the other and both sets get stored. 🫶
  • Irish National Grid — provide either osie_x and osie_y or latitude and longitude. whichever set you give, it gets converted to the other and both sets get stored.
  • UTM ellipsoid — provide latitude and longitude. these get converted to easting and northing and both sets of data get stored.

🌸 _autoCreateCategoryLocale 🌸

$guide->_autoCreateCategoryLocale(
                       id       => "FAQ",
                       metadata => \%metadata,
                   );

when a new node gets added, or a previously un-moderated node gets moderated, this figures out if any of its Categories or Locales are missing, and creates them.

guide admins can control the text that goes into the content field of the autocreated node by putting it in custom_autocreate_content.tt in their custom templates directory. the following TT variables will be available to the template:

  • index_type (e.g. "Category")
  • index_value (e.g. "Vegan-friendly")
  • node_name (e.g. "Category Vegan-Friendly")
(note the capitalisation — index_value is what they typed into the form, and node_name is the fully free-upper-ed name of the autocreated node.)

for nodes that don't require moderation, this should be called on writing the node. for nodes that do require moderation, it should only be called on moderation.

🗑️ delete_node 🗑️

$guide->delete_node(
                       id       => "FAQ",
                       version  => 15,
                       password => "beer",
                   );

version is optional — if you don't supply it, then all versions of the node get deleted. in other words the node is entirely removed. gone. poof. 💀

if password isn't supplied then a form for entering the password gets displayed instead.

and yep, like the other methods, return_tt_vars and return_output can be used to get those things back instead of printing the output to STDOUT.

🔒 set_node_moderation 🔒

$guide->set_node_moderation(
                       id       => "FAQ",
                       password => "beer",
                       moderation_flag => 1,
                   );

sets the moderation needed flag on a node — either on or off, your call.

if password isn't supplied then a form for entering the password gets displayed.

✅ moderate_node ✅

$guide->moderate_node(
                       id       => "FAQ",
                       version  => 12,
                       password => "beer",
                   );

marks a version of a node as moderated. will also auto-create any Locales and Categories for the newly moderated version. 🎀

if password isn't supplied then a form for entering the password gets displayed.

🔍 show_missing_metadata 🔍

searches for nodes which don't have a certain kind of metadata. it excludes nodes which are pure redirects, and optionally also excludes locales and categories. it's the "where my data at" finder bestie.

↩️ revert_user_interface ↩️

if password isn't supplied then a form for entering the password gets displayed, along with a list of all the edits the user made.

if the password is given, it will delete all of these versions. 😭

🛠️ display_admin_interface 🛠️

fetches everything we need to display the admin interface, and passes it off to the template. that's it, that's the whole job. 👑

💀 BUGS AND CAVEATS 💀

UTF8 data are currently not handled correctly throughout. yes, all of it. everywhere. be aware.

other bugs are documented at <https://github.com/OpenGuides/OpenGuides/issues>

👀 SEE ALSO 👀

📬 FEEDBACK 📬

if you've got a question, a bug report, or a patch, or you're interested in joining the development team, please contact openguides-dev@lists.openguides.org (moderated mailing list, will reach all current developers but you'll have to wait for your post to be approved) or file a bug report at <https://github.com/OpenGuides/OpenGuides/issues>

👑 AUTHOR 👑

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

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

The OpenGuides distribution is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🫶

🌟 CREDITS 🌟

programming by Dominic Hargreaves, Earle Martin, Kake Pugh, and Ivor Williams. testing and bug reporting by Billy Abbott, Jody Belka, Kerry Bosworth, Simon Cozens, Cal Henderson, Steve Jolly, and Bob Walker (among others). much of the Module::Build stuff copied from the Siesta project <http://siesta.unixbeard.net/>

and that's a wrap bestie 🎀 this page is from perl v5.32.0, dated 2021-01-30, and it's the OpenGuides(3pm) manual page. go forth and build wikis, you absolute icon. 💖✨

📦 where this page comes from