|
|
| Line 1: |
Line 1: |
| − | <!-- Pod2Wiki=_preamble_
| |
| − | This page has been automatically generated from the EPrints source. Any wiki changes made between the 'Pod2Wiki=*' and 'End of Pod2Wiki' comments will be lost.
| |
| − | -->{{Pod2Wiki}}{{API:Source|file=EPrints/Search.pm|package_name=EPrints::Search}}[[Category:API|Search]]<!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=head_name -->=NAME=
| |
| − | '''EPrints::Search''' - Represents a single search
| |
| | | | |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=head_description -->=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 [[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.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=head_examples -->=EXAMPLES=
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=head_searching_for_eprints -->==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" );
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=head_getting_results -->==Getting Results==
| |
| − | $results = $searchexp->perform_search;
| |
| − |
| |
| − | my $count = $searchexp->count;
| |
| − | my $count = $results->count;
| |
| − |
| |
| − | my $ids = $results->get_ids( 0, 10 );
| |
| − | my $ids = $results->get_ids; # Get all matching ids
| |
| − |
| |
| − | my $info = { matches => 0 };
| |
| − | sub fn {
| |
| − | my( $session, $dataset, $eprint, $info ) = @_;
| |
| − | $info->{matches}++;
| |
| − | };
| |
| − | $results->map( \&fn, $info );
| |
| − |
| |
| − | $searchexp->dispose;
| |
| − |
| |
| − | See [[API:EPrints/List|EPrints::List]] for more.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=head_methods -->=METHODS=
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_new -->==new==
| |
| − |
| |
| − | $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
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_session -->==session==
| |
| − |
| |
| − | session (required)
| |
| − |
| |
| − | The current [[API:EPrints/Session|EPrints::Session]]
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_dataset_id -->==dataset_id==
| |
| − |
| |
| − | dataset OR dataset_id (required)
| |
| − |
| |
| − | Either the [[API:EPrints/DataSet|EPrints::DataSet]] to search, or the ID of it.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_allow_blank -->==allow_blank==
| |
| − |
| |
| − | allow_blank (default 0)
| |
| − |
| |
| − | Unless this is set, a search with no conditions will return zero records rather than all records.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_satisfy_all -->==satisfy_all==
| |
| − |
| |
| − | 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.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_search_fields -->==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.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_order -->==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
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_custom_order -->==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.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_keep_cache -->==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.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_cache_id -->==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.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_prefix -->==prefix==
| |
| − |
| |
| − | 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.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_staff -->==staff==
| |
| − |
| |
| − | 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.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_filters -->==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.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_from_cache -->==from_cache==
| |
| − |
| |
| − | $ok = $thing->from_cache( $id )
| |
| − |
| |
| − | Populate this search expression with values from the given cache.
| |
| − |
| |
| − | Return false if the cache does not exist.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_add_field -->==add_field==
| |
| − |
| |
| − | $searchfield = $searchexp->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.
| |
| − |
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_get_searchfield -->==get_searchfield==
| |
| − |
| |
| − | $searchfield = $searchexp->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.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_clear -->==clear==
| |
| − |
| |
| − | $searchexp->clear
| |
| − |
| |
| − | Clear the search values of all search fields in the expression.
| |
| − |
| |
| − | Resets satisfy_all to true.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_get_satisfy_all -->==get_satisfy_all==
| |
| − |
| |
| − | $bool = $searchexp->get_satisfy_all
| |
| − |
| |
| − | Return true if this search requires that all the search fields with values are satisfied.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_is_blank -->==is_blank==
| |
| − |
| |
| − | $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.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_serialise -->==serialise==
| |
| − |
| |
| − | $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.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_from_string -->==from_string==
| |
| − |
| |
| − | $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.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_clone -->==clone==
| |
| − |
| |
| − | $newsearchexp = $searchexp->clone
| |
| − |
| |
| − | Return a new search expression which is a duplicate of this one.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_get_conditons -->==get_conditons==
| |
| − |
| |
| − | $conditions = $searchexp->get_conditons
| |
| − |
| |
| − | Return a tree of [[API:EPrints/Search/Condition|EPrints::Search::Condition]] objects describing the simple steps required to perform this search.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_get_dataset -->==get_dataset==
| |
| − |
| |
| − | $dataset = $searchexp->get_dataset
| |
| − |
| |
| − | Return the [[API:EPrints/DataSet|EPrints::DataSet]] which this search relates to.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_set_dataset -->==set_dataset==
| |
| − |
| |
| − | $searchexp->set_dataset( $dataset )
| |
| − |
| |
| − | Set the [[API:EPrints/DataSet|EPrints::DataSet]] which this search relates to.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_render_description -->==render_description==
| |
| − |
| |
| − | $xhtml = $searchexp->render_description
| |
| − |
| |
| − | Return an XHTML DOM description of this search expressions current parameters.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_render_conditions_description -->==render_conditions_description==
| |
| − |
| |
| − | $xhtml = $searchexp->render_conditions_description
| |
| − |
| |
| − | Return an XHTML DOM description of this search expressions conditions. ie title is "foo"
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_render_order_description -->==render_order_description==
| |
| − |
| |
| − | $xhtml = $searchexp->render_order_description
| |
| − |
| |
| − | Return an XHTML DOM description of how this search is ordered.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_set_property -->==set_property==
| |
| − |
| |
| − | $searchexp->set_property( $property, $value );
| |
| − |
| |
| − | Set any single property of this search, such as the order.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_get_searchfields -->==get_searchfields==
| |
| − |
| |
| − | @search_fields = $searchexp->get_searchfields()
| |
| − |
| |
| − | Return the [[API:EPrints/Search/Field|EPrints::Search::Field]] objects relating to this search.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_get_non_filter_searchfields -->==get_non_filter_searchfields==
| |
| − |
| |
| − | @search_fields = $searchexp->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".
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_get_set_searchfields -->==get_set_searchfields==
| |
| − |
| |
| − | @search_fields = $searchexp->get_set_searchfields
| |
| − |
| |
| − | Return the searchfields belonging to this search expression which have a value set.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_get_cache_id -->==get_cache_id==
| |
| − |
| |
| − | $cache_id = $searchexp->get_cache_id
| |
| − |
| |
| − | Return the ID of the cache containing the results of this search, if known.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_perform_search -->==perform_search==
| |
| − |
| |
| − | $results = $searchexp->perform_search
| |
| − |
| |
| − | Execute this search and return a [[API:EPrints/List|EPrints::List]] object representing the results.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_get_ids_by_field_values -->==get_ids_by_field_values==
| |
| − |
| |
| − | $hash = $searchexp->get_ids_by_field_values( $field )
| |
| − |
| |
| − | Find the ids for each unique value in $field.
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=head_undocumented_methods -->=UNDOCUMENTED METHODS=
| |
| − | {{API:Undocumented Methods}}<!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_cache_results -->==cache_results==
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_count -->==count==
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_dispose -->==dispose==
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_from_string_raw -->==from_string_raw==
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_get_conditions -->==get_conditions==
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_get_ids -->==get_ids==
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_get_records -->==get_records==
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=item_map -->==map==
| |
| − |
| |
| − | <!-- End of Pod2Wiki -->
| |
| − | <!-- Pod2Wiki=_postamble_ --><!-- End of Pod2Wiki -->
| |
