API:EPrints/Plugin/Search - Revision history

https://wiki.eprints.org/w/index.php?action=history&feed=atom&title=API%3AEPrints%2FPlugin%2FSearch API:EPrints/Plugin/Search - Revision history 2026-05-02T12:46:52Z Revision history for this page on the wiki MediaWiki 1.31.8 https://wiki.eprints.org/w/index.php?title=API:EPrints/Plugin/Search&diff=10815&oldid=prev Tdb01r: Created page with '<!-- 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' com…' 2013-07-24T11:01:03Z

<p>Created page with '{{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><br /> <br /> <br /> <br /> ==NAME==<br /> EPrints::Plugin::Search - pluggable search engines<br /> <br /> <br /> <br /> <br /> <br /> <br /> ==SYNOPSIS==<br /> <source lang="perl"># use a specific engine<br /> $searchexp = $repo->plugin( "Search::XXX",<br /> dataset => $repo->dataset( "archive" ),<br /> filters => [{<br /> meta_fields => [qw( meta_visibility )], value => 'show',<br /> }],<br /> ...<br /> );<br /> <br /> # find the best engine for a given search configuration<br /> @engines = $repo->get_plugins({<br /> dataset => $repo->dataset( "archive" )<br /> },<br /> type => "Search",<br /> can_search => "simple/eprint",<br /> );<br /> @engines = sort {<br /> $b->param('qs') <=> $a->param('qs')<br /> } @engines;<br /> <br /> # render a search input form<br /> $form->appendChild(<br /> $searchexp->render_simple_fields<br /> );<br /> <br /> # read the user input terms<br /> $searchexp->from_form();<br /> <br /> # and execute to get some results<br /> $results = $searchexp->execute();</source><br /> <br /> <br /> <br /> <br /> <br /> <br /> ==DESCRIPTION==<br /> Search plugins implement the features required to render search query form inputs, perform queries and return matching objects.<br /> <br /> 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.<br /> <br /> 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.<br /> <br /> There are currently two engines provided as part of the EPrints core:<br /> <br /> * Internal<br /> : [[API:EPrints/Plugin/Search/Internal|EPrints::Plugin::Search::Internal]] is a wrapper around [[API:EPrints/Search|EPrints::Search]].<br /> <br /> : This supports querying any object type and in any search configuration (matches <code>*/*</code>).<br /> <br /> * Xapian<br /> : [[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.<br /> <br /> : Currently only <code>simple</code> searches are supported.<br /> <br /> <br /> ==METHODS==<br /> <br /> ===new===<br /> <br /> <source lang="perl">$searchexp = EPrints::Plugin::Search->new( session => $session, dataset => $dataset, %opts )<br /> <br /> </source><br /> : Create a new Search plugin object. Options:<br /> <br /> <pre> custom_order - stringified order specification<br /> qs - quality score</pre><br /> <br /> <br /> <br /> <br /> <br /> <br /> ===from_form===<br /> <br /> <source lang="perl">@probs = $searchexp->from_form()<br /> <br /> </source><br /> : Populate the query from an input form.<br /> <br /> <br /> <br /> <br /> <br /> <br /> ===from_cache===<br /> <br /> <source lang="perl">$ok = $searchexp->from_cache( $id )<br /> <br /> </source><br /> : Retrieve an existing query from a cache identified by $id.<br /> <br /> : The cache id is set via the [[API:EPrints/List|EPrints::List]] object returned by [[API:EPrints/Plugin/Search#execute|execute]] (cache_id option).<br /> <br /> <br /> <br /> <br /> <br /> <br /> ===from_string===<br /> <br /> <source lang="perl">$ok = $searchexp->from_string( $exp )<br /> <br /> </source><br /> : Populate the search values from a previously [[API:EPrints/Plugin/Search#serialise|serialise]]d query $exp.<br /> <br /> : Will only set search values for those fields that have already been defined.<br /> <br /> <br /> <br /> <br /> <br /> <br /> ===from_string_raw===<br /> <br /> <source lang="perl">$searchexp->from_string_raw( $exp )<br /> <br /> </source><br /> : Populate the search values from a previously [[API:EPrints/Plugin/Search#serialise|serialise]]d query $exp.<br /> <br /> : This will add any [[API:EPrints/Search/Field|EPrints::Search::Field]]s that are in $exp.<br /> <br /> <br /> <br /> <br /> <br /> <br /> ===from_string_fields===<br /> <br /> <source lang="perl">$searchexp->from_string_fields( $fields, %opts )<br /> <br /> </source><br /> : Populate the field values from serialised $fields (array ref).<br /> <br /> : Options:<br /> <br /> <pre> init - initialise the fields</pre><br /> <br /> <br /> <br /> <br /> <br /> <br /> ===from_string_filters===<br /> <br /> <source lang="perl">$searchexp->from_string_filters( $fields, %opts )<br /> <br /> </source><br /> : Populate the filter field values from serialised $fields (array ref).<br /> <br /> : Options:<br /> <br /> <pre> init - initialise the fields</pre><br /> <br /> <br /> <br /> <br /> <br /> <br /> ===serialise===<br /> <br /> <source lang="perl">$exp = $searchexp->serialise( %opts )<br /> <br /> </source><br /> : Serialise the query and return it as a plain-string.<br /> <br /> <br /> <br /> <br /> <br /> <br /> ===serialise_fields===<br /> <br /> <source lang="perl">@fields = $searchexp->serialise_fields()<br /> <br /> </source><br /> : Returns a list of serialised field-values.<br /> <br /> <br /> <br /> <br /> <br /> <br /> ===serialise_filters===<br /> <br /> <source lang="perl">@fields = $searchexp->serialise_filters()<br /> <br /> </source><br /> : Returns a list of serialised filter field-values.<br /> <br /> <br /> <br /> <br /> <br /> <br /> ===freeze===<br /> <br /> <source lang="perl">$spec = $searchexp->freeze()<br /> <br /> </source><br /> : Freeze this search spec.<br /> <br /> <br /> <br /> <br /> <br /> <br /> ===thaw===<br /> <br /> <source lang="perl">$searchexp = $searchexp->thaw( $spec )<br /> <br /> </source><br /> : Unthaw a search spec into a new [[API:EPrints/Plugin/Search|EPrints/Plugin/Search]] object.<br /> <br /> <pre> $searchexp = $repo-&gt;plugin( "Search" )-&gt;thaw( ... );</pre><br /> <br /> : Returns undef if $spec is invalid.<br /> <br /> <br /> <br /> <br /> <br /> <br /> ===is_blank===<br /> <br /> <source lang="perl">$searchexp->is_blank()<br /> <br /> </source><br /> : Returns true if no query has been specified (ignoring any dataset-specific filters).<br /> <br /> <br /> <br /> <br /> <br /> <br /> ===clear===<br /> <br /> <source lang="perl">$searchexp->clear()<br /> <br /> </source><br /> : Clears values from the query from e.g. [[API:EPrints/Plugin/Search#from_form|from_form]].<br /> <br /> <br /> <br /> <br /> <br /> <br /> ===execute===<br /> <br /> <source lang="perl">$results = $searchexp->execute()<br /> <br /> </source><br /> : Execute the query and return a [[API:EPrints/List|EPrints::List]] object (or subclass).<br /> <br /> <br /> <br /> <br /> <br /> <br /> ===render_description===<br /> <br /> <source lang="perl">$xhtml = $searchexp->render_description()<br /> <br /> </source><br /> : Return an XHTML DOM description of this search expression. This is the combination of the condition and sort options.<br /> <br /> <br /> <br /> <br /> <br /> <br /> ===render_conditions_description===<br /> <br /> <source lang="perl">$xhtml = $searchexp->render_conditions_description()<br /> <br /> </source><br /> : Return an XHTML DOM description of this search expression's conditions.<br /> <br /> <br /> <br /> <br /> <br /> <br /> ===render_order_description===<br /> <br /> <source lang="perl">$xhtml = $searchexp->render_order_description()<br /> <br /> </source><br /> : Return an XHTML DOM description of how this search is ordered.<br /> <br /> <br /> <br /> <br /> <br /> <br /> ===render_simple_fields===<br /> <br /> <source lang="perl">$xhtml = $searchexp->render_simple_fields( [ %opts ] )<br /> <br /> </source><br /> : Renders the form input field(s) required for a simple search (typically just a single text input box).<br /> <br /> : Options are as passed to [[API:EPrints/XHTML#input_field|EPrints::XHTML/input_field]].<br /> <br /> <br /> <br /> <br /> <br /> <br /> ===render_advanced_fields===<br /> <br /> <source lang="perl">$xhtml = $searchexp->render_advanced_fields()<br /> <br /> </source><br /> : Renders a list of input fields for advanced input as table rows.<br /> <br /> <br /> <br /> <br /> <br /> <br /> ===join_exp===<br /> <br /> <source lang="perl">$exp = $searchexp->join_exp( @sections )<br /> <br /> </source><br /> <br /> <br /> <br /> <br /> <br /> ===split_exp===<br /> <br /> <source lang="perl">@sections = $searchexp->split_exp( $exp )<br /> <br /> </source><br /> <br /> <br /> <br /> <br /> <br /> ===describe===<br /> <br /> <source lang="perl">$text = $searchexp->describe<br /> <br /> </source><br /> : Returns a text string describing this search query that will be executed (for debugging).<br /> <br /> <br /> <br /> <br /> <br /> <br /> ==SEE ALSO==<br /> :: [[API:EPrints/Const#EP_TRIGGER_INDEX_FIELDS|EPrints::Const/EP_TRIGGER_INDEX_FIELDS]], [[API:EPrints/Search|EPrints::Search]], [[API:EPrints/List|EPrints::List]].<br /> <br /> <br /> <br /> <br /> <br /> <br /> ==COPYRIGHT==<br /> :: Copyright 2000-2013 University of Southampton.<br /> <br /> :: This file is part of EPrints http://www.eprints.org/.<br /> <br /> :: 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.<br /> <br /> :: 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.<br /> <br /> :: You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.<br /> <br /> <br /> <br /> <br /> <br /> <br /> </div>

Tdb01r