Difference between revisions of "API:EPrints/Search"

From EPrints Documentation
Jump to: navigation, search
Line 17: Line 17:
 
<!-- Pod2Wiki=head_description --></div>
 
<!-- Pod2Wiki=head_description --></div>
 
==DESCRIPTION==
 
==DESCRIPTION==
The Search object represents the conditions of a single  search. It returns an [[API:EPrints/List|EPrints::List]] object which stores the results of the search.
+
The Search object represents the conditions of a single  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.
+
It used to also store the results of the search, but now it returns an [[API:EPrints/List|EPrints::List]] object.
 +
 
 +
A search expression can also render itself as a web-form, populate itself with values from that web-form and render the results as a web page.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 26: Line 28:
  
  
<!-- Pod2Wiki=head_synopsis --></div>
+
<!-- Pod2Wiki=head_examples --></div>
==SYNOPSIS==
+
==EXAMPLES==
  # searching for articles and books in the archive, sorted by date:
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
   my $ds = $handle-&gt;get_dataset( "archive" );
+
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=head_searching_for_eprints --></div>
 +
===Searching for Eprints===
 +
   $ds = $session-&gt;get_repository-&gt;get_dataset( "archive" );
 
    
 
    
   my $search = EPrints::Search-&gt;new(
+
   $searchexp = EPrints::Search-&gt;new(
 
     satisfy_all =&gt; 1,
 
     satisfy_all =&gt; 1,
     handle =&gt; $handle,
+
     session =&gt; $session,
 
     dataset =&gt; $ds,
 
     dataset =&gt; $ds,
    order =&gt; "-date"
 
 
   );
 
   );
 
    
 
    
   $search-&gt;add_field( $ds-&gt;get_field( "type" ), qw/ article book /, "EQ", "ANY" );
+
  # Search for an eprint with eprintid 23
 +
  # (ought to use EPrints::DataObj::EPrint-&gt;new( SESSION, ID ))
 +
   $searchexp-&gt;add_field( $ds-&gt;get_field( "eprintid" ), 23 );
 
    
 
    
   # getting the results:
+
   $searchexp-&gt;add_field( $ds-&gt;get_field( "creators" ), "John Smith" );
  my $list = $search-&gt;perform_search;
+
 
+
  # Dispose of the Search object:
+
  $search-&gt;dispose;
+
 
    
 
    
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 51: Line 56:
  
  
<!-- Pod2Wiki=head_see_also_eprints_list_to_know_how_to_access_the_results_of_the_search --></div>
+
<!-- Pod2Wiki=head_getting_results --></div>
==SEE ALSO &lt;EPrints::List&gt; to know how to access the results of the search.==
+
===Getting Results===
 +
  $results = $searchexp-&gt;perform_search;
 +
 
 +
  my $count = $results-&gt;count;
 +
 
 +
  my $ids = $results-&gt;ids( 0, 10 );
 +
  my $ids = $results-&gt;ids; # Get all matching ids
 +
 
 +
  my $info = { matches =&gt; 0 };
 +
  sub fn {
 +
    my( $session, $dataset, $eprint, $info ) = @_;
 +
    $info-&gt;{matches}++;
 +
  };
 +
  $results-&gt;map( \&amp;fn, $info );
 +
 
 +
  $results-&gt;dispose;
 +
 
 +
See [[API:EPrints/List|EPrints::List]] for more.
 +
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<h4><span style='display:none'>User Comments</span></h4>
Line 66: Line 89:
  
 
<!-- Pod2Wiki=item_new --></div>
 
<!-- Pod2Wiki=item_new --></div>
===$search = EPrints::Search-&gt;new( %params )===
+
===$searchexp = EPrints::Search-&gt;new( %params )===
  
 
Create a new search expression.
 
Create a new search expression.
Line 79: Line 102:
  
  
<!-- Pod2Wiki=item_handle --></div>
+
<!-- Pod2Wiki=item_session --></div>
===handle (required)===
+
===session (required)===
  
The current [[API:EPrints/Handle|EPrints::Handle]]
+
The current [[API:EPrints/Session|EPrints::Session]]
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 122: Line 145:
 
===search_fields===
 
===search_fields===
  
A reference to an array of search field configuration structures. Each  takes the form: { id=&gt;"...", default=&gt;"..", meta_fields=&gt;"..." }  
+
A reference to an array of search field configuration structures. Each  takes the form { id=&gt;"...", default=&gt;"..", meta_fields=&gt;"..." } where the meaning is the same as for search configuration in ArchiveConfig.
  
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.
 
+
Search fields can also be added to the search expression after it has been constructed (by using $search-&gt;add_field(...)).
+
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 136: Line 157:
 
===order===
 
===order===
  
The order the results should be returned.  
+
The order the results should be returned. This is a key to the list of orders available to this dataset, defined in ArchiveConfig.pm
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 146: Line 167:
 
===custom_order===
 
===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.
+
"order" limits you to the orders specified in ArchiveConfig, 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.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 221: Line 242:
  
  
<!-- Pod2Wiki=item_perform_search --></div>
+
<!-- Pod2Wiki=item_from_cache --></div>
===$results = $search-&gt;perform_search===
+
===$ok = $thing-&gt;from_cache( $id )===
  
Execute this search and return a [[API:EPrints/List|EPrints::List]] object representing the results.
+
Populate this search expression with values from the given cache.
 +
 
 +
Return false if the cache does not exist.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 232: Line 255:
  
 
<!-- Pod2Wiki=item_add_field --></div>
 
<!-- Pod2Wiki=item_add_field --></div>
===$searchfield = $search-&gt;add_field( $metafields, $value, $match, $merge, $id, $filter, $show_help )===
+
===$searchfield = $searchexp-&gt;add_field( $metafields, $value, $match, $merge, $id, $filter, $show_help )===
 +
 
 +
Adds a new search in $metafields which is either a single [[API:EPrints/MetaField|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.
  
Adds the new search field $metafields (which is either a single [[API:EPrints/MetaField|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.
+
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=item_get_searchfield --></div>
 +
===$searchfield = $searchexp-&gt;get_searchfield( $sf_id )===
 +
 
 +
Return a [[API:EPrints/Search/Field|EPrints::Search::Field]] belonging to this Search with the given id.
 +
 
 +
Return undef if not searchfield of that ID belongs to this search.  
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 242: Line 278:
  
 
<!-- Pod2Wiki=item_clear --></div>
 
<!-- Pod2Wiki=item_clear --></div>
===$search-&gt;clear===
+
===$searchexp-&gt;clear===
  
 
Clear the search values of all search fields in the expression.
 
Clear the search values of all search fields in the expression.
  
 
Resets satisfy_all to true.
 
Resets satisfy_all to true.
 +
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki=item_get_satisfy_all --></div>
 +
===$bool = $searchexp-&gt;get_satisfy_all===
 +
 +
Return true if this search requires that all the search fields with values are satisfied.
 +
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki=item_is_blank --></div>
 +
===$boolean = $searchexp-&gt;is_blank===
 +
 +
Return true is this searchexpression has no conditions set, otherwise true.
 +
 +
If any field is set to "exact" then it can never count as unset.
 +
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki=item_serialise --></div>
 +
===$string = $searchexp-&gt;serialise===
 +
 +
Return a text representation of the search expression, for persistent storage. Doesn't store table or the order by fields, just the field names, values, default order and satisfy_all.
 +
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki=item_from_string --></div>
 +
===$searchexp-&gt;from_string( $string )===
 +
 +
Unserialises the contents of $string but only into the fields alrdeady existing in $searchexp. Set the order and satisfy_all mode but do not  affect the dataset or allow blank.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 254: Line 332:
  
 
<!-- Pod2Wiki=item_clone --></div>
 
<!-- Pod2Wiki=item_clone --></div>
===$newsearch = $search-&gt;clone===
+
===$newsearchexp = $searchexp-&gt;clone===
  
 
Return a new search expression which is a duplicate of this one.
 
Return a new search expression which is a duplicate of this one.
 +
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki=item_get_conditons --></div>
 +
===$conditions = $searchexp-&gt;get_conditons===
 +
 +
Return a tree of [[API:EPrints/Search/Condition|EPrints::Search::Condition]] objects describing the simple steps required to perform this search.
 +
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki=item_get_dataset --></div>
 +
===$dataset = $searchexp-&gt;get_dataset===
 +
 +
Return the [[API:EPrints/DataSet|EPrints::DataSet]] which this search relates to.
 +
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki=item_set_dataset --></div>
 +
===$searchexp-&gt;set_dataset( $dataset )===
 +
 +
Set the [[API:EPrints/DataSet|EPrints::DataSet]] which this search relates to.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 264: Line 372:
  
 
<!-- Pod2Wiki=item_render_description --></div>
 
<!-- Pod2Wiki=item_render_description --></div>
===$xhtml = $search-&gt;render_description===
+
===$xhtml = $searchexp-&gt;render_description===
  
 
Return an XHTML DOM description of this search expressions current parameters.
 
Return an XHTML DOM description of this search expressions current parameters.
Line 274: Line 382:
  
 
<!-- Pod2Wiki=item_render_conditions_description --></div>
 
<!-- Pod2Wiki=item_render_conditions_description --></div>
===$xhtml = $search-&gt;render_conditions_description===
+
===$xhtml = $searchexp-&gt;render_conditions_description===
  
 
Return an XHTML DOM description of this search expressions conditions. ie title is "foo"  
 
Return an XHTML DOM description of this search expressions conditions. ie title is "foo"  
Line 284: Line 392:
  
 
<!-- Pod2Wiki=item_render_order_description --></div>
 
<!-- Pod2Wiki=item_render_order_description --></div>
===$xhtml = $search-&gt;render_order_description===
+
===$xhtml = $searchexp-&gt;render_order_description===
  
 
Return an XHTML DOM description of how this search is ordered.
 
Return an XHTML DOM description of how this search is ordered.
Line 294: Line 402:
  
 
<!-- Pod2Wiki=item_set_property --></div>
 
<!-- Pod2Wiki=item_set_property --></div>
===$search-&gt;set_property( $property, $value );===
+
===$searchexp-&gt;set_property( $property, $value );===
  
 
Set any single property of this search, such as the order.
 
Set any single property of this search, such as the order.
 +
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki=item_get_searchfields --></div>
 +
===@search_fields = $searchexp-&gt;get_searchfields()===
 +
 +
Return the [[API:EPrints/Search/Field|EPrints::Search::Field]] objects relating to this search.
 +
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki=item_get_non_filter_searchfields --></div>
 +
===@search_fields = $searchexp-&gt;get_non_filter_searchfields();===
 +
 +
Return the [[API:EPrints/Search/Field|EPrints::Search::Field]] objects relating to this search, which are normal search fields, and not "filters".
 +
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki=item_get_set_searchfields --></div>
 +
===@search_fields = $searchexp-&gt;get_set_searchfields===
 +
 +
Return the searchfields belonging to this search expression which have a value set.
 +
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki=item_get_cache_id --></div>
 +
===$cache_id = $searchexp-&gt;get_cache_id===
 +
 +
Return the ID of the cache containing the results of this search, if known.
 +
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki=item_perform_search --></div>
 +
===$results = $searchexp-&gt;perform_search===
 +
 +
Execute this search and return a [[API:EPrints/List|EPrints::List]] object representing the results.
 +
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki=item_perform_groupby --></div>
 +
===($values, $counts) = $searchexp-&gt;perform_groupby( $field )===
 +
 +
Perform a SQL GROUP BY on $field based on the current search parameters.
 +
 +
Returns two array references, one containing a list of unique values and one a list of counts for each value.
 +
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<h4><span style='display:none'>User Comments</span></h4>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki=item_get_ids_by_field_values --></div>
 +
===$hash = $searchexp-&gt;get_ids_by_field_values( $field )===
 +
 +
Find the ids for each unique value in $field.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>

Revision as of 16:34, 12 February 2010


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.3, 3.2) | 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 used to also store the results of the search, but now it returns an EPrints::List object.

A search expression 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


EXAMPLES

User Comments


Searching for Eprints

 $ds = $session->get_repository->get_dataset( "archive" );
 
 $searchexp = EPrints::Search->new(
   satisfy_all => 1,
   session => $session,
   dataset => $ds,
 );
 
 # Search for an eprint with eprintid 23
 # (ought to use EPrints::DataObj::EPrint->new( SESSION, ID ))
 $searchexp->add_field( $ds->get_field( "eprintid" ), 23 );
 
 $searchexp->add_field( $ds->get_field( "creators" ), "John Smith" );
 

User Comments


Getting Results

 $results = $searchexp->perform_search;
 
 my $count = $results->count;
 
 my $ids = $results->ids( 0, 10 );
 my $ids = $results->ids; # Get all matching ids
 
 my $info = { matches => 0 };
 sub fn {
   my( $session, $dataset, $eprint, $info ) = @_;
   $info->{matches}++;
 };
 $results->map( \&fn, $info );
 
 $results->dispose;
 

See EPrints::List for more.

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


session (required)

The current EPrints::Session

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

Search fields can also be added to the search expression after it has been constructed.

User Comments


order

The order the results should be returned. This is a key to the list of orders available to this dataset, defined in ArchiveConfig.pm

User Comments


custom_order

"order" limits you to the orders specified in ArchiveConfig, 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


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

Populate this search expression with values from the given cache.

Return false if the cache does not exist.

User Comments


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

Adds a new search in $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


$searchfield = $searchexp->get_searchfield( $sf_id )

Return a EPrints::Search::Field belonging to this Search with the given id.

Return undef if not searchfield of that ID belongs to this search.

User Comments


$searchexp->clear

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

Resets satisfy_all to true.

User Comments


$bool = $searchexp->get_satisfy_all

Return true if this search requires that all the search fields with values are satisfied.

User Comments


$boolean = $searchexp->is_blank

Return true is this searchexpression has no conditions set, otherwise true.

If any field is set to "exact" then it can never count as unset.

User Comments


$string = $searchexp->serialise

Return a text representation of the search expression, for persistent storage. Doesn't store table or the order by fields, just the field names, values, default order and satisfy_all.

User Comments


$searchexp->from_string( $string )

Unserialises the contents of $string but only into the fields alrdeady existing in $searchexp. Set the order and satisfy_all mode but do not affect the dataset or allow blank.

User Comments


$newsearchexp = $searchexp->clone

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

User Comments


$conditions = $searchexp->get_conditons

Return a tree of EPrints::Search::Condition objects describing the simple steps required to perform this search.

User Comments


$dataset = $searchexp->get_dataset

Return the EPrints::DataSet which this search relates to.

User Comments


$searchexp->set_dataset( $dataset )

Set the EPrints::DataSet which this search relates to.

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


@search_fields = $searchexp->get_searchfields()

Return the EPrints::Search::Field objects relating to this search.

User Comments


@search_fields = $searchexp->get_non_filter_searchfields();

Return the EPrints::Search::Field objects relating to this search, which are normal search fields, and not "filters".

User Comments


@search_fields = $searchexp->get_set_searchfields

Return the searchfields belonging to this search expression which have a value set.

User Comments


$cache_id = $searchexp->get_cache_id

Return the ID of the cache containing the results of this search, if known.

User Comments


$results = $searchexp->perform_search

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

User Comments


($values, $counts) = $searchexp->perform_groupby( $field )

Perform a SQL GROUP BY on $field based on the current search parameters.

Returns two array references, one containing a list of unique values and one a list of counts for each value.

User Comments


$hash = $searchexp->get_ids_by_field_values( $field )

Find the ids for each unique value in $field.

User Comments