API:EPrints/Plugin/Search

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects

API: Core API

Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki

NAME

EPrints::Plugin::Search - pluggable search engines

SYNOPSIS

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

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 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 simple and advanced searches for objects of class 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

EPrints::Plugin::Search::Internal is a wrapper around EPrints::Search.

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

Xapian

EPrints::Plugin::Search::Xapian is a wrapper around the Search::Xapian module (must be installed separately). Xapian supports relevance matches, phrase searching, stemming and other advanced text index approaches.

Currently only simple searches are supported.

METHODS

new

$searchexp = EPrints::Plugin::Search->new( session => $session, dataset => $dataset, %opts )

Create a new Search plugin object. Options:

  custom_order - stringified order specification
  qs - quality score

from_form

@probs = $searchexp->from_form()

Populate the query from an input form.

from_cache

$ok = $searchexp->from_cache( $id )

Retrieve an existing query from a cache identified by $id.

The cache id is set via the EPrints::List object returned by execute (cache_id option).

from_string

$ok = $searchexp->from_string( $exp )

Populate the search values from a previously serialised query $exp.

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

from_string_raw

$searchexp->from_string_raw( $exp )

Populate the search values from a previously serialised query $exp.

This will add any EPrints::Search::Fields that are in $exp.

from_string_fields

$searchexp->from_string_fields( $fields, %opts )

Populate the field values from serialised $fields (array ref).

Options:

  init - initialise the fields

from_string_filters

$searchexp->from_string_filters( $fields, %opts )

Populate the filter field values from serialised $fields (array ref).

Options:

  init - initialise the fields

serialise

$exp = $searchexp->serialise( %opts )

Serialise the query and return it as a plain-string.

serialise_fields

@fields = $searchexp->serialise_fields()

Returns a list of serialised field-values.

serialise_filters

@fields = $searchexp->serialise_filters()

Returns a list of serialised filter field-values.

freeze

$spec = $searchexp->freeze()

Freeze this search spec.

thaw

$searchexp = $searchexp->thaw( $spec )

Unthaw a search spec into a new EPrints/Plugin/Search object.

  $searchexp = $repo->plugin( "Search" )->thaw( ... );

Returns undef if $spec is invalid.

is_blank

$searchexp->is_blank()

Returns true if no query has been specified (ignoring any dataset-specific filters).

clear

$searchexp->clear()

Clears values from the query from e.g. from_form.

execute

$results = $searchexp->execute()

Execute the query and return a EPrints::List object (or subclass).

render_description

$xhtml = $searchexp->render_description()

Return an XHTML DOM description of this search expression. This is the combination of the condition and sort options.

render_conditions_description

$xhtml = $searchexp->render_conditions_description()

Return an XHTML DOM description of this search expression's conditions.

render_order_description

$xhtml = $searchexp->render_order_description()

Return an XHTML DOM description of how this search is ordered.

render_simple_fields

$xhtml = $searchexp->render_simple_fields( [ %opts ] )

Renders the form input field(s) required for a simple search (typically just a single text input box).

Options are as passed to EPrints::XHTML/input_field.

render_advanced_fields

$xhtml = $searchexp->render_advanced_fields()

Renders a list of input fields for advanced input as table rows.

join_exp

$exp = $searchexp->join_exp( @sections )

split_exp

@sections = $searchexp->split_exp( $exp )

describe

$text = $searchexp->describe

Returns a text string describing this search query that will be executed (for debugging).

COPYRIGHT

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/.