API:EPrints/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::Search - Represents a single search

User Comments

DESCRIPTION

The Search object represents the conditions of a single search. It returns an EPrints::List object which stores the results of the search.

A Search object can also render itself as a web-form, populate itself with values from that web-form and render the results as a web page.

User Comments

SYNOPSIS

 # searching for articles and books in the archive, sorted by date:
 my $ds = $handle->get_dataset( "archive" );
 
 my $searchexp = EPrints::Search->new(
   satisfy_all => 1,
   handle => $handle,
   dataset => $ds,
   order => "-date"
 );
 
 $searchexp->add_field( $ds->get_field( "type" ), qw/ article book /, "EQ", "ANY" );
 
 # getting the results:
 my $list = $searchexp->perform_search;
 
 # Dispose of the Search object:
 $searchexp->dispose;
 

User Comments

SEE ALSO <EPrints::List> to know how to access the results of the search.

User Comments

METHODS

User Comments

$searchexp = EPrints::Search->new( %params )

Create a new search expression.

The parameters are split into two parts. The general parameters and those which influence how the HTML form is rendered, and the results displayed.

GENERAL PARAMETERS

User Comments

handle (required)

The current EPrints::Handle

User Comments

dataset OR dataset_id (required)

Either the EPrints::DataSet to search, or the ID of it.

User Comments

allow_blank (default 0)

Unless this is set, a search with no conditions will return zero records rather than all records.

User Comments

satisfy_all (default 1)

If this is true than all search-fields much be satisfied, if false then results matching any search-field will be returned.

User Comments

search_fields

A reference to an array of search field configuration structures. Each takes the form: { id=>"...", default=>"..", meta_fields=>"..." }

where the meaning is the same as for search configuration in cfg.d/eprint_search_*.pl

Search fields can also be added to the search expression after it has been constructed (by using $searchexp->add_field(...)).

User Comments

order

The order the results should be returned.

User Comments

custom_order

"order" limits you to the orders specified in cfg.d/eprint_search_*.pl, and is usually used by the web page based searching. custom_order allows you to specify any order you like. The format is foo/-bar. This means that the results will be sorted by foo and then any with equal foo values will be reverse sorted by bar. More than 2 fields can be specified.

User Comments

keep_cache

If true then the search results produced will be stored in the database even after the current script ends. This is useful for speeding up page 2 onwards of a search.

keep_cache may get set to true anyway for various reasons, but setting the parameter makes certain of it.

User Comments

cache_id

The ID of a cached search. The cache contains both the results of the search, and the parameters used for the search.

If the cache still exists, it will set the default values of the search fields, and when the search is performed it will skip the search and build a search results object directly from the cache.

User Comments

limit

Limit the number of matching records to limit.

User Comments

prefix (default "")

When generating the web form and reading back from the web form, the prefix is inserted before the form names of all fields. This is useful if you need to put two search expressions in a single form for some reason.

User Comments

staff (default 0)

If true then this is a "staff" search, which prevents searching unless the user is staff, and the results link to the staff URL of an item rather than the public URL.

User Comments

filters

A reference to an array of filter definitions.

Filter definitions take the form of: { value=>"..", match=>"..", merge=>"..", id=>".." } and work much like normal search fields except that they do not appear in the web form so force certain search parameters on the user.

An optional parameter of describe=>0 can be set to supress the filter being mentioned in the description of the search.

User Comments

$results = $searchexp->perform_search

Execute this search and return a EPrints::List object representing the results.

User Comments

$searchfield = $searchexp->add_field( $metafields, $value, $match, $merge, $id, $filter, $show_help )

Adds the new search field $metafields (which is either a single EPrints::MetaField or a list of fields in an array ref) with default $value. If a search field already exists, the value of that field is replaced with $value.

User Comments

$searchexp->clear

Clear the search values of all search fields in the expression.

Resets satisfy_all to true.

User Comments

$newsearchexp = $searchexp->clone

Return a new search expression which is a duplicate of this one.

User Comments

$xhtml = $searchexp->render_description

Return an XHTML DOM description of this search expressions current parameters.

User Comments

$xhtml = $searchexp->render_conditions_description

Return an XHTML DOM description of this search expressions conditions. ie title is "foo"

User Comments

$xhtml = $searchexp->render_order_description

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

User Comments

$searchexp->set_property( $property, $value );

Set any single property of this search, such as the order.

User Comments