NAME

       Wiki::Toolkit::Plugin::Locator::Grid - A Wiki::Toolkit plugin to manage co-ordinate data.

DESCRIPTION

       Access to and calculations using co-ordinate metadata supplied to a Wiki::Toolkit wiki
       when writing a node.

       Note: This is read-only access. If you want to write to a node's metadata, you need to do
       it using the "write_node" method of Wiki::Toolkit.

       We assume that the points are located on a flat, square grid with unit squares of side 1
       metre.

SYNOPSIS

         use Wiki::Toolkit;
         use Wiki::Toolkit::Plugin::Locator::Grid;

         my $wiki = Wiki::Toolkit->new( ... );
         my $locator = Wiki::Toolkit::Plugin::Locator::Grid->new;
         $wiki->register_plugin( plugin => $locator );

         $wiki->write_node( "Jerusalem Tavern", "A good pub", $checksum,
                            { x => 531674, y => 181950 } ) or die "argh";

         # Just retrieve the co-ordinates.
         my ( $x, $y ) = $locator->coordinates( node => "Jerusalem Tavern" );

         # Find the straight-line distance between two nodes, in metres.
         my $distance = $locator->distance( from_node => "Jerusalem Tavern",
                                            to_node   => "Calthorpe Arms" );

         # Find all the things within 200 metres of a given place.
         my @others = $locator->find_within_distance( node   => "Albion",
                                                      metres => 200 );

         # Maybe our wiki calls the x and y co-ordinates something else.
         my $locator = Wiki::Toolkit::Plugin::Locator::Grid->new(
                                                              x => "os_x",
                                                              y => "os_y",
                                                            );

METHODS

       new
             # By default we assume that x and y co-ordinates are stored in
             # metadata called "x" and "y".
             my $locator = Wiki::Toolkit::Plugin::Locator::Grid->new;

             # But maybe our wiki calls the x and y co-ordinates something else.
             my $locator = Wiki::Toolkit::Plugin::Locator::Grid->new(
                                                                  x => "os_x",
                                                                  y => "os_y",
                                                                );

       x_field
             my $x_field = $locator->x_field;

           An accessor, returns the name of the metadata field used to store the x-coordinate.

       y_field
             my $y_field = $locator->y_field;

           An accessor, returns the name of the metadata field used to store the y-coordinate.

       coordinates
             my ($x, $y) = $locator->coordinates( node => "Jerusalem Tavern" );

           Returns the x and y co-ordinates stored as metadata last time the node was written.

       distance
             # Find the straight-line distance between two nodes, in metres.
             my $distance = $locator->distance( from_node => "Jerusalem Tavern",
                                                to_node   => "Calthorpe Arms" );

             # Or in kilometres, and between a node and a point.
             my $distance = $locator->distance( from_x  => 531467,
                                                from_y  => 183246,
                                                to_node => "Duke of Cambridge",
                                                unit    => "kilometres" );

           Defaults to metres if "unit" is not supplied or is not recognised.  Recognised units
           at the moment: "metres", "kilometres".

           Returns "undef" if one of the endpoints does not exist, or does not have both co-
           ordinates defined. The "node" specification of an endpoint overrides the x/y co-ords
           if both specified (but don't do that).

           Note: Works to the nearest metre. Well, actually, calls "int" and rounds down, but if
           anyone cares about that they can send a patch.

       find_within_distance
             # Find all the things within 200 metres of a given place.
             my @others = $locator->find_within_distance( node   => "Albion",
                                                          metres => 200 );

             # Or within 200 metres of a given location.
             my @things = $locator->find_within_distance( x      => 530774,
                                                          y      => 182260,
                                                          metres => 200 );

           Units currently understood: "metres", "kilometres". If both "node" and "x"/"y" are
           supplied then "node" takes precedence. Croaks if insufficient start point data
           supplied.

SEE ALSO

       •   Wiki::Toolkit

       •   OpenGuides - an application that uses this plugin.

AUTHOR

       Kake Pugh (kake@earth.li).  The Wiki::Toolkit team (http://www.wiki-toolkit.org/)

COPYRIGHT

            Copyright (C) 2004 Kake L Pugh.  All Rights Reserved.
            Copyright (C) 2006 the Wiki::Toolkit Team. All Rights Reserved.

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

CREDITS

       This module is based heavily on (and is the replacement for)
       Wiki::Toolkit::Plugin::Locator::UK.

       The following thanks are due to people who helped with Wiki::Toolkit::Plugin::Locator::UK:
       Nicholas Clark found a very silly bug in a pre-release version, oops :) Stephen White got
       me thinking in the right way to implement "find_within_distance". Marcel Gruenauer helped
       me make "find_within_distance" work properly with postgres.

POD ERRORS

       Hey! The above document had some coding errors, which are explained below:

       Around line 269:
           You forgot a '=back' before '=head1'