Editing API:EPrints/Plugin/Search

<!-- Pod2Wiki=_preamble_ 
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
 -->{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/Plugin/Search.pm|package_name=EPrints::Plugin::Search}}[[Category:API|SEARCH]][[Category:API:EPrints/Plugin|SEARCH]][[Category:API:EPrints/Plugin/Search|SEARCH]]<div><!-- Edit below this comment -->


<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
==NAME==
EPrints::Plugin::Search - pluggable search engines

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_synopsis -->
==SYNOPSIS==
<source lang="perl"># use a specific engine
$searchexp = $repo->plugin( "Search::XXX",
	dataset => $repo->dataset( "archive" ),
	filters => [{
		meta_fields => [qw( meta_visibility )], value => 'show',
	}],
	...
);

# find the best engine for a given search configuration
@engines = $repo->get_plugins({
		dataset => $repo->dataset( "archive" )
	},
	type => "Search",
	can_search => "simple/eprint",
);
@engines = sort {
		$b->param('qs') <=> $a->param('qs')
	} @engines;

# render a search input form
$form->appendChild(
	$searchexp->render_simple_fields
);

# read the user input terms
$searchexp->from_form();

# and execute to get some results
$results = $searchexp->execute();</source>

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_description -->
==DESCRIPTION==
Search plugins implement the features required to render search query form inputs, perform queries and return matching objects.

The main function of a search plugin is to retrieve objects from a [[API:EPrints/DataSet|dataset]] based on a set of search criteria. The criteria are search fields and search filters. The terms used in search fields are usually provided by the user (e.g. from a Web form) while filters are defined by the search configuration. Search fields also define the "setness" of a search - if the user hasn't supplied any search terms the search is deemed to be empty. Filters tend to provide more options than those currently available from the Web UI, for instance testing whether a value is or is not set.

In the default EPrints configuration there are <code>simple</code> and <code>advanced</code> searches for objects of class [[API:EPrints/DataObj/EPrint|EPrints::DataObj::EPrint]]. These (at least) define the form input boxes provided to the user and the fields that those user-supplied values are matched against. The search configuration can also define the choice of ordering of results, additional filters etc. Not all options will be supported by every engine - see the engine-specific plugins for details.

There are currently two engines provided as part of the EPrints core:

* Internal
: [[API:EPrints/Plugin/Search/Internal|EPrints::Plugin::Search::Internal]] is a wrapper around [[API:EPrints/Search|EPrints::Search]].

: This supports querying any object type and in any search configuration (matches <code>*/*</code>).

* Xapian
: [[API:EPrints/Plugin/Search/Xapian|EPrints::Plugin::Search::Xapian]] is a wrapper around the {{API:PodLink|file=Search/Xapian|package_name=Search::Xapian|section=|text=Search::Xapian}} module (must be installed separately). Xapian supports relevance matches, phrase searching, stemming and other advanced text index approaches.

: Currently only <code>simple</code> searches are supported.

<!-- Pod2Wiki=head_methods -->
==METHODS==
<!-- Pod2Wiki=head_new -->
===new===

<source lang="perl">$searchexp = EPrints::Plugin::Search->new( session => $session, dataset => $dataset, %opts )

</source>
: Create a new Search plugin object. Options:

<pre>  custom_order - stringified order specification
  qs - quality score</pre>

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_from_form -->
===from_form===

<source lang="perl">@probs = $searchexp->from_form()

</source>
: Populate the query from an input form.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_from_cache -->
===from_cache===

<source lang="perl">$ok = $searchexp->from_cache( $id )

</source>
: Retrieve an existing query from a cache identified by $id.

: The cache id is set via the [[API:EPrints/List|EPrints::List]] object returned by [[API:EPrints/Plugin/Search#execute|execute]] (cache_id option).

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_from_string -->
===from_string===

<source lang="perl">$ok = $searchexp->from_string( $exp )

</source>
: Populate the search values from a previously [[API:EPrints/Plugin/Search#serialise|serialise]]d query $exp.

: Will only set search values for those fields that have already been defined.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_from_string_raw -->
===from_string_raw===

<source lang="perl">$searchexp->from_string_raw( $exp )

</source>
: Populate the search values from a previously [[API:EPrints/Plugin/Search#serialise|serialise]]d query $exp.

: This will add any [[API:EPrints/Search/Field|EPrints::Search::Field]]s that are in $exp.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_from_string_fields -->
===from_string_fields===

<source lang="perl">$searchexp->from_string_fields( $fields, %opts )

</source>
: Populate the field values from serialised $fields (array ref).

: Options:

<pre>  init - initialise the fields</pre>

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_from_string_filters -->
===from_string_filters===

<source lang="perl">$searchexp->from_string_filters( $fields, %opts )

</source>
: Populate the filter field values from serialised $fields (array ref).

: Options:

<pre>  init - initialise the fields</pre>

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_serialise -->
===serialise===

<source lang="perl">$exp = $searchexp->serialise( %opts )

</source>
: Serialise the query and return it as a plain-string.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_serialise_fields -->
===serialise_fields===

<source lang="perl">@fields = $searchexp->serialise_fields()

</source>
: Returns a list of serialised field-values.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_serialise_filters -->
===serialise_filters===

<source lang="perl">@fields = $searchexp->serialise_filters()

</source>
: Returns a list of serialised filter field-values.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_freeze -->
===freeze===

<source lang="perl">$spec = $searchexp->freeze()

</source>
: Freeze this search spec.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_thaw -->
===thaw===

<source lang="perl">$searchexp = $searchexp->thaw( $spec )

</source>
: Unthaw a search spec into a new [[API:EPrints/Plugin/Search|EPrints/Plugin/Search]] object.

<pre>  $searchexp = $repo-&gt;plugin( "Search" )-&gt;thaw( ... );</pre>

: Returns undef if $spec is invalid.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_is_blank -->
===is_blank===

<source lang="perl">$searchexp->is_blank()

</source>
: Returns true if no query has been specified (ignoring any dataset-specific filters).

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_clear -->
===clear===

<source lang="perl">$searchexp->clear()

</source>
: Clears values from the query from e.g. [[API:EPrints/Plugin/Search#from_form|from_form]].

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_execute -->
===execute===

<source lang="perl">$results = $searchexp->execute()

</source>
: Execute the query and return a [[API:EPrints/List|EPrints::List]] object (or subclass).

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_render_description -->
===render_description===

<source lang="perl">$xhtml = $searchexp->render_description()

</source>
: Return an XHTML DOM description of this search expression. This is the combination of the condition and sort options.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_render_conditions_description -->
===render_conditions_description===

<source lang="perl">$xhtml = $searchexp->render_conditions_description()

</source>
: Return an XHTML DOM description of this search expression's conditions.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_render_order_description -->
===render_order_description===

<source lang="perl">$xhtml = $searchexp->render_order_description()

</source>
: Return an XHTML DOM description of how this search is ordered.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_render_simple_fields -->
===render_simple_fields===

<source lang="perl">$xhtml = $searchexp->render_simple_fields( [ %opts ] )

</source>
: Renders the form input field(s) required for a simple search (typically just a single text input box).

: Options are as passed to [[API:EPrints/XHTML#input_field|EPrints::XHTML/input_field]].

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_render_advanced_fields -->
===render_advanced_fields===

<source lang="perl">$xhtml = $searchexp->render_advanced_fields()

</source>
: Renders a list of input fields for advanced input as table rows.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_join_exp -->
===join_exp===

<source lang="perl">$exp = $searchexp->join_exp( @sections )

</source>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_split_exp -->
===split_exp===

<source lang="perl">@sections = $searchexp->split_exp( $exp )

</source>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_describe -->
===describe===

<source lang="perl">$text = $searchexp->describe

</source>
: Returns a text string describing this search query that will be executed (for debugging).

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_see_also -->
==SEE ALSO==
:: [[API:EPrints/Const#EP_TRIGGER_INDEX_FIELDS|EPrints::Const/EP_TRIGGER_INDEX_FIELDS]], [[API:EPrints/Search|EPrints::Search]], [[API:EPrints/List|EPrints::List]].

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_copyright -->
==COPYRIGHT==
:: Copyright 2000-2013 University of Southampton.

:: This file is part of EPrints http://www.eprints.org/.

:: EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

:: EPrints is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.

:: You should have received a copy of the GNU Lesser General Public License along with EPrints.  If not, see http://www.gnu.org/licenses/.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=_postamble_ -->
<!-- Edit below this comment -->