# Blosxom3 Plugin: Search
# Author: Bernie Simon
# Version: 2004-02-18
# More notes at the bottom of this file or type: perldoc Search

package Blosxom::Plugin::Search;

use strict;
use Text::ParseWords;

#----------------------------------------------------------------------
# Configuration Section

# The paramter containing the search terms
use constant SEARCH_PARAM => 'query';

use constant SEARCH_FORM => <<'EOQ';
<div id="searchform">
<form method="get" action="">
<input type="text" name="" value="" />
</form>
</div>
EOQ
;

#----------------------------------------------------------------------
# call from handlers.entry

sub run {
    my $self = shift;

    # Get search terms from search parameter. Return if not found

    my $query = $self->{cgi}->param (SEARCH_PARAM);
    $query =~ s/[\<\>\%\;\)\(\&\+]//g;
    return 1 unless length ($query);

    # Prepare text for searching by stripping html

    my $text = $self->{state}->{current_entry}->{title} . ' ' .
	$self->{state}->{current_entry}->{body};

    $text =~ s/<!--.*?-->/ /gs;
    $text =~ s/<[^>]*>/ /gs;
    $text =~ s/&nbsp;/ /g;
    $text =~ tr/\t\r\n / /s;

    # Check text for search terms and stop if none found

    my @term = map ('\b' . quotemeta($_) . '\b', shellwords ($query));

    foreach my $term (@term) {
	if ($text !~ /$term/i) {
	    $self->{state}->{stop}->{handlers}->{entry} ++;
	    return 0;
	}
    }

    return 1;
}

#----------------------------------------------------------------------
# call from handlers.flow

sub form {
    my $self = shift;

    my $action =  $self->{request}->{url} . $self->{request}->{path_info};

    my $name = SEARCH_PARAM;

    my $query = $self->{cgi}->param (SEARCH_PARAM);
    $query =~ s/[\<\>\%\;\)\(\&\+]//g;

    my $form = SEARCH_FORM;
    $form =~ s/action=\"\"/action=\"$action\"/;
    $form =~ s/name=\"\"/name=\"$name\"/;
    $form =~ s/value=\"\"/value=\"$query\"/;

    $self->{state}->{current_entry}->{Plugin}->{Search}->{Form} = $form;

    return 1;
}

1;

__END__

=head1 NAME

Search.pm

=head1 SYNOPSIS

Display entries containing search terms

=head1 DESCRIPTION

The search plugin restricts results that are returned by Blosxom to
entries which contain the search terms submitted by the user. Thus it
allows the user to find the needle in the haystack of your Blosxom
weblog. Search terms only match complete words. No stemming is done on
the search terms: talking does not match talk. If you want to search
for a phrase, you can enclose it "in quotes."

The plugin looks for the cgi parameter query in the submitted
url. (The parameter name is configurable.) It examines the title and
the body of each entry and stop processing if the entry does not
contain all the submitted search terms. It does not otherwise effect
the results returned by Blosxom. This plugin can be used together with
the Paginate plugin to page through the search results.

=head1 CONFIGURABLE VARIABLES

The name of the search parameter and the input form can be configured.

=over 4

=item SEARCH_PARAM

The name of the cgi parameter containing the search terms.

=item SEARCH_FORM

The html code representing the search form. You may wish to change
this to customize the look of the form. Change the lines up to but not
including the EOQ, which marks the end of the form.

=back

=head1 INSTALLATION

Place this file in the plugins directory. Edit the
.settings/handlers.entry file and place the line

    Blosxom::Plugin::Search::run

after the line 

    Blosxom::read_entry_file

The form subroutine creates a search form and assigns it to the
variable $Plugin::Search::Form. Place this variable in your html
falvour template where you want the search form to appear. It is not
strictly necessary to call this subroutine. You could add your own
form in the head.html or foot.html template and not use it.

To use $Plugin::Search::Form, edit the .settings/handlers.flow file 
and add the line

    Blosxom::Plugin::Search::form

anywhere between the lines

    Blosxom::run_entries

and

    Blosxom::render_response

=head1 BUGS

Because the version of Blosxom 3 that is currently being distributed
ignores the handlers.flow file, you need to first install a patch to
Blosxom 3 to fix this problem, such as the one distributed on my
site in order for changes to the handlers.flow file to be recognized.

=head1 AUTHOR

Bernie Simon (http://carelesshand.net)

=head1 LICENSE

Copyright Bernard Simon, 2005. You may use this file as you wish as
long as this copyright notice is maintained.