Provided by: openguides_0.84-1_all bug

NAME

       OpenGuides - A complete web application for managing a collaboratively-written guide to a
       city or town.

DESCRIPTION

       The OpenGuides software provides the framework for a collaboratively-written city guide.
       It is similar to a wiki but provides somewhat more structured data storage allowing you to
       annotate wiki pages with information such as category, location, and much more.  It
       provides searching facilities including "find me everything within a certain distance of
       this place".  Every page includes a link to a machine-readable (RDF) version of the page.

METHODS

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

       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 "version" is omitted then it will assume you want the latest version.

           Note that 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.)

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

           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;

           Display a random page.  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
                                      );

           Display 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,
                                             );

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

       show_backlinks
             $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.

           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.

           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.

       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" );

             # 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
           Fetch the OpenGuides feed object, and the output content type, for the supplied feed
           type.

           Handles all the setup for the OpenGuides feed object.

       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. Supported values at present are "rss" and
           "atom".

           "feed_listing" is a mandatory parameter. Supported values at present are
           "recent_changes". (More values are coming soon though!)

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

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

           Displays static 'about' information in various format. Defaults to HTML.

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

           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.

           If you have specified the "spam_detector_module" option in your "wiki.conf", this
           method will attempt to call the <looks_like_spam> method of that module to determine
           whether the edit is spam.  If this method returns true, then the "spam_detected.tt"
           template will be used to display an error message.

           The "looks_like_spam" method will be passed a datastructure containing content and
           metadata.

           The geographical data that you should provide in the CGI object depends on the handler
           you chose in "wiki.conf".

           •   British National Grid - provide either "os_x" and "os_y" or "latitude" and
               "longitude"; whichever set of data you give, it will be converted to the other and
               both sets will be stored.

           •   Irish National Grid - provide either "osie_x" and "osie_y" or "latitude" and
               "longitude"; whichever set of data you give, it will be converted to the other and
               both sets will be stored.

           •   UTM ellipsoid - provide "latitude" and "longitude"; these will be converted to
               easting and northing and both sets of data will be stored.

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

           When a new node is added, or a previously un-moderated node is moderated, identifies
           if any of its Categories or Locales are missing, and creates them.

           Guide admins can control the text that gets put 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 capitalisation - index_value is what they typed in to the form, and node_name is
           the fully free-upper-ed name of the autocreated node.)

           For nodes not requiring moderation, should be called on writing the node For nodes
           requiring moderation, should only be called on moderation

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

           "version" is optional - if it isn't supplied then all versions of the node will be
           deleted; in other words the node will be entirely removed.

           If "password" is not supplied then a form for entering the password will be displayed.

           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.

       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.

           If "password" is not supplied then a form for entering the password will be displayed.

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

           Marks a version of a node as moderated. Will also auto-create and Locales and
           Categories for the newly moderated version.

           If "password" is not supplied then a form for entering the password will be displayed.

       show_missing_metadata
           Search for nodes which don't have a certain kind of metadata.  Excludes nodes which
           are pure redirects, and optionally also excludes locales and categories.

       revert_user_interface
           If "password" is not supplied then a form for entering the password will be displayed,
           along with a list of all the edits the user made.

           If the password is given, will delete all of these versions.

       display_admin_interface
           Fetch everything we need to display the admin interface, and passes it off
            to the template

BUGS AND CAVEATS

       UTF8 data are currently not handled correctly throughout.

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

SEE ALSO

       •   The Randomness Guide to London, at <http://london.randomness.org.uk/>, the largest
           OpenGuides site.

       •   The list of live OpenGuides installs at <http://openguides.org/>.

       •   Wiki::Toolkit, the Wiki toolkit which does the heavy lifting for OpenGuides.

FEEDBACK

       If you have 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

            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/>