bob walker > OpenGuides-0.70 > OpenGuides::Search

Download:
OpenGuides-0.70.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 0.14   Source   Latest Release: OpenGuides-0.77

NAME ^

OpenGuides::Search - Search form generation and processing for OpenGuides.

DESCRIPTION ^

Does search stuff for OpenGuides. Distributed and installed as part of the OpenGuides project, not intended for independent installation. This documentation is probably only useful to OpenGuides developers.

SYNOPSIS ^

  use CGI;
  use OpenGuides::Config;
  use OpenGuides::Search;

  my $config = OpenGuides::Config->new( file => "wiki.conf" );
  my $search = OpenGuides::Search->new( config => $config );
  my %vars = CGI::Vars();
  $search->run( vars => \%vars );

METHODS ^

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

An accessor; returns the underlying Wiki::Toolkit object.

config
  my $config = $search->config;

An accessor; returns the underlying OpenGuides::Config object.

run
  my %vars = CGI::Vars();
  $search->run(
                vars           => \%vars,
                return_output  => 1,   # defaults to 0
                return_tt_vars => 1,  # defaults to 0
              );

The return_output parameter is optional. If supplied and true, the stuff that would normally be printed to STDOUT will be returned as a string instead.

The return_tt_vars parameter is also optional. If supplied and true, the template is not processed and the variables that would have been passed to it are returned as a hash. This parameter takes precedence over return_output.

These two parameters exist to make testing easier; you probably don't want to use them in production.

You can also request just the raw search results:

  my %results = $search->run(
                              os_x    => 528864,
                              os_y    => 180797,
                              os_dist => 750,
                              format  => "raw",
                            );

Results are returned as a hash, keyed on the page name. All results are returned, not just the first page. The values in the hash are hashes themselves, with the following key/value pairs:

  • name
  • wgs84_lat - WGS-84 latitude
  • wgs84_long - WGS-84 longitude
  • summary
  • distance - distance (in metres) from origin, if origin exists
  • score - relevance to search string, if search string exists; higher score means more relevance

In case you're struggling to follow the code, it does the following: 1) Processes the parameters, and bails out if it hit a problem with them 2) If a search string was given, do a text search 3) If distance search paramaters were given, do a distance search 4) If no search has occured, print out the search form 5) If an error occured, bail out 6) If we got a single hit on a string search, redirect to it 7) If no results were found, give an empty search results page 8) Sort the results by either score or distance 9) Decide which results to show, based on paging 10) Display the appropriate page of the results

INPUT ^

word

a single word will be matched as-is. For example, a search on

  escalator

will return all pages containing the word "escalator".

AND searches

A list of words with no punctuation will be ANDed, for example:

  restaurant vegetarian

will return all pages containing both the word "restaurant" and the word "vegetarian".

OR searches

A list of words separated by commas (and optional spaces) will be ORed, for example:

  restaurant, cafe

will return all pages containing either the word "restaurant" or the word "cafe".

phrase searches

Enclose phrases in double quotes, for example:

  "meat pie"

will return all pages that contain the exact phrase "meat pie" - not pages that only contain, for example, "apple pie and meat sausage".

SEARCHING BY DISTANCE ^

To perform a distance search, you need to supply one of the following sets of criteria to specify the distance to search within, and the origin (centre) of the search:

os_dist, os_x, and os_y

Only works if you chose to use British National Grid in wiki.conf

osie_dist, osie_x, and osie_y

Only works if you chose to use Irish National Grid in wiki.conf

latlong_dist, latitude, and longitude

Should always work, but has a habit of "finding" things a couple of metres away from themselves.

You can perform both pure distance searches and distance searches in combination with text searches.

OUTPUT ^

Results will be put into some form of relevance ordering. These are the rules we have tests for so far (and hence the only rules that can be relied on):

AUTHOR ^

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

COPYRIGHT ^

     Copyright (C) 2003-2012 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.

SEE ALSO ^

OpenGuides

syntax highlighting: