NAME
CGI::Wiki::Plugin::Locator::Grid - A CGI::Wiki plugin to manage co-ordinate data.
DESCRIPTION
Access to and calculations using co-ordinate metadata supplied to a CGI::Wiki 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 CGI::Wiki.
We assume that the points are located on a flat, square grid with unit squares of side 1 metre.
SYNOPSIS
use
CGI::Wiki;
my
$wiki
= CGI::Wiki->new( ... );
my
$locator
= CGI::Wiki::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
= CGI::Wiki::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
= CGI::Wiki::Plugin::Locator::Grid->new;
# But maybe our wiki calls the x and y co-ordinates something else.
my
$locator
= CGI::Wiki::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. Thenode
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 bothnode
andx
/y
are supplied thennode
takes precedence. Croaks if insufficient start point data supplied.
SEE ALSO
OpenGuides - an application that uses this plugin.
AUTHOR
Kake Pugh (kake@earth.li).
COPYRIGHT
Copyright (C) 2004 Kake L Pugh. 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) CGI::Wiki::Plugin::Locator::UK.
The following thanks are due to people who helped with CGI::Wiki::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.
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 264:
You forgot a '=back' before '=head1'