---
name: "Wiki::Toolkit::Plugin::Locator::Grid"
section: "3pm"
platform: "linux"
package: "libwiki-toolkit-plugin-locator-grid-perl"
version: "0.05-5.1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Wiki::Toolkit::Plugin::Locator::Grid"
---

# Wiki::Toolkit::Plugin::Locator::Grid(3pm)

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

## 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'