EPrints Documentation - User contributions [en-gb]

API:EPrints/Config

2013-07-30T14:59:48Z

Tdb01r:

API:EPrints/Config

2013-07-30T14:58:22Z

Tdb01r:

API:EPrints/Config

2013-07-30T14:56:43Z

Tdb01r:

API:EPrints/Repository

2013-07-30T14:39:33Z

Tdb01r:

{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/Repository.pm|package_name=EPrints::Repository}}[[Category:API|REPOSITORY]][[Category:API:EPrints/Repository|REPOSITORY]]<div>


==NAME==
EPrints::Repository - connection to a single repository instance





==SYNOPSIS==
<source lang="perl">use EPrints;

$repo = EPrints->new->current_repository;

$repo = EPrints->new->repository( "myrepo" );

$xml = $repo->xml;
$cuser = $repo->current_user;
$repo->log( "Got user " . $cuser->id );</source>





==DESCRIPTION==
EPrints::Repository represents a connection to the EPrints system. It connects to a single EPrints repository, and the database used by that repository.

Each Repository has a "current language". If you are running in a multilingual mode, this is used by the HTML rendering functions to choose what language to return text in.

The Repository object also knows about the current apache connection, if there is one, including the CGI parameters.

If the connection requires a username and password then it can also give access to the [[API:EPrints/DataObj/User|EPrints::DataObj::User]] object representing the user who is causing this request. See [[API:EPrints/Repository#current_user|current_user]].

The Repository object provides access to the [[API:EPrints/XML|EPrints::XML]] and [[API:EPrints/XHTML|EPrints::XHTML]] class which contain methods for creating XHTML results which can be returned via the web interface.





==METHODS==

===new===

<source lang="perl">$repository = EPrints::Repository->new( %opts )

</source>
Creates and returns a new repository object. This is a utility object only and will only have the basic system configuration available.





===new===

<source lang="perl">$repository = EPrints::Repository->new( $repository_id, %opts )

</source>
Create a connection to an EPrints repository $repository_id which provides access to the database and to the repository configuration.

Options:

<pre> db_connect - 1
check_db - 1
noise - 0</pre>





===create_from_data===

<source lang="perl">$repo = EPrints::Repository->create_from_data( $epdata )

</source>
Create a new repository instance using $epdata.





===delete===

<source lang="perl">$repo->delete()

</source>
Destroy the repository and all its contents.

To allow this method you must first set $EPrints::Repository::ALLOW_DELETE to 1.





===query===

<source lang="perl">$query = $repository->query

</source>
Return the {{API:PodLink|file=CGI|package_name=CGI|section=|text=CGI}} object describing the current HTTP query, or undefined if this isn't a CGI script.





===url_param===

<source lang="perl">$value or @values = $repository->url_param( $name )

</source>
Retrieve the UTF-8 value(s) of the query parameter $name for the current request.

This will not cause the POST data to be read.





===param===

<source lang="perl">$value or @values = $repository->param( $name )

</source>
Passes through to CGI.pm param method.

$value = $repository->param( $name ): returns the value of CGI parameter $name.

@values = $repository->param: returns an array of the names of all the CGI parameters in the current request.





===xml===

<source lang="perl">$xml = $repo->xml

</source>
Return an [[API:EPrints/XML|EPrints::XML]] object for working with XML.





===xhtml===

<source lang="perl">$xhtml = $repo->xhtml

</source>
Return an [[API:EPrints/XHTML|EPrints::XHTML]] object for working with XHTML.





===eprint===

<source lang="perl">$eprint = $repository->eprint( $eprint_id );

</source>
A convience method to return the [[API:EPrints/DataObj/EPrint|EPrints::DataObj::EPrint]] with the given ID, or undef.

Equivent to $repository->dataset("eprint")->dataobj( $eprint_id )





===current_language===

<source lang="perl">$lang = $repository->current_language

</source>
Returns the current language.





===current_user===

<source lang="perl">$user = $repository->current_user

</source>
Return the current logged in [[API:EPrints/DataObj/User|EPrints::DataObj::User]] for this session.

Return undef if there isn't one.





===user===

<source lang="perl">$user = $repository->user( $user_id );

</source>
A convience method to return the [[API:EPrints/DataObj/User|EPrints::DataObj::User]] with the given ID, or undef.

Equivent to $repository->dataset("user")->dataobj( $user_id )





===user_by_username===

<source lang="perl">$user = $repository->user_by_username( $username );

</source>
Return the user with the given username, or undef.





===user_by_email===

<source lang="perl">$user = $repository->user_by_email( $email );

</source>
Return the [[API:EPrints/DataObj/User|EPrints::DataObj::User]] with the given email, or undef.





===template===

<source lang="perl">$template = $repository->template( [ $id ] )

</source>




===dataset===

<source lang="perl">$dataset = $repository->dataset( $setname )

</source>
Return a given [[API:EPrints/DataSet|EPrints::DataSet]] or undef if it doesn't exist.





===config===

<source lang="perl">$confitem = $repository->config( $key, [@subkeys] )

</source>
Returns a named configuration setting including those defined in archvies/<archive_id>/cfg/cfg.d/

$repository->config( "stuff", "en", "foo" )

is equivalent to

$repository->config( "stuff" )->{en}->{foo}





===log===

<source lang="perl">$repository->log( $msg [, $level ] )

</source>
Log a plain text message $msg. If $level is given only logs if $level is greater than or equal to [[API:EPrints/Repository#noise|noise]].

To override where log messages are sent define the <code>log</code> callback:

<pre> $c->{log} = sub {
my( $repo, $msg, $level ) = @_;

...
};</pre>





===call===

<source lang="perl">$result = $repository->call( $cmd, @params )

</source>
Calls the subroutine named $cmd from the configuration perl modules for this repository with the given params and returns the result.





===can_call===

<source lang="perl">$boolean = $repository->can_call( @cmd_conf_path )

</source>
Return true if the given subroutine exists in this repository's config package.





===try_call===

<source lang="perl">$result = $repository->try_call( $cmd, @params )

</source>
Calls the subroutine named $cmd from the configuration perl modules for this repository with the given params and returns the result.

If the subroutine does not exist then quietly returns undef.

This is used to call deprecated callback subroutines.





===template_dirs===

<source lang="perl">@dirs = $repository->template_dirs( $langid )

</source>
Returns a list of directories from which template files may be sourced, where the first matching template encountered is used.

The directories searched are:

<pre> archives/[archiveid]/cfg/lang/[langid]/templates/
archives/[archiveid]/cfg/templates/
archives/[archiveid]/cfg/themes/[themeid]/lang/[langid]/templates/
archives/[archiveid]/cfg/themes/[themeid]/templates/
lib/themes/[themeid]/templates/
lib/lang/[langid]/templates/
lib/templates/</pre>





===get_static_dirs===

<source lang="perl">@dirs = $repository->get_static_dirs( $langid )

</source>
Returns a list of directories from which static files may be sourced.

Directories are returned in order of importance, most important first:

<pre> archives/[archiveid]/cfg/lang/[langid]/static
archives/[archiveid]/cfg/static
archives/[archiveid]/themes/[themeid]/static
lib/themes/[themeid]/static
lib/lang/[langid]/static
lib/static</pre>





===id===

<source lang="perl">$id = $repository->id

</source>
Returns the id string of this repository.





===exec===

<source lang="perl">$returncode = $repository->exec( $cmd_id, %map )

</source>
Executes a system command. $cmd_id is the id of the command as set in SystemSettings and %map contains a list of things to "fill in the blanks" in the invocation line in SystemSettings.





===test_config===

<source lang="perl">( $returncode, $output) = $repository->test_config

</source>
This runs "epadmin test" as an external script to test if the current configuraion on disk loads OK. This can be used by the web interface to test if changes to config. files may be saved, or not.

$returncode will be zero if everything seems OK.

If not, then $output will contain the output of epadmin test





===reload_config===

<source lang="perl">$ok = $repository->reload_config

</source>
Trigger a configuration reload on the next request/index.

To reload the configuration right now just call [[API:EPrints/Repository#load_config|load_config]].





===html_phrase===

<source lang="perl">$xhtml_phrase = $repository->html_phrase( $phraseid, %inserts )

</source>
Return an XHTML DOM object describing a phrase from the phrase files.

$phraseid is the id of the phrase to return. If the same ID appears in both the repository-specific phrases file and the system phrases file then the repository-specific one is used.

If the phrase contains <ep:pin> elements, then each one should have an entry in %inserts where the key is the "ref" of the pin and the value is an XHTML DOM object describing what the pin should be replaced with.





===phrase===

<source lang="perl">$utf8_text = $repository->phrase( $phraseid, %inserts )

</source>
Performs the same function as html_phrase, but returns plain text.

All HTML elements will be removed, <br> and <p> will be converted into breaks in the text. <img> tags will be replaced with their "alt" values.





===noise===

<source lang="perl">$noise_level = $repository->noise

</source>
Return the noise level for the current session. See the explaination under EPrints::Repository->new()





===plugins===

<source lang="perl">@plugins = $repository->plugins( [ $params, ] %restrictions )

</source>
Returns a list of plugin objects that conform to %restrictions (may be empty).

If $params is given uses that hash reference to initialise the plugins. Always passes this session to the plugin constructor method.





===init_from_indexer===

<source lang="perl">$repo->init_from_indexer( $daemon )

</source>
(Re)initialise the repository object for use by the indexer.

Calls [[API:EPrints/Repository#check_last_changed|check_last_changed]].


==COPYRIGHT==
Copyright 2000-2011 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/.

API:EPrints/Plugin/InputForm/Component

2013-07-29T12:45:23Z

Tdb01r:

API:EPrints/Plugin/InputForm/Component

2013-07-29T12:45:07Z

Tdb01r:

API:EPrints/Plugin/InputForm/Component

2013-07-29T12:42:54Z

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…'

API:EPrints/Plugin/Screen

2013-07-29T09:47:22Z

Tdb01r:

API:EPrints/Plugin/Screen

2013-07-25T16:17:58Z

Tdb01r:

API:EPrints/Plugin/Screen

2013-07-25T15:57:59Z

Tdb01r:

API:EPrints/Plugin/Screen

2013-07-25T15:26:56Z

API:EPrints/Plugin/Storage

2013-07-25T13:47:03Z

Tdb01r:

API:EPrints/Plugin/Storage

2013-07-25T13:42:41Z

API:EPrints/DataObj/File

2013-07-25T13:36:02Z

Tdb01r:

API:EPrints/DataObj/File

2013-07-25T13:34:28Z

Tdb01r:

API:EPrints/Storage

2013-07-25T13:34:21Z

Tdb01r:

API:EPrints/Storage

2013-07-25T09:51:00Z

Tdb01r:

API:EPrints/Plugin/Search/Xapian

2013-07-24T11:02:08Z

API:EPrints/Plugin/Search

2013-07-24T11:01:03Z

API:EPrints/Search

2013-07-24T11:00:21Z

Tdb01r:

{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/Search.pm|package_name=EPrints::Search}}[[Category:API|SEARCH]][[Category:API:EPrints/Search|SEARCH]]<div>


==NAME==
EPrints::Search - retrieve objects based on search criteria





==DESCRIPTION==
The Search object represents the conditions of a single search.

Executing a search 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.

[[API:EPrints/Plugin/Search|EPrints::Plugin::Search]] provides a pluggable architecture for searching EPrints.





==SYNOPSIS==




===Searching for Eprints===
<pre> $ds = $repo->dataset( "archive" );

# NB 'archive' is an implicit filter on eprint.status
$list = $ds->search(filters => [{
meta_fields => [qw( eprintid )], value => 23,
}]);

$list = $ds->search(search_fields => [{
meta_fields => [qw( creators_name )], value => "John Smith",
}]);

$searchexp = $ds->prepare_search();
$searchexp->add_field(
fields => [
$ds->field('creators_name')
],
value => "John Smith",
match => "EQ", # EQuals
);
$searchexp->add_field(
fields => [
$ds->field('title')
],
value => "eagle buzzard",
match => "IN", # INdex
);</pre>

See [[API:EPrints/DataSet|EPrints::DataSet]] for more API methods for constructing search objects.





===Getting Results===
<pre> $list = $searchexp->perform_search;

my $count = $list->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}++;
};
$list->map( \&fn, $info );</pre>

See [[API:EPrints/List|EPrints::List]] for more.





==METHODS==

===new===

<source lang="perl">$searchexp = EPrints::Search->new( %params )

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

* session (required)
: The current [[API:EPrints/Session|EPrints::Session]]

* dataset OR dataset_id (required)
: Either the [[API:EPrints/DataSet|EPrints::DataSet]] to search, or the ID of it.

* allow_blank (default 0)
: Unless this is set, a search with no conditions will return zero records rather than all records.

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

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

* 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

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

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

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

* limit
: Limit the number of matching records to limit.

WEB PAGE RELATED PARAMETERS

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

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

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





===from_cache===

<source lang="perl">$ok = $thing->from_cache( $id )

</source>
Populate this search expression with values from the given cache.

Return false if the cache does not exist.





===add_field===

<source lang="perl">$searchfield = $searchexp->add_field( %opts )

</source>
<pre> fields - one or more fields to search over
match - match type
merge - merge type
value - value to match against (for EX matches, NULL = is_null!)
id - search field id, if not the name of the first field
filter - is filter-type
show_help - show help in search input</pre>

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

See [[API:EPrints/Search/Field|EPrints::Search::Field]] for details on match/merge etc.





===clear===

<source lang="perl">$searchexp->clear

</source>
Clear the search values of all search fields in the expression.

Resets satisfy_all to true.





===get_satisfy_all===

<source lang="perl">$bool = $searchexp->get_satisfy_all

</source>
Return true if this search requires that all the search fields with values are satisfied.





===is_blank===

<source lang="perl">$boolean = $searchexp->is_blank

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





===serialise===

<source lang="perl">$string = $searchexp->serialise

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





===from_string===

<source lang="perl">$searchexp->from_string( $string )

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





===clone===

<source lang="perl">$newsearchexp = $searchexp->clone

</source>
Return a new search expression which is a duplicate of this one.





===get_conditons===

<source lang="perl">$conditions = $searchexp->get_conditons

</source>
Return a tree of [[API:EPrints/Search/Condition|EPrints::Search::Condition]] objects describing the simple steps required to perform this search.





===get_dataset===

<source lang="perl">$dataset = $searchexp->get_dataset

</source>
Return the [[API:EPrints/DataSet|EPrints::DataSet]] which this search relates to.





===set_dataset===

<source lang="perl">$searchexp->set_dataset( $dataset )

</source>
Set the [[API:EPrints/DataSet|EPrints::DataSet]] which this search relates to.





===render_description===

<source lang="perl">$xhtml = $searchexp->render_description

</source>
Return an XHTML DOM description of this search expressions current parameters.





===render_conditions_description===

<source lang="perl">$xhtml = $searchexp->render_conditions_description

</source>
Return an XHTML DOM description of this search expressions conditions. ie title is "foo"





===render_order_description===

<source lang="perl">$xhtml = $searchexp->render_order_description

</source>
Return an XHTML DOM description of how this search is ordered.





===set_property===

<source lang="perl">$searchexp->set_property( $property, $value );

</source>
Set any single property of this search, such as the order.





===get_searchfields===

<source lang="perl">@search_fields = $searchexp->get_searchfields()

</source>
Return the [[API:EPrints/Search/Field|EPrints::Search::Field]] objects relating to this search.





===get_non_filter_searchfields===

<source lang="perl">@search_fields = $searchexp->get_non_filter_searchfields();

</source>
Return the [[API:EPrints/Search/Field|EPrints::Search::Field]] objects relating to this search, which are normal search fields, and not "filters".





===get_set_searchfields===

<source lang="perl">@search_fields = $searchexp->get_set_searchfields

</source>
Return the searchfields belonging to this search expression which have a value set.





===get_cache_id===

<source lang="perl">$cache_id = $searchexp->get_cache_id

</source>
Return the ID of the cache containing the results of this search, if known.





===perform_search===

<source lang="perl">$results = $searchexp->perform_search

</source>
Execute this search and return a [[API:EPrints/List|EPrints::List]] object representing the results.





===perform_distinctby===

<source lang="perl">$ids_map = $searchexp->perform_distinctby( $fields )

</source>
Perform a DISTINCT on $fields to find all unique ids by value.





===perform_groupby===

<source lang="perl">($values, $counts) = $searchexp->perform_groupby( $field )

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





===get_ids_by_field_values===

<source lang="perl">$hash = $searchexp->get_ids_by_field_values( $field )

</source>
Find the ids for each unique value in $field.








==COPYRIGHT==
Copyright 2000-2011 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/.

API:EPrints/Search/Field

2013-07-24T10:59:30Z

Tdb01r:

API:EPrints/Search

2013-07-24T10:58:44Z

Tdb01r:

{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/Search.pm|package_name=EPrints::Search}}[[Category:API|SEARCH]][[Category:API:EPrints/Search|SEARCH]]<div>


==NAME==
EPrints::Search - retrieve objects based on search criteria





==DESCRIPTION==
The Search object represents the conditions of a single search.

Executing a search 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.

[[API:EPrints/Search/Plugin|EPrints::Search::Plugin]] provides a pluggable architecture for searching EPrints.





==SYNOPSIS==




===Searching for Eprints===
<pre> $ds = $repo->dataset( "archive" );

# NB 'archive' is an implicit filter on eprint.status
$list = $ds->search(filters => [{
meta_fields => [qw( eprintid )], value => 23,
}]);

$list = $ds->search(search_fields => [{
meta_fields => [qw( creators_name )], value => "John Smith",
}]);

$searchexp = $ds->prepare_search();
$searchexp->add_field(
fields => [
$ds->field('creators_name')
],
value => "John Smith",
match => "EQ", # EQuals
);
$searchexp->add_field(
fields => [
$ds->field('title')
],
value => "eagle buzzard",
match => "IN", # INdex
);</pre>

See [[API:EPrints/DataSet|EPrints::DataSet]] for more API methods for constructing search objects.





===Getting Results===
<pre> $list = $searchexp->perform_search;

my $count = $list->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}++;
};
$list->map( \&fn, $info );</pre>

See [[API:EPrints/List|EPrints::List]] for more.





==METHODS==

===new===

<source lang="perl">$searchexp = EPrints::Search->new( %params )

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

* session (required)
: The current [[API:EPrints/Session|EPrints::Session]]

* dataset OR dataset_id (required)
: Either the [[API:EPrints/DataSet|EPrints::DataSet]] to search, or the ID of it.

* allow_blank (default 0)
: Unless this is set, a search with no conditions will return zero records rather than all records.

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

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

* 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

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

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

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

* limit
: Limit the number of matching records to limit.

WEB PAGE RELATED PARAMETERS

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

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

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





===from_cache===

<source lang="perl">$ok = $thing->from_cache( $id )

</source>
Populate this search expression with values from the given cache.

Return false if the cache does not exist.





===add_field===

<source lang="perl">$searchfield = $searchexp->add_field( %opts )

</source>
<pre> fields - one or more fields to search over
match - match type
merge - merge type
value - value to match against (for EX matches, NULL = is_null!)
id - search field id, if not the name of the first field
filter - is filter-type
show_help - show help in search input</pre>

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

See [[API:EPrints/Search/Field|EPrints::Search::Field]] for details on match/merge etc.





===clear===

<source lang="perl">$searchexp->clear

</source>
Clear the search values of all search fields in the expression.

Resets satisfy_all to true.





===get_satisfy_all===

<source lang="perl">$bool = $searchexp->get_satisfy_all

</source>
Return true if this search requires that all the search fields with values are satisfied.





===is_blank===

<source lang="perl">$boolean = $searchexp->is_blank

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





===serialise===

<source lang="perl">$string = $searchexp->serialise

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





===from_string===

<source lang="perl">$searchexp->from_string( $string )

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





===clone===

<source lang="perl">$newsearchexp = $searchexp->clone

</source>
Return a new search expression which is a duplicate of this one.





===get_conditons===

<source lang="perl">$conditions = $searchexp->get_conditons

</source>
Return a tree of [[API:EPrints/Search/Condition|EPrints::Search::Condition]] objects describing the simple steps required to perform this search.





===get_dataset===

<source lang="perl">$dataset = $searchexp->get_dataset

</source>
Return the [[API:EPrints/DataSet|EPrints::DataSet]] which this search relates to.





===set_dataset===

<source lang="perl">$searchexp->set_dataset( $dataset )

</source>
Set the [[API:EPrints/DataSet|EPrints::DataSet]] which this search relates to.





===render_description===

<source lang="perl">$xhtml = $searchexp->render_description

</source>
Return an XHTML DOM description of this search expressions current parameters.





===render_conditions_description===

<source lang="perl">$xhtml = $searchexp->render_conditions_description

</source>
Return an XHTML DOM description of this search expressions conditions. ie title is "foo"





===render_order_description===

<source lang="perl">$xhtml = $searchexp->render_order_description

</source>
Return an XHTML DOM description of how this search is ordered.





===set_property===

<source lang="perl">$searchexp->set_property( $property, $value );

</source>
Set any single property of this search, such as the order.





===get_searchfields===

<source lang="perl">@search_fields = $searchexp->get_searchfields()

</source>
Return the [[API:EPrints/Search/Field|EPrints::Search::Field]] objects relating to this search.





===get_non_filter_searchfields===

<source lang="perl">@search_fields = $searchexp->get_non_filter_searchfields();

</source>
Return the [[API:EPrints/Search/Field|EPrints::Search::Field]] objects relating to this search, which are normal search fields, and not "filters".





===get_set_searchfields===

<source lang="perl">@search_fields = $searchexp->get_set_searchfields

</source>
Return the searchfields belonging to this search expression which have a value set.





===get_cache_id===

<source lang="perl">$cache_id = $searchexp->get_cache_id

</source>
Return the ID of the cache containing the results of this search, if known.





===perform_search===

<source lang="perl">$results = $searchexp->perform_search

</source>
Execute this search and return a [[API:EPrints/List|EPrints::List]] object representing the results.





===perform_distinctby===

<source lang="perl">$ids_map = $searchexp->perform_distinctby( $fields )

</source>
Perform a DISTINCT on $fields to find all unique ids by value.





===perform_groupby===

<source lang="perl">($values, $counts) = $searchexp->perform_groupby( $field )

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





===get_ids_by_field_values===

<source lang="perl">$hash = $searchexp->get_ids_by_field_values( $field )

</source>
Find the ids for each unique value in $field.








==COPYRIGHT==
Copyright 2000-2011 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/.

API:EPrints/Search/Field

2013-07-24T10:57:51Z

Tdb01r:

Installing EPrints 3 on Win32

2013-05-31T15:56:43Z

Tdb01r:

{{Installation}}
{{Version|since=3.2.1}}

This page contains notes concerning installing version EPrints 3.3 on Win32-based platforms. Windows is not a well-supported platform and these instructions are likely to go out of date, due to the complexity of getting a working Apache-Perl environment working.

==Requirements==

* Microsoft Windows XP or later
* Apache 2.0 or later
* MySQL 5 or later
* ModPerl 2.0 or later

For indexing and thumbnailing you will also need:

* [http://www.imagemagick.org/ ImageMagick]
* [http://www.foolabs.com/xpdf/ xpdf] (for the pdftotext utility)
* [http://gnuwin32.sourceforge.net/ GNU Win32 tools]

==Download EPrints Windows Installation Package (MSI)==

Download the latest Win32 build from the link at the top of this page - do not install this until ALL supporting software is in place and in the places outlined!

==Supporting Software==

===MySQL===

Download and install 64bit MySQL from http://dev.mysql.com/downloads/mysql/

During the MySQL configuration Wizard:

* Change default character set to '''Best support For Multilingualism'''

===Apache===

Download and install the 64bit Apache '''2.2''' from http://www.apachelounge.com/download/ to C:\Apache2.

* Add '''C:\Apache2\bin''' to the windows path environment variable. Failure to add this path will result with a missing libaprutil-1.dll error when you attempt to run EPrints.

===Perl===

Download and install the 64bit Strawberry Perl 5.16 from http://strawberryperl.com/ to C:\Strawberry

==Nod_Perl==

Download and install the 64bit mod_perl for Strawberry Perl 5.16 from http://people.apache.org/~stevehay/.

===Perl Modules===

At a command-prompt run:

> cpan install Win32-Daemon
> cpan install Win32-DriveInfo

===Indexing and Thumbnailing Tools===

To get indexing and thumbnailing working will require some configuration file changes.

When you have installed a tool you need to tell EPrints where to find it. Edit perl_lib\EPrints\SystemSettings.pm:

$EPrints::SystemSettings::conf = {
...,
executables => {
convert => '/ImageMagick/convert.exe',
pdftotext => '/xpdf/pdftotext.exe',
},
};

For a full list of tools look in lib\syscfg.d\executables.pl.

==Configuration==

Edit the Apache configuration file '''C:\Apache2\conf\httpd.conf''' and add below the last LoadModule line:

# LoadFile C:/perl/bin/perl510.dll # Not necessary?
LoadModule perl_module modules/mod_perl.so

And at the end of the file:

Include C:/eprints/cfg/apache.conf

==Getting Started==

To create the indexer service entries (EPrints 3.3+), as administrator run:

> perl C:\eprints\bin\indexer install

Before starting Apache configure a new repository, see [[Getting Started with EPrints 3]].

You will need to manually restart the indexer if you change the repository configuration.

API:EPrints/RepositoryConfig

2013-01-30T16:24:43Z

Tdb01r:

API:bin/indexer

2013-01-22T09:57:24Z

Tdb01r:

{{API}}{{Pod2Wiki}}{{API:Source|file=bin/indexer|package_name=bin/indexer}}[[Category:API|BIN/INDEXER]][[Category:API:bin/indexer|BIN/INDEXER]][[Category:API:bin/indexer|BIN/INDEXER]]<div>


==NAME==
'''indexer''' - Indexing daemon for EPrints





==SYNOPSIS==
'''indexer''' start ['''options''']

'''indexer''' stop

'''indexer''' status

'''indexer''' install

'''indexer''' uninstall

'''indexer''' debug

'''indexer''' --help





==DESCRIPTION==
This daemon runs in the background and creates index files for all eprints repositories.

Messages and errors are logged to /opt/eprints3/var/indexer.log unless you change the log options. If it appears to be having problems try raising the log level and examining the log.

Once every 24 hours, the indexer rolls the logs (up to logfile.5) and then starts again. See --rollcount for ways to customise this.





==OPTIONS==
* '''--help'''
: Print a brief help message and exit.

* '''--man'''
: Print the full manual page and then exit.

* '''--quiet'''
: Be vewwy vewwy quiet. This option will supress all output unless an error occurs.

* '''--force'''
: Start up, even if the PID file exists (implying another copy is running). This is useful for starting after a crash, but be carefully not to run to copies at once as BAD THINGS will happen.

* '''--verbose'''
: Explain in detail what is going on. May be repeated for greater effect.

* '''--clear'''
: Clear broken event queue items (items that are "inprogress" or "failed") before commencing.

* '''--retry'''
: Retry broken event queue items (items that are "inprogress" or "failed") before commencing.

* '''--logfile''' <em>filename</em>
: Log to <em>filename</em> rather than default indexer log.

* '''--loglevel''' <em>level</em>
: Set the level of detail to log. Level may be 0-6.

* '''--rollcount''' <em>number</em>
: Set the number of once-through logs that should be kept. If set to zero then indexer will never roll the logs but rather just keep writing to the main log.

* '''--respawn''' <em>seconds</em>
: Respawn the indexer every <em>seconds</em> (rolls the log files).

* '''--notdaemon'''
: Do not become a daemon, remain attached to the current terminal.

: Log goes to STDERR instead of the log file.

: Does not create a .pid file.

* '''--once'''
: Only clear the current queue of things needing indexing then exit.

* '''--version'''
: Output version information and exit.





==Making into a service ==
This has only been tested under redhat linux. It make work on other OS's, but not promise.

To make the indexer into a service which starts and stops on reboots etc. like httpd and mysqld do the following (as root):

<pre> ln -s /opt/eprints3/bin/epindexer /etc/init.d/epindexer
chkconfig --add epindexer
chkconfig epindexer on</pre>

The epindexer script runs as root, changes user to "eprints" (or whatever uid your eprints install runs as) and then calls indexer.

<pre></pre>





==COPYRIGHT==
Copyright 2000-2011 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 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 General Public License for more details.

You should have received a copy of the GNU General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.

API:bin/import

2013-01-22T09:57:24Z

Tdb01r:

API:bin/export

2013-01-22T09:57:23Z

Tdb01r:

{{API}}{{Pod2Wiki}}{{API:Source|file=bin/export|package_name=bin/export}}[[Category:API|BIN/EXPORT]][[Category:API:bin/export|BIN/EXPORT]][[Category:API:bin/export|BIN/EXPORT]]<div>


==NAME==
'''export''' - export some or all items in a dataset using an output plugin.





==SYNOPSIS==
'''export''' <em>repository_id</em> ['''options'''] <em>dataset</em>

'''export''' <em>repository_id</em> ['''options'''] <em>dataset</em> <em>plugin</em> [<em>objectid</em>] [<em>objectid...</em>]





==DESCRIPTION==
This command outputs a dataset in the selected format. The formats available depend on what Export plugins have been installed.

Some plugins only operate on lists (e.g. RSS), others only operate on single objects only. Some plugins act slightly differently in single-item only mode. For example, outputing a list of eprints as XML gives a number of <eprint> elements in an outer <eprints> element.

To get the plugin to export a single item use --single. This may not always return a complete file. For example it may be missing the <?xml header, depending on the plugin.





==ARGUMENTS==
* <em>repository_id</em>
: The ID of the EPrint repository to use.

* <em>dataset</em>
: The name of the dataset to export, such as "archive", "subject" or "user".

* <em>plugin</em>
: The id of the output plugin to use. This should not include the leading "Export::". Examples: BibTeX, XML.

: If this is ommited or an invalid plugin is requested, then 'export' will list all plugins compatible with the dataset and exit.

* <em>objectid</em>
: If this is set then just output the single, specified item or items.





==OPTIONS==
* '''--argument key=value'''
: Add an argument to the export plugin. May be repeated. Effects depend on te export plugin.

* '''--help'''
: Print a brief help message and exit.

* '''--man'''
: Print the full manual page and then exit.

* '''--quiet'''
: Be vewwy vewwy quiet. This option will supress all output unless an error occurs.

* '''--verbose'''
: Explain in detail what is going on. May be repeated for greater effect.

: Shows why a plugin is disabled.

* '''--version'''
: Output version information and exit.

<pre>

</pre>





==COPYRIGHT==
Copyright 2000-2011 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 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 General Public License for more details.

You should have received a copy of the GNU General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.

API:bin/epadmin

2013-01-22T09:57:23Z

Tdb01r:

API:bin/generate abstracts

2013-01-22T09:57:22Z

Tdb01r:

API:bin/generate static

2013-01-22T09:57:22Z

Tdb01r:

API:bin/import subjects

2013-01-22T09:57:21Z

Tdb01r:

API:bin/generate apacheconf

2013-01-22T09:57:21Z

Tdb01r:

API:bin/generate views

2013-01-22T09:57:20Z

Tdb01r:

API:EPrints/DataObj/EPM

2013-01-22T09:57:19Z

Tdb01r:

API:EPrints/DataObj/EventQueue

2013-01-22T09:57:19Z

API:EPrints/DataObj/Subject

2013-01-22T09:57:18Z

Tdb01r:

API:EPrints/DataObj/File

2013-01-22T09:57:17Z

Tdb01r:

API:EPrints/DataObj/EPrint

2013-01-22T09:57:16Z

Tdb01r:

{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/DataObj/EPrint.pm|package_name=EPrints::DataObj::EPrint}}[[Category:API|EPRINT]][[Category:API:EPrints/DataObj|EPRINT]][[Category:API:EPrints/DataObj/EPrint|EPRINT]]<div>


==NAME==
'''EPrints::DataObj::EPrint''' - Class representing an actual EPrint





==DESCRIPTION==
This class represents a single eprint record and the metadata associated with it. This is associated with one of more EPrint::Document objects.

EPrints::DataObj::EPrint is a subclass of EPrints::DataObj with the following metadata fields (plus those defined in ArchiveMetadataFieldsConfig):





==SYSTEM METADATA==
* eprintid (int)
: The unique numerical ID of this eprint.

* rev_number (int)
: The number of the current revision of this record.

* userid (itemref)
: The id of the user who deposited this eprint (if any). Scripted importing could cause this not to be set.

* dir (text)
: The directory, relative to the documents directory for this repository, which this eprints data is stored in. Eg. disk0/00/00/03/34 for record 334.

* datestamp (time)
: The date this record first appeared live in the repository.

* lastmod (time)
: The date this record was last modified.

* status_changes (time)
: The date/time this record was moved between inbox, buffer, archive, etc.

* type (namedset)
: The type of this record, one of the types of the "eprint" dataset.

* succeeds (itemref)
: The ID of the eprint (if any) which this succeeds. This field should have been an int and may be changed in a later upgrade.

* commentary (itemref)
: The ID of the eprint (if any) which this eprint is a commentary on. This field should have been an int and may be changed in a later upgrade.

* metadata_visibility (set)
: This field is automatically set.

<pre> show - appears normally
no_search - hidden from search/views</pre>

: The 'hide' option may be used to force an eprint to not appear in search/views but is not considered a stable option.





==METHODS==

===get_system_field_info===

<source lang="perl">$metadata = EPrints::DataObj::EPrint->get_system_field_info

</source>
Return an array describing the system metadata of the EPrint dataset.





===fileinfo===

<source lang="perl">$eprint->fileinfo()

</source>
The special '''fileinfo''' field contains the icon URL and main-file URL for each non-volatile document in the eprint. This is a performance tweak to avoid having to retrieve documents when rendering eprint citations.

Example:

<pre> /style/images/fileicons/application_pdf.png;/20/1/paper.pdf|/20/4.hassmallThumbnailVersion/tdb_portrait.jpg;/20/4/tdb_portrait.jpg</pre>

These URLs are relative to the current repository base path ('http_url').





===get_dataset_id===

<source lang="perl">$dataset = EPrints::DataObj::EPrint->get_dataset_id

</source>
Returns the id of the [[API:EPrints/DataSet|EPrints::DataSet]] object to which this record belongs.





===get_dataset===

<source lang="perl">$dataset = $eprint->get_dataset

</source>
Return the dataset to which this object belongs. This will return one of the virtual datasets: inbox, buffer, archive or deletion.





===get_defaults===

<source lang="perl">$defaults = EPrints::DataObj::EPrint->get_defaults( $session, $data )

</source>
Return default values for this object based on the starting data.





===clone===

<source lang="perl">$eprint = $eprint->clone( $dest_dataset, $copy_documents, $link )

</source>
Create a copy of this EPrint with a new ID in the given dataset. Return the new eprint, or undef in the case of an error.

If $copy_documents is set and true then the documents (and files) will be copied in addition to the metadata.

If $nolink is true then the new eprint is not connected to the old one.





===log_mail_owner===

<source lang="perl">$eprint->log_mail_owner( $mail )

</source>
Log that the given mail message was send to the owner of this EPrint.

$mail is the same XHTML DOM that was sent as the email.





===get_editorial_contact===

<source lang="perl">$user = $eprint->get_editorial_contact

</source>
Return the user identified as the editorial contact for this item.

By default returns undef.

nb. This has nothing to do with the editor defined in the metadata





===remove===

<source lang="perl">$success = $eprint->remove

</source>
Erase this eprint and any associated records from the database and filesystem.

This should only be called on eprints in "inbox" or "buffer".





===commit===

<source lang="perl">$success = $eprint->commit( [$force] );

</source>
Commit any changes to the database.

Calls [[API:EPrints/DataObj/EPrint#update_triggers|update_triggers]] just before the database is updated.

The actions this method does are dependent on some object attributes:

<pre> changed - HASH of changed fields (from [[API:EPrints/DataObj|EPrints::DataObj]])
non_volatile_change - BOOL (from [[API:EPrints/DataObj|EPrints::DataObj]])
under_construction - BOOL</pre>

If '''datestamp''' is unset and this eprint is in the '''archive''' dataset datestamp will always be set which will in turn set '''datestamp''' as changed.

If no field values were changed and <code>$force</code> is false returns.

If <code>under_construction</code> is false:
- static files updated

If <code>non_volatile_change</code> is true:
- '''lastmod''' field updated
- triples update queued

If <code>under_construction</code> is false and <code>non_volatile_change</code> is true:
- revision generated

The goal of these controls is to only trigger expensive processes in response to user actions. Revisions need to be generated when the user changes metadata or uploads new files (see [[API:EPrints/DataObj/Document#commit|EPrints::DataObj::Document/commit]]).





===save_revision===

<source lang="perl">$eprint->save_revision( %opts )

</source>
Increase the eprint revision number and save a complete copy of the record into the history (see [[API:EPrints/DataObj/History|EPrints::DataObj::History]]).

Options:

<pre> user - user that caused the action to occur, defaults to current user
action - see history.action, defaults to "modify"
details - see history.details, defaults to a description of changed fields</pre>





===validate===

<source lang="perl">$problems = $eprint->validate( [$for_archive], $workflow_id )

</source>
Return a reference to an array of XHTML DOM objects describing validation problems with the entire eprint based on $workflow_id.

If $workflow_id is undefined defaults to "default".

A reference to an empty array indicates no problems.

Calls [[API:EPrints/DataObj/EPrint#validate_eprint|validate_eprint]] for the <code>$eprint</code>.





===skip_validation===

<source lang="perl">$boolean = $eprint->skip_validation

</source>
Returns true if this eprint should pass validation without being properly validated. This is to allow the use of dodgey data imported from legacy systems.





===prune_documents===

<source lang="perl">$eprint->prune_documents

</source>
Remove any documents associated with this eprint which don't actually have any files.





===get_all_documents===

<source lang="perl">@documents = $eprint->get_all_documents

</source>
Return a list of all {{API:PodLink|file=EPrint/Document|package_name=EPrint::Document|section=|text=EPrint::Document}} objects associated with this eprint excluding documents with a "isVolatileVersionOf" relation (e.g. thumbnails).





===move_to_deletion===

<source lang="perl">$success = $eprint->move_to_deletion

</source>
Transfer the EPrint into the "deletion" dataset. Should only be called in eprints in the "archive" dataset.





===move_to_inbox===

<source lang="perl">$success = $eprint->move_to_inbox

</source>
Transfer the EPrint into the "inbox" dataset. Should only be called in eprints in the "buffer" dataset.





===move_to_buffer===

<source lang="perl">$success = $eprint->move_to_buffer

</source>
Transfer the EPrint into the "buffer" dataset. Should only be called in eprints in the "inbox" or "archive" dataset.





===move_to_archive===

<source lang="perl">$success = $eprint->move_to_archive

</source>
Move this eprint into the main "archive" dataset. Normally only called on eprints in "deletion" or "buffer" datasets.





===local_path===

<source lang="perl">$path = $eprint->local_path

</source>
Return the full path of the EPrint directory on the local filesystem. No trailing slash.





===url_stem===

<source lang="perl">$url = $eprint->url_stem

</source>
Return the URL to this EPrint's directory. Note, this INCLUDES the trailing slash, unlike the local_path method.





===generate_static===

<source lang="perl">$eprint->generate_static

</source>
Generate the static version of the abstract web page. In a multi-language repository this will generate one version per language.

If called on inbox or buffer, remove the abstract page.





===remove_static===

<source lang="perl">$eprint->remove_static

</source>
Remove the static web page or pages.





===render===

<source lang="perl">( $description, $title, $links ) = $eprint->render

</source>
Render the eprint. The 3 returned values are references to XHTML DOM objects. $description is the public viewable description of this eprint that appears as the body of the abstract page. $title is the title of the abstract page for this eprint. $links is any elements which should go in the <head> of this page.

Calls [[API:EPrints/DataObj/EPrint#eprint_render|eprint_render]] to actually render the <code>$eprint</code>, if it isn't deleted.





===get_control_url===

<source lang="perl">$url = $eprint->get_control_url

</source>
Return the URL of the control page for this eprint.





===get_url===

<source lang="perl">$url = $eprint->get_url

</source>
Return the public URL of this eprints abstract page.





===get_user===

<source lang="perl">$user = $eprint->get_user

</source>
Return the EPrints::DataObj::User to whom this eprint belongs (if any).





===in_thread===

<source lang="perl">$bool = $eprint->in_thread( $field )

</source>
Returns true if this eprint is in the $field thread.





===first_in_thread===

<source lang="perl">$eprint = $eprint->first_in_thread( $field )

</source>
Return the first (earliest) version or first paper in the thread of commentaries of this paper in the repository.





===last_in_thread===

<source lang="perl">$eprint = $eprint->last_in_thread( $field )

</source>
Returns the latest item in the $field thread on this eprint's branch of the thread tree.





===render_version_thread===

<source lang="perl">$xhtml = $eprint->render_version_thread( $field )

</source>
Render XHTML DOM describing the entire thread as nested unordered lists.





===get_type===

<source lang="perl">$type = $eprint->get_type

</source>
Return the type of this eprint.





===user_roles===

<source lang="perl">@roles = $eprint->user_roles( $user )

</source>
Return the @roles $user has on $eprint.





===in_editorial_scope_of===

<source lang="perl">$boolean = $eprint->in_editorial_scope_of( $possible_editor )

</source>
Returns true if $possible_editor can edit this eprint. This is according to the user editperms.

This does not mean the user has the editor priv., just that if they do then they may edit the given item.





===has_owner===

<source lang="perl">$boolean = $eprint->has_owner( $possible_owner )

</source>
Returns true if $possible_owner can edit this eprint. This is according to the user editperms.

This does not mean the user has the editor priv., just that if they do then they may edit the given item.

Uses the callback "does_user_own_eprint" if available.





===obtain_lock===

<source lang="perl">$boolean = $eprint->obtain_lock( $user )

</source>




===remove_lock===

<source lang="perl">$boolean = $eprint->remove_lock( $user )

</source>




===could_obtain_lock===

<source lang="perl">$boolean = $eprint->could_obtain_lock( $user )

</source>




===is_locked===

<source lang="perl">$boolean = $eprint->is_locked()

</source>




===render_edit_lock===

<source lang="perl">$xhtml = render_edit_lock( $session, $value )

</source>




==CALLBACKS==
Callbacks may optionally be defined in the ArchiveConfig.

* validate_field
<pre> validate_field( $field, $value, $session, [$for_archive] )</pre>

* validate_eprint
<pre> validate_eprint( $eprint, $session, [$for_archive] )</pre>

* set_eprint_defaults
<pre> set_eprint_defaults( $data, $session )</pre>

* set_eprint_automatic_fields
<pre> set_eprint_automatic_fields( $eprint )</pre>

* eprint_render
<pre> eprint_render( $eprint, $session )</pre>

: See {{API:PodLink|file=ArchiveRenderConfig|package_name=ArchiveRenderConfig|section=eprint_render|text=ArchiveRenderConfig/eprint_render}}.

<pre>

</pre>





==COPYRIGHT==
Copyright 2000-2011 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/.

API:EPrints/DataObj/User

2013-01-22T09:57:14Z

Tdb01r:

{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/DataObj/User.pm|package_name=EPrints::DataObj::User}}[[Category:API|USER]][[Category:API:EPrints/DataObj|USER]][[Category:API:EPrints/DataObj/User|USER]]<div>


==NAME==
'''EPrints::DataObj::User''' - Class representing a single user.





==DESCRIPTION==
This class represents a single eprint user record and the metadata associated with it.

EPrints::DataObj::User is a subclass of EPrints::DataObj with the following metadata fields (plus those defined in ArchiveMetadataFieldsConfig:





==SYSTEM METADATA==
* userid (int)
: The unique ID number of this user record. Unique within the current repository.

* rev_number (int)
: The revision number of this record. Each time it is changed the revision number is increased. This is not currently used for anything but it may be used for logging later.

* username (text)
: The username of this user. Used for logging into the system. Unique within this repository.

* password (secret)
: The crypted password for this user as generated by [[API:EPrints/Utils#crypt|EPrints::Utils/crypt]]. This may be ignored if for example LDAP authentication is being used.

* usertype (namedset)
: The type of this user. The options are configured in metadata-phrases.xml.

* newemail (email)
: Used to store a new but as yet unconfirmed email address.

* newpassword (secret)
: Used to store a new but as yet unconfirmed password.

* pin (text)
: A code required to confirm a new username or password. This code is emailed to the user to confirm they are who they say they are.

* pinsettime (int)
: When the pin code was set, so we can make it time out.

* joined (time)
: The date and time that the user account was created. Before EPrints 2.4 this was a date field so users created before the upgrade will appear to have been created at midnight.

* email (email)
: The email address of this user. Unique within the repository.

* lang (namedset)
: The ID of the prefered language of this user. Only really used in multilingual repositories.

* editperms (search, multiple)
: This field is used to filter what eprints a staff member can approve and modify. If it's unset then they can modify any (given the correct privs. but if it is set then an eprint must match at least one of the searches to be within their scope.

* frequency (set)
: Only relevant to staff accounts. Is the frequency they want to be mailed about eprints matching their scope that are in editorial review. never, daily, weekly or monthly.

* mailempty (boolean)
: Only relevant to staff accounts. If set to true then emails are sent even if there are no items matching the scope.

* preference (compound)
: User preferences which need to be persistent (simple key-value pairs).





==METHODS==

===get_system_field_info===

<source lang="perl">$field_info = EPrints::DataObj::User->get_system_field_info

</source>
Return an array describing the system metadata of the this dataset.





===new===

<source lang="perl">$user = EPrints::DataObj::User->new( $session, $userid )

</source>
Load the user with the ID of $userid from the database and return it as an EPrints::DataObj::User object.





===new_from_data===

<source lang="perl">$user = EPrints::DataObj::User->new_from_data( $session, $data )

</source>
Construct a new EPrints::DataObj::User object based on the $data hash reference of metadata.

Used to create an object from the data retrieved from the database.





===get_dataset_id===

<source lang="perl">$dataset = EPrints::DataObj::User->get_dataset_id

</source>
Returns the id of the [[API:EPrints/DataSet|EPrints::DataSet]] object to which this record belongs.





===get_defaults===

<source lang="perl">$defaults = EPrints::DataObj::User->get_defaults( $session, $data )

</source>
Return default values for this object based on the starting data.





===user_with_email===

<source lang="perl">$user = EPrints::DataObj::User::user_with_email( $session, $email )

</source>
Return the EPrints::user with the specified $email, or undef if they are not found.





===user_with_username===

<source lang="perl">$user = EPrints::DataObj::User::user_with_username( $session, $username )

</source>
Return the EPrints::user with the specified $username, or undef if they are not found.





===validate===

<source lang="perl">$problems = $thing->validate

</source>
Validate the user - find out if all the required fields are filled out, and that what's been filled in is OK. Returns a reference to an array of problem descriptions.

If there are no probelms then the array is empty.

The problems are XHTML DOM objects describing the problem.





===commit===

<source lang="perl">$user->commit( [$force] )

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





===remove===

<source lang="perl">$success = $user->remove

</source>
Remove this user from the database. Also, remove their saved searches, but do not remove their eprints.





===is_staff===

<source lang="perl">$bool = $user->is_staff()

</source>
Returns true if the user's type is '''editor''' or '''admin'''.





===langauge===

<source lang="perl">$lang = $user->langauge()

</source>
Get the preferred language of the user.





===owned_eprints_list===

<source lang="perl">$list = $user->owned_eprints_list( %opts )

</source>
Returns a [[API:EPrints/List|EPrints::List]] of all the [[API:EPrints/DataObj/EPrint|EPrints::DataObj::EPrint]]s owned by this user.

%opts is passed to a [[API:EPrints/Search|EPrints::Search]] which is used to filter the results.





===editable_eprints_list===

<source lang="perl">$list = $user->editable_eprints_list( %opts )

</source>
Returns a [[API:EPrints/List|EPrints::List]] of [[API:EPrints/DataObj/EPrint|EPrints::DataObj::EPrint]]s that match this user's editorial search expressions. If the user has no editorial scope a list of all eprints that match the given %opts is returned.

%opts is passed to a [[API:EPrints/Search|EPrints::Search]] which is used to filter the results.

<pre> $list = $user->editable_eprints_list(
dataset => $repo->dataset( "buffer" ),
);</pre>





===has_owner===

<source lang="perl">$boolean = $user->has_owner( $possible_owner )

</source>
True if the users are the same record.





===mail===

<source lang="perl">$ok = $user->mail( $subjectid, $message, [$replyto], [$email] )

</source>
Send an email to this user.

$subjectid is the ID of a phrase to use as the subject of this email.

$message is an XML DOM object describing the message in simple XHTML.

$replyto is the reply to address for this email, if different to the repository default.

$email is the email address to send this email to if different from this users configured email address.

Return true if the email was sent OK.





===render===

<source lang="perl">( $page, $title ) = $user->render

</source>
Render this user into HTML using the "user_render" method in ArchiveRenderConfig.pm. Returns both the rendered information and the title as XHTML DOM.





===render_full===

<source lang="perl">( $page, $title ) = $user->render_full

</source>
The same as $user->render, but renders all fields, not just those intended for public viewing. This is the admin view of the user.





===get_url===

<source lang="perl">$url = $user->get_url

</source>
Return the URL which will display information about this user.

If $staff is true then return the URL for an administrator to view and modify this record.





===get_type===

<source lang="perl">$type = $user->get_type

</source>
Return the type of this user. Equivalent of $user->get_value( "usertype" );





===get_saved_searches===

<source lang="perl">@saved_searches = $eprint->get_saved_searches

</source>
Return an array of all EPrint::DataObj::SavedSearch objects associated with this user.





===preference===

<source lang="perl">$value = $user->preference( $key )

</source>
Retrieve the preference $key.





===set_preference===

<source lang="perl">$user->set_preference( $key, $value )

</source>
Set a preference $key for the user to $value.





===send_out_editor_alert===

<source lang="perl">$user->send_out_editor_alert

</source>
Called on users who are editors, when it's time to send their update on what items are in the editorial review buffer.

Sends the email if needed.





===process_editor_alerts===

<source lang="perl">EPrints::DataObj::User::process_editor_alerts( $session, $frequency );

</source>
Static method.

Called to send out all editor alerts of a given frequency (daily, weekly, monthly) for the current repository.





===allow===

<source lang="perl">$result = $user->allow( $priv )

</source>
Returns true if $user can perform this action/view this screen.

To test whether a privilege is possible on an object use [[API:EPrints/DataObj#permit|EPrints::DataObj/permit]].





===has_privilege===

<source lang="perl">$boolean = $user->has_privilege( $priv )

</source>
Returns true if $priv is in the user's privileges table.





==COPYRIGHT==
Copyright 2000-2011 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/.

API:EPrints/DataObj/Document

2013-01-22T09:57:13Z

Tdb01r:

{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/DataObj/Document.pm|package_name=EPrints::DataObj::Document}}[[Category:API|DOCUMENT]][[Category:API:EPrints/DataObj|DOCUMENT]][[Category:API:EPrints/DataObj/Document|DOCUMENT]]<div>


==NAME==
'''EPrints::DataObj::Document''' - A single format of a record.





==DESCRIPTION==
Document represents a single format of an EPrint (eg. PDF) - the actual file(s) rather than the metadata.

This class is a subclass of DataObj, with the following metadata fields:

* docid (text)
: The unique ID of the document. This is a string of the format 123-02 where the first number is the eprint id and the second is the document number within that eprint.

: This should probably have been and "int" but isn't. I later version of EPrints may change this.

* eprintid (itemref)
: The id number of the eprint to which this document belongs.

* placement (int)
: Placement of the document - the order documents should be shown in.

* format (namedset)
: The format of this document. One of the types of the dataset "document".

* formatdesc (text)
: An additional description of this document. For example the specific version of a format.

* language (namedset)
: The ISO ID of the language of this document. The default configuration of EPrints does not set this.

* security (namedset)
: The security type of this document - who can view it. One of the types of the dataset "security".

* main (text)
: The file which we should link to. For something like a PDF file this is the only file. For an HTML document with images it would be the name of the actual HTML file.

* files (subobject, multiple)
: A virtual field which represents the list of Files which are part of this record.

* media
: A compound field containing a description of the document media - dimensions, codec etc.





==METHODS==

===get_system_field_info===

<source lang="perl">$metadata = EPrints::DataObj::Document->get_system_field_info

</source>
Return an array describing the system metadata of the Document dataset.





===get_dataset_id===

<source lang="perl">$dataset = EPrints::DataObj::Document->get_dataset_id

</source>
Returns the id of the [[API:EPrints/DataSet|EPrints::DataSet]] object to which this record belongs.





===get_defaults===

<source lang="perl">$defaults = EPrints::DataObj::Document->get_defaults( $session, $data )

</source>
Return default values for this object based on the starting data.





===clone===

<source lang="perl">$newdoc = $doc->clone( $eprint )

</source>
Attempt to clone this document. Both the document metadata and the actual files. The clone will be associated with the given EPrint.





===remove===

<source lang="perl">$success = $doc->remove

</source>
Attempt to completely delete this document





===get_eprint===

<source lang="perl">$eprint = $doc->get_eprint

</source>
Return the EPrint this document is associated with.

This is a synonym for get_parent().





===get_baseurl===

<source lang="perl">$url = $doc->get_baseurl( [$staff] )

</source>
Return the base URL of the document. Overrides the stub in DataObj. $staff is currently ignored.





===is_public===

<source lang="perl">$boolean = $doc->is_public()

</source>
True if this document has no security set and is in the live archive.





===path===

<source lang="perl">$path = $doc->path

</source>
Returns the relative path to the document WITHOUT any file.





===file_path===

<source lang="perl">$path = $doc->file_path( [ $filename ] )

</source>
Returns the relative path to $filename stored in this document. If $filename is undefined returns the path to the main file.

This is an efficient shortcut to this:

<pre> my $file = $doc->stored_file( $filename );
my $path = $file->path;</pre>





===get_url===

<source lang="perl">$url = $doc->get_url( [$file] )

</source>
Return the full URL of the document. Overrides the stub in DataObj.

If file is not specified then the "main" file is used.





===files===

<source lang="perl">%files = $doc->files

</source>
Return a hash, the keys of which are all the files belonging to this document (relative to $doc->local_path). The values are the sizes of the files, in bytes.





===remove_file===

<source lang="perl">$success = $doc->remove_file( $filename )

</source>
Attempt to remove the given file. Give the filename as it is returned by get_files().





===set_main===

<source lang="perl">$doc->set_main( $main_file )

</source>
Sets the main file and adjusts format and mime type as necessary. Won't affect the database until a $doc->commit().





===get_main===

<source lang="perl">$filename = $doc->get_main

</source>
Return the name of the main file in this document.





===set_format===

<source lang="perl">$doc->set_format( $format )

</source>
Set format. Won't affect the database until a commit(). Just an alias for $doc->set_value( "format" , $format );





===set_format_desc===

<source lang="perl">$doc->set_format_desc( $format_desc )

</source>
Set the format description. Won't affect the database until a commit(). Just an alias for $doc->set_value( "format_desc" , $format_desc );





===add_file===

<source lang="perl">$fileobj = $doc->add_file( $file, $filename [, $preserve_path] )

</source>
$file is the full path to a file to be added to the document, with name $filename. $filename is passed through [[API:EPrints/System#sanitise|EPrints::System/sanitise]] before being written.

If $preserve_path is true then include path components in $filename.

Returns the $fileobj created or undef on failure.





===add_archive===

<source lang="perl">$success = $doc->add_archive( $file, $archive_format )

</source>
$file is the full path to an archive file, eg. zip or .tar.gz

This function will add the contents of that archive to the document.





===add_directory===

<source lang="perl">$success = $doc->add_directory( $directory )

</source>
Upload the contents of $directory to this document. This will not set the main file.

This method expects $directory to have a trailing slash (/).





===upload_url===

<source lang="perl">$success = $doc->upload_url( $url )

</source>
Attempt to grab stuff from the given URL. Grabbing HTML stuff this way is always problematic, so (by default): only relative links will be followed and only links to files in the same directory or subdirectory will be followed.

This (by default) uses wget. The details can be configured in SystemSettings.





===commit===

<source lang="perl">$success = $doc->commit

</source>
Commit any changes that have been made to this object to the database.

Calls "set_document_automatic_fields" in the ArchiveConfig first to set any automatic fields that may be needed.





===validate===

<source lang="perl">$problems = $doc->validate( [$for_archive] )

</source>
Return an array of XHTML DOM objects describing validation problems with the entire document, including the metadata and repository config specific requirements.

A reference to an empty array indicates no problems.





===get_type===

<source lang="perl">$type = $doc->get_type

</source>
Return the type of this document.





===files_modified===

<source lang="perl">$doc->files_modified

</source>
This method does all the things that need doing when a file has been modified.





===rehash===

<source lang="perl">$doc->rehash

</source>
Recalculate the hash value of the document. Uses MD5 of the files (in alphabetic order), but can use user specified hashing function instead.





===make_indexcodes===

<source lang="perl">$doc = $doc->make_indexcodes()

</source>
Make the indexcodes document for this document. Returns the generated document or undef on failure.





===remove_indexcodes===

<source lang="perl">$doc = $doc->remove_indexcodes()

</source>
Remove any documents containing index codes for this document. Returns the number of documents removed.





===render_icon_link===

<source lang="perl">$frag = $doc->render_icon_link( %opts )

</source>
Render a link to the icon for this document.

Options:

* new_window => 1
: Make link go to _blank not current window.

* preview => 1
: If possible, provide a preview pop-up.

* public => 0
: Show thumbnail/preview only on public docs.

* public => 1
: Show thumbnail/preview on all docs if poss.





===render_preview_link===

<source lang="perl">$frag = $doc->render_preview_link( %opts )

</source>
Render a link to the preview for this document (if available) using a lightbox.

Options:

* caption => $frag
: XHTML fragment to use as the caption, defaults to empty.

* set => "foo"
: The name of the set this document belongs to, defaults to none (preview won't be shown as part of a set).





===add_relation===

<source lang="perl">$doc->add_relation( $tgt, @types )

</source>
Add one or more relations to $doc pointing to $tgt (does not modify $tgt).





===remove_relation===

<source lang="perl">$doc->remove_relation( $tgt [, @types ] )

</source>
Removes the relations in $doc to $tgt. If @types isn't given removes all relations to $tgt. If $tgt is undefined removes all relations given in @types.

If you want to remove all relations do $doc->set_value( "relation", [] );





===has_relation===

<source lang="perl">$bool = $doc->has_relation( $tgt [, @types ] )

</source>
Returns true if $doc has relations to $tgt. If @types is given checks that $doc satisfies all of the given types. $tgt may be undefined.





===search_related===

<source lang="perl">$list = $doc->search_related( [ $type ] )

</source>
Return a [[API:EPrints/List|EPrints::List]] that contains all documents related to this document. If $type is defined returns only those documents related by $type.





==COPYRIGHT==
Copyright 2000-2011 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/.

API:EPrints/DataObj/LoginTicket

2013-01-22T09:57:12Z

Tdb01r:

API:EPrints/MetaField/Int

2013-01-22T09:57:10Z

Tdb01r:

API:EPrints/MetaField/Timestamp

2013-01-22T09:57:07Z

API:EPrints/MetaField/Multilang

2013-01-22T09:57:06Z

Tdb01r:

API:EPrints/Update/Views

2013-01-22T09:57:05Z

Tdb01r:

API:EPrints/Paginate/Columns

2013-01-22T09:57:03Z

Tdb01r:

API:EPrints/Plugin/Search/External

2013-01-22T09:56:49Z

API:EPrints/Plugin/Convert/Thumbnails

2013-01-22T09:56:48Z

Tdb01r:

API:EPrints/Plugin/Export/XSLT

2013-01-22T09:56:43Z

Tdb01r: