API:EPrints/Search/Field

From EPrints Documentation
Jump to: navigation, 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::Field - one criteria in a search expression.


DESCRIPTION

This class represents a single criteria in a EPrints::Search and by extension a search form.

It can search over several EPrints::MetaFields, and the value of the search field is usually a string containing a list of whitespace separated words.

A search field has four key parameters:

1. The list of the metadata fields it searches.

2. The value to search for.

3. The "match" parameter which can be one of:

  • match=IN (index)
Treat the value as a list of whitespace-seperated words. Search for each one in the full-text index.
In the case of subjects, match these subject ids or the those of any of their decendants in the subject tree.
  • match=EQ (equal)
Treat the value as a single string. Match only fields which have this value.
  • match=EX (exact)
If the value is an empty string then search for fields which are empty, as oppose to skipping this search field.
In the case of subjects, match the specified subjects, but not their decendants.
  • match=SET
If the value is non-empty.
  • match=NO
This is only really used internally, it means the search field will just fail to match anything without doing any actual searching.

4. the "merge" parameter which can be one of:

  • merge=ANY
Match an item if any of the space-separated words in the value match.
  • merge=ALL
Match an item only if all of the space-separated words in the value match.

Merge has no affect on EX matches, which always match the entire value.


METHODS

$sf = EPrints::Search::Field->new( %opts )

  repository
  dataset
  fields - field or fields to search
  value - value to search for
  match
  merge
  prefix
  show_help
  id
$thing = EPrints::Search::Field->new( $session, $dataset, $fields, $value, [$match], [$merge], [$prefix], [$show_help] )

Create a new search field object (%opts form is preferred).

$prefix is used when generating HTML forms and reading values from forms.

$fields is a reference to an array of EPrints::MetaField objects.

$match is one of EQ, IN, EX. default is EQ.

$merge is ANY or ALL. default is ALL

Special case - if match is "EX" and field type is name then value must be a name hash.

$show_help is used to control if the help shows up on the search form. A value of "always" shows the help without the show/hide toggle. "never" shows no help and no toggle. "toggle" shows no help, but shows the [?] icon which will reveal the help. The default is "toggle". If javascript is off, toggle will show the help and show no toggle.

If match and merge are not explicitly provided the properties of the first field in the fields will be used. If you are performing a multi-field search you probably want to explicitly set the search type to "IN" (index). 

$sf->clear

Set this searchfield's "match" to "NO" so that it always returns nothing when searched. 

$problem = $sf->from_form

Modify the value, merge and match parameters of this field based on results from an HTML form.

Return undef if everything is OK, otherwise return a ref to an array containing the problems as XHTML DOM objects. 

$search_condition = $sf->get_conditions

Convert this Search::Field into an EPrints::Search::Condition object which can actually perform the search. 

$value = $sf->get_value

Return the current value parameter of this search field.

Do not do EPrints::Utils::is_set($sf-get_value)> to test whether the search field is set, see is_set for details. 

$match = $sf->get_match

Return the current match parameter of this search field. 

$merge = $sf->get_merge

Return the current merge parameter of this search field. 

$field = $sf->get_field

Return the first of the metafields which we are searching. This is used for establishing the type of the search field. If this metafield has special input rendering methods then they will be used for this search field. 

$fields = $sf->get_fields

Return a reference to an array of EPrints::MetaField objects which this search field is going to search. 

$xhtml = $sf->render

Returns an XHTML tree of this search field which contains all the input boxes required to search this field. 

$xhtml = $sf->get_form_prefix

Return the string use to prefix form field names so values don't get mixed with other search fields. 

$xhtml = $sf->render_description

Returns an XHTML DOM object describing this field and its current settings. Used at the top of the search results page to describe the search. 

$xhtml_name = $sf->render_name

Return XHTML object of this searchfields name. 

$xhtml_help = $sf->render_help

Return an XHTML DOM object containing the "help" for this search field. 

$boolean = $sf->is_type( @types )

Return true if the first metafield in the fieldlist is of any of the types in @types. 

$id = $sf->get_id

Return the string ID of this searchfield. It is the "id" specified when the string was configured, or failing that the names of all the metafields it searches, joined with a slash "/". 

$boolean = $sf->is_set

Returns true if this search field has a value to search.

For "EX" matches this will always return true unless the %opts form of the constructor was used without a value option. This is because "" is a valid search value in "EX" searches (but by EPrints definitions is "not set"). 

$string = $sf->serialise

Serialise the parameters of this search field into a string. 

$sf = EPrints::Search::Field->unserialise( %opts )

  repository
  dataset
  string

Convert a serialised searchfield back into a search field. 

$boolean  = $sf->get_include_in_description

Change the dataset of this searchfield. This is probably a bad idea, except moving between two datasets with the same confid. eg. buffer and inbox. 

$sf->set_include_in_description( $boolean )

If set to zero then this search field will not be included in descriptions of the search. 

$sf->set_dataset( $datasetid )

Change the dataset of this searchfield. This is probably a bad idea, except moving between two datasets with the same confid. eg. buffer and inbox.


COPYRIGHT

Copyright 2000-2013 University of Southampton.

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



Retrieved from ‘https://wiki.eprints.org/w/index.php?title=API:EPrints/Search/Field&oldid=10813’