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

  # 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 the latest version will be displayed.

display_edit_form

  $guide->display_edit_form(
                             id => "Vivat Bacchus",
                           );

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.

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

  $guide->show_index(
                        type   => "category",
                        value  => "pubs",
                    );

  # RDF version.
  $guide->show_index(
                        type   => "locale",
                        value  => "Holborn",
                        format => "rdf",
                    );

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

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

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.

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.

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. 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 http://dev.openguides.org/

SEE ALSO

• http://london.openguides.org/, the first and biggest OpenGuides site.

• http://openguides.org/, with a list of all live OpenGuides installs.

• 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 http://dev.openguides.org/

AUTHOR

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

COPYRIGHT

     Copyright (C) 2003-2006 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/