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

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

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

       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.

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

             escalator

           will return all pages containing the word "escalator".

       ANDsearches
           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".

       ORsearches
           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".

       phrasesearches
           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".

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

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

       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):

       •   A match on page title will score higher than a match on page category or locale.

       •   A match on page category or locale will score higher than a match on page content.

       •   Two matches in the title beats one match in the title and one in the content.

       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,andos_y
           Only works if you chose to use British National Grid in wiki.conf

       osie_dist,osie_x,andosie_y
           Only works if you chose to use Irish National Grid in wiki.conf

       latlong_dist,latitude,andlongitude
           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.

       OpenGuides

perl v5.40.0                                       2025-01-02                            OpenGuides::Search(3pm)

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