Difference between revisions of "API:EPrints/DataObj/SavedSearch"

From EPrints Documentation
Jump to: navigation, search
(New page: <!-- 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. -...)
 
 
(4 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
<!-- Pod2Wiki=_preamble_  
 
<!-- 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.
+
This page has been automatically generated from the EPrints 3.4 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
−
  -->{{Pod2Wiki}}{{API:Source|file=EPrints/DataObj/SavedSearch.pm|package_name=EPrints::DataObj::SavedSearch}}[[Category:API|SavedSearch]]<!-- End of Pod2Wiki -->
+
  -->{{API}}{{Pod2Wiki}}{{API:Source|file=EPrints/DataObj/SavedSearch.pm|package_name=EPrints::DataObj::SavedSearch}}[[Category:API|SAVEDSEARCH]][[Category:API:EPrints/DataObj|SAVEDSEARCH]]<div><!-- Edit below this comment -->
−
<!-- Pod2Wiki=head_name -->=NAME=
+
 
 +
 
 +
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
 +
==NAME==
 
'''EPrints::DataObj::SavedSearch''' - Single saved search.
 
'''EPrints::DataObj::SavedSearch''' - Single saved search.
  
−
<!-- End of Pod2Wiki -->
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<!-- Pod2Wiki=head_description -->=DESCRIPTION=
+
<span style='display:none'>User Comments</span>
−
A saved search is a sub class of EPrints::DataObj.
+
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_description -->
 +
==DESCRIPTION==
 +
A saved search is a sub class of [[API:EPrints/DataObj/SubObject|EPrints::DataObj::SubObject]].
  
 
Each one belongs to one and only one user, although one user may own multiple saved searches.
 
Each one belongs to one and only one user, although one user may own multiple saved searches.
  
−
<!-- End of Pod2Wiki -->
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<!-- Pod2Wiki=item_get_system_field_info -->==get_system_field_info==
+
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_core_metadata_fields -->
 +
==CORE METADATA FIELDS==
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_id -->
 +
===id (counter)===
 +
 
 +
The ID of the saved search,
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_name -->
 +
===name (text)===
 +
 
 +
A name assigned to the saved search.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_spec -->
 +
===spec (search)===
 +
 
 +
A serialization of the search specification.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_frequency -->
 +
===frequency (set)===
 +
 
 +
How often to send saves search email updates.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_mailempty -->
 +
===mailempty (boolean)===
 +
 
 +
Whether to send saved search  email updates if there are no results.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_additional_recipients -->
 +
===additional_recipients (text)===
 +
 
 +
Additional email addresses to send updates about saved search results.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_public -->
 +
===public (boolean)===
 +
 
 +
If the saved search results should be publicly accessible.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_references_and_related_objects -->
 +
==REFERENCES AND RELATED OBJECTS==
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_userid -->
 +
===userid (itemref)===
 +
 
 +
The ID of the user to whom created this saved search.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_instance_variables -->
 +
==INSTANCE VARIABLES==
 +
Also see [[API:&lt;EPrints/DataObj#INSTANCE_VARIABLES|EPrints::DataObj]].
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_$self->{user} -->
 +
===$self-&gt;{user}===
 +
 
 +
The user who owns this saved search.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_methods -->
 +
==METHODS==
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_constructor_methods -->
 +
===Constructor Methods===
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_create -->
 +
====create====
 +
 
 +
$saved_search = EPrints::DataObj::SavedSearch-&gt;create( $session, $userid )
 +
Creates a new saved search, belonging to user with ID <tt>$userid</tt>.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_class_methods -->
 +
===Class Methods===
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_get_system_field_info -->
 +
====get_system_field_info====
 +
 
 +
$field_config = EPrints::DataObj::SavedSearch-&gt;get_system_field_info
 +
Returns an array describing the system metadata of the saved search  dataset.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_get_dataset_id -->
 +
====get_dataset_id====
 +
 
 +
$dataset = EPrints::DataObj::SavedSearch-&gt;get_dataset_id
 +
Returns the ID of the [[API:EPrints/DataSet|EPrints::DataSet]] object to which this record  belongs.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_object_methods -->
 +
===Object Methods===
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_get_dataset -->
 +
====get_dataset====
 +
 
 +
$dataset = $saved_search-&gt;get_dataset
 +
Get the dataset that this saved search covers.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_commit -->
 +
====commit====
 +
 
 +
$success = $saved_search-&gt;commit( [ $force ] )
 +
Writes this object to the database.
 +
 
 +
If <tt>$force</tt> is not true then it only actually modifies the database if one or more fields have been changed.
 +
 
 +
Returns <tt>true</tt> if commit was successfully. Otherwise, returns  <tt>false</tt>.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_get_user -->
 +
====get_user====
 +
 
 +
$user = $saved_search-&gt;get_user
 +
Returns the <tt>EPrints::DataObj::User</tt> which owns this saved search.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
−
  $field_config = EPrints::DataObj::SavedSearch-&gt;get_system_field_info
 
  
−
Return an array describing the system metadata of the saved search. dataset.
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_make_searchexp -->
 +
====make_searchexp====
  
−
<!-- End of Pod2Wiki -->
+
$searchexp = $saved_search-&gt;make_searchexp
−
<!-- Pod2Wiki=item_new -->==new==
+
Returns an [[API:EPrints/Search|EPrints::Search]] describing how to find the data objects which are in the scope of this saved search.
  
−
  $saved_search = EPrints::DataObj::SavedSearch-&gt;new( $session, $id )
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
−
Return new Saved Search object, created by loading the Saved Search with id $id from the database.
 
  
−
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=item_new_from_data -->==new_from_data==
+
</div>
 +
<!-- Pod2Wiki=item_send_out_alert -->
 +
====send_out_alert====
  
−
  $saved_search = EPrints::DataObj::SavedSearch-&gt;new_from_data( $session, $data )
+
$saved_search-&gt;send_out_alert
 +
Sends out an email for this subscription. If there are no matching new data objects then an email is only sent if the saved search has  <tt>mailempty</tt> set to <tt>true</tt>.
  
−
Construct a new EPrints::DataObj::SavedSearch object based on the $data hash  reference of metadata.
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_defaults -->==get_defaults==
 
  
−
  $defaults = EPrints::DataObj::SavedSearch-&gt;get_defaults( $session, $data )
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_has_owner -->
 +
====has_owner====
  
−
Return default values for this object based on the starting data.
+
$boolean = $saved_search-&gt;has_owner( $possible_owner )
 +
Returns <tt>true</tt> if <tt>$possible_owner</tt> is the same as the owner of this saved search. Otherwise, returns <tt>false</tt>.
  
−
<!-- End of Pod2Wiki -->
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<!-- Pod2Wiki=item_remove -->==remove==
+
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
−
  $success = $saved_search-&gt;remove
 
  
−
Remove the saved search.
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_parent -->
 +
====parent====
  
−
<!-- End of Pod2Wiki -->
+
$parent = $saved_search-&gt;parent
−
<!-- Pod2Wiki=item_commit -->==commit==
+
Returns the parent data object for this saved search. I.e. the user  who owns this saved search.  This is similar to [[API:EPrints/DataObj/SavedSearch#get_user|get_user]] but is  not as fault tolerant and does set instance variable:
  
−
  $success = $saved_search-&gt;commit( [$force] )
+
$self-&gt;{user}
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
−
Write this object to the database.
 
  
−
If $force isn't true then it only actually modifies the database if one or more fields have been changed.
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_get_url -->
 +
====get_url====
  
−
<!-- End of Pod2Wiki -->
+
$url = $saved_search-&gt;get_url( [ $staff ] )
−
<!-- Pod2Wiki=item_get_user -->==get_user==
+
Gets the URL for this saved search.  Currently <tt>$staff</tt> will not  effect the URL but in future this may return a specialised URL for  staff only.
  
−
  $user = $saved_search-&gt;get_user
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
−
Return the EPrints::User which owns this saved search.
 
  
−
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=item_make_searchexp -->==make_searchexp==
+
</div>
 +
<!-- Pod2Wiki=head_utility_methods -->
 +
===Utility Methods===
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
−
  $searchexp = $saved_search-&gt;make_searchexp
 
  
−
Return a EPrints::Search describing how to find the eprints which are in the scope of this saved search.
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_process_set -->
 +
====process_set====
  
−
<!-- End of Pod2Wiki -->
+
EPrints::DataObj::SavedSearch::process_set( $session, $frequency );
−
<!-- Pod2Wiki=item_send_out_alert -->==send_out_alert==
+
Static method.
  
−
  $saved_search-&gt;send_out_alert
+
Calls <tt>send_out_alert</tt> on every saved search with a frequency  matching <tt>$frequency</tt>.
  
−
Send out an email for this subcription. If there are no matching new items then an email is only sent if the saved search has mailempty set to true.
+
Also saves a file logging that the alerts for this frequency was sent out at the current time.
  
−
<!-- End of Pod2Wiki -->
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
<!-- Pod2Wiki=item_process_set -->==process_set==
+
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
−
  EPrints::DataObj::SavedSearch::process_set( $session, $frequency );
 
  
−
Static method. Calls send_out_alert on every saved search  with a frequency matching $frequency.
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_get_last_timestamp -->
 +
====get_last_timestamp====
  
−
Also saves a file logging that the alerts for this frequency was sent out at the current time.
+
$timestamp = EPrints::DataObj::SavedSearch::get_last_timestamp( $session, $frequency );
 +
Static method.
  
−
<!-- End of Pod2Wiki -->
+
Return sthe timestamp of the last time this <tt>$frequency</tt> of alert was  sent.
−
<!-- Pod2Wiki=item_get_last_timestamp -->==get_last_timestamp==
 
  
−
  $timestamp = EPrints::DataObj::SavedSearch::get_last_timestamp( $session, $frequency );
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
−
Static method. Return the timestamp of the last time this frequency  of alert was sent.
 
  
−
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=item_has_owner -->==has_owner==
+
</div>
 +
<!-- Pod2Wiki=head_see_also -->
 +
==SEE ALSO==
 +
[[API:EPrints/DataObj/SubObject|EPrints::DataObj::SubObject]], [[API:EPrints/DataObj|EPrints::DataObj]] and  [[API:EPrints/DataSet|EPrints::DataSet]].
  
−
  $boolean = $user-&gt;has_owner( $possible_owner )
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
−
True if the users are the same record.
 
  
−
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=head_undocumented_methods -->=UNDOCUMENTED METHODS=
+
</div>
−
{{API:Undocumented Methods}}<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki=head_copyright -->
−
<!-- Pod2Wiki=item_create -->==create==
+
==COPYRIGHT==
 +
{{API:Copyright}}
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_url -->==get_url==
 
  
−
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=_postamble_ --><!-- End of Pod2Wiki -->
+
</div>
 +
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->

Latest revision as of 17:29, 10 January 2022

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::DataObj::SavedSearch - Single saved search.

User Comments


DESCRIPTION

A saved search is a sub class of EPrints::DataObj::SubObject.

Each one belongs to one and only one user, although one user may own multiple saved searches.

User Comments


CORE METADATA FIELDS

User Comments


id (counter)

The ID of the saved search,

User Comments


name (text)

A name assigned to the saved search.

User Comments


spec (search)

A serialization of the search specification.

User Comments


frequency (set)

How often to send saves search email updates.

User Comments


mailempty (boolean)

Whether to send saved search email updates if there are no results.

User Comments


additional_recipients (text)

Additional email addresses to send updates about saved search results.

User Comments


public (boolean)

If the saved search results should be publicly accessible.

User Comments


REFERENCES AND RELATED OBJECTS

User Comments


userid (itemref)

The ID of the user to whom created this saved search.

User Comments


INSTANCE VARIABLES

Also see [[API:<EPrints/DataObj#INSTANCE_VARIABLES|EPrints::DataObj]].

User Comments


$self->{user}

The user who owns this saved search.

User Comments


METHODS

User Comments


Constructor Methods

User Comments


create

$saved_search = EPrints::DataObj::SavedSearch->create( $session, $userid )

Creates a new saved search, belonging to user with ID $userid.

User Comments


Class Methods

User Comments


get_system_field_info

$field_config = EPrints::DataObj::SavedSearch->get_system_field_info

Returns an array describing the system metadata of the saved search dataset.

User Comments


get_dataset_id

$dataset = EPrints::DataObj::SavedSearch->get_dataset_id

Returns the ID of the EPrints::DataSet object to which this record belongs.

User Comments


Object Methods

User Comments


get_dataset

$dataset = $saved_search->get_dataset

Get the dataset that this saved search covers.

User Comments


commit

$success = $saved_search->commit( [ $force ] )

Writes this object to the database.

If $force is not true then it only actually modifies the database if one or more fields have been changed.

Returns true if commit was successfully. Otherwise, returns false.

User Comments


get_user

$user = $saved_search->get_user

Returns the EPrints::DataObj::User which owns this saved search.

User Comments


make_searchexp

$searchexp = $saved_search->make_searchexp

Returns an EPrints::Search describing how to find the data objects which are in the scope of this saved search.

User Comments


send_out_alert

$saved_search->send_out_alert

Sends out an email for this subscription. If there are no matching new data objects then an email is only sent if the saved search has mailempty set to true.

User Comments


has_owner

$boolean = $saved_search->has_owner( $possible_owner )

Returns true if $possible_owner is the same as the owner of this saved search. Otherwise, returns false.

User Comments


parent

$parent = $saved_search->parent

Returns the parent data object for this saved search. I.e. the user who owns this saved search. This is similar to get_user but is not as fault tolerant and does set instance variable: 

$self->{user}

User Comments


get_url

$url = $saved_search->get_url( [ $staff ] )

Gets the URL for this saved search. Currently $staff will not effect the URL but in future this may return a specialised URL for staff only.

User Comments


Utility Methods

User Comments


process_set

EPrints::DataObj::SavedSearch::process_set( $session, $frequency );

Static method.

Calls send_out_alert on every saved search with a frequency matching $frequency.

Also saves a file logging that the alerts for this frequency was sent out at the current time.

User Comments


get_last_timestamp

$timestamp = EPrints::DataObj::SavedSearch::get_last_timestamp( $session, $frequency );

Static method.

Return sthe timestamp of the last time this $frequency of alert was sent.

User Comments


SEE ALSO

EPrints::DataObj::SubObject, EPrints::DataObj and EPrints::DataSet.

User Comments


COPYRIGHT

© Copyright 2023 University of Southampton.

EPrints 3.4 is supplied by EPrints Services.

http://www.eprints.org/eprints-3.4/

LICENSE

This file is part of EPrints 3.4 http://www.eprints.org/.

EPrints 3.4 and this file are released under the terms of the GNU Lesser General Public License version 3 as published by the Free Software Foundation unless otherwise stated.

EPrints 3.4 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 3.4. If not, see http://www.gnu.org/licenses/.

User Comments


Retrieved from ‘https://wiki.eprints.org/w/index.php?title=API:EPrints/DataObj/SavedSearch&oldid=14167’