EPrints Documentation - User contributions [en-gb]

ORCID

2016-09-26T18:24:20Z

Bdgregg@pitt.edu: /* Notes from Pittsburgh: */ - Added warning:orcid_invalid phrase.

This page has been created to gather information about how different EPrints repositories have integrated ORCID.
At this time (April 2016) there doesn't seem to be a 'best practice' approach that has been adopted widely - this will hopefully change over time.

If you are looking to retrieve publications from the ORCID service, the [http://bazaar.eprints.org/354/ Import from ORCID (Tier 1 API)] Bazaar package, or the [https://github.com/eprintsug/orcidt2 ORCID Tier 2 api framework] are good places to start.

2016-05-20 [[User:Alan.stiles@open.ac.uk|Alan Stiles]] at The Open University is working on a plugin to connect EPrints with ORCID via the Tier 2 Members API to retrieve ORCID ids and synchronise publications and affiliation details.

Some aspects that need to be considered when adopting ORCIDs, and making them available to other systems are:

* storing the ORCID (see: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier)
* rendering the ORCID in abstract pages (see [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier link above])
* exposing ORCIDs over OAI-PMH metadata profiles e.g. RIOXX

NB The examples below may refer to the 'creators' field - but the same approach could be used to extend other 'person' fields - e.g. contributors.

= Re-using creators.id subfield =

The creators.id field is labelled 'email' by default, but as it's an 'id' type field, it can be used to store ORCIDs.
To re-label the field, a simple addition to a phrase file in <code>archives/ARCHIVEID/cfg/lang/en/phrases/</code> needs to be made:
<source lang="xml">
<epp:phrase id="eprint_fieldname_creators_id">ORCID / Creators email (if known)</epp:phrase>
</source>

== Rendering the ORCID in a citation ==
The rendering of this field then needs to be changed to accommodate an author with an ORCID. The following script adds methods that can be called via the EPScript language:

<source lang="perl">
# add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/z_add_to_EPrints_Script_Compiled.pl
# Write into EPrints::Script::Compiled package to allow use of function in epscript
{
package EPrints::Script::Compiled;
use strict;

sub run_wrro_people_with_orcids
{
my( $self, $state, $value ) = @_;

my $session = $state->{session};
my $r = $state->{session}->make_doc_fragment;

my $creators = $value->[0];

foreach my $i (0..$#$creators){

my $creator = @$creators[$i];

if( $i > 0 ){
#not first item (or only one item)
if( $i == $#$creators ){
#last item
$r->appendChild( $session->make_text( " and " ) );
} else {
$r->appendChild( $session->make_text( ", " ) );
}
}

my $person_span = $session->make_element( "span", "class" => "person" );
$person_span->appendChild( $session->render_name( $creator->{name} ) );

my $id = $creator->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
my $orcid_span = $session->make_element( "span", "class" => "orcid" );

# According to https://orcid.org/trademark-and-id-display-guidelines
# "recommended display is a hyperlinked URI preceded by the iD icon"
# This looks terrible in a citation. Removed for the time being.
#
# my $orcid_link = $session->make_element(
# "a",
# "href" => "http://orcid.org/",
# "target" => "_blank",
# "class" => "orcid-icon"
# );
# $orcid_link->appendChild( $session->make_element(
# "img",
# "src" => "/images/orcid_16x16.png",
# "title" => "ORCID"
# ) );
# $orcid_span->appendChild( $orcid_link );

my $link = $session->make_element(
"a",
"href" => "http://orcid.org/$1",
"target" => "_blank",
);
$link->appendChild( $session->make_text( "orcid.org/$1" ) );

$orcid_span->appendChild( $session->make_text( "(" ) );
$orcid_span->appendChild( $link );
$orcid_span->appendChild( $session->make_text( ")" ) );

$person_span->appendChild( $session->make_text( " " ) );
$person_span->appendChild( $orcid_span );
}
$r->appendChild( $person_span );
}

return [ $r, "XHTML" ];
}

}
# END EPrints::Script::Compiled additions
</source>

You may also want a bit of CSS to style ORCID links
<source lang="css">
/* Add to e.g. ~/archives/ARCHIVEID/cfg/static/style/auto/zzz_orcid.css */
.person:hover {border-bottom: 1px dashed #a6ce39;}
.orcid {}
.orcid a:hover {
color: #a6ce39;
}
.orcid-icon {}
.orcid-icon img { vertical-align: text-bottom; margin: 0 4px 0 2px; }
</source>

And finally, you have to call the new EPScript function from a citation file e.g. <code>archives/ARCHIVEID/cfg/citations/eprint/default.xml</code>
<source lang="xml">

<print expr="wrro_people_with_orcids(creators)" />
</source>

== Exposing the ORCID in RIOXX ==
Based on re-using the creators.id field, this block of code over-writes the default <code>rioxx2_value_author</code> function.
<source lang="perl">
# Add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/zzz_rioxx2_overwrites.pl
$c->{rioxx2_value_author} = sub {
my( $eprint ) = @_;

my @authors;
for( @{ $eprint->value( "creators" ) } )
{
my $id = $_->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
id => "http://orcid.org/$1"
};
} else {
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
};
}
}

#NB If your corp_creators has DOIs or ISNIs for the entries, a similar method could be used to include these here.
foreach my $corp ( @{ $eprint->value( "corp_creators" ) } )
{
my $entry = {};
$entry->{name} = $corp;
push @authors, { author => $corp };
}

return \@authors;
};

</source>

= Add additional identifiers to creators =
Another approach to storing ORCIDs is to add an additional sub-field to the creator field.
This has been discussed on the Eprints tech list. If you know how to do this, please document it here!

This is how University of Bath has done it. We're getting the ORCID data from another system, so have used a text field to capture it for display. At present there is no special rendering on it, it's just displaying as a number.
<source lang="perl">
{
name => 'creators',
type => 'compound',
multiple => 1,
fields => [
{
sub_name => 'name',
type => 'name',
hide_honourific => 1,
hide_lineage => 1,
family_first => 1,
},
{
sub_name => 'id',
type => 'text',
input_cols => 20,
allow_null => 1,
},
{
sub_name => 'orcid',
type => 'text',
input_cols => 20,
allow_null => 1,
}

],
input_boxes => 4,
},
</source>
This is how University of Pittsburgh has done it:
<source lang="perl">
{
'name' => 'creators',
'type' => 'compound',
'multiple' => 1,
'fields' => [
{
'sub_name' => 'name',
'type' => 'name',
'hide_honourific' => 1,
'hide_lineage' => 1,
'family_first' => 1,
},
{
'sub_name' => 'email',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'id',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'orcid',
'type' => 'id',
'input_cols' => 19,
'allow_null' => 1,
},
],
'input_boxes' => 4,
'render_value' => 'custom_render_creators_with_orcid',
},

</source>

==Notes from Pittsburgh:==

We have added some ORCID functionality in our IR System here at the University of Pittsburgh. We however have not “linked” our IR with orcid.org in anyway such as we do not have a lookup user in ORCID or the ability to add publications from ORCID to our IR. The only link is the entering of the ORCID into the system so that it can be displayed.

An example record is available here: [http://d-scholarship.pitt.edu/28114/ http://d-scholarship.pitt.edu/28114/]

# Users have an ORCID field in their profile – user_fields.pl
# Any “Creator” types have an ORCID field added to the workflow – eprint_fields.pl
# We have added ORCID validation adhering to this document: [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier] - eprint_validate.pl
# We have added the ORCID to the “lookup” function to populate the ORCID field from any user entries in the database. – cgi/users/lookup/name
# We display the ORCID as such on the input form, where the green icon links out to our own orcid.pitt.edu site, but could be to orcid.org by default.
# We display the ORCID as such on the public display of the record where the ORCID is linked out to orcid.org (see [http://d-scholarship.pitt.edu/28114/ example record])

ORCID Validator - snippet for eprints_validate.pl
<source lang="perl">
# ORCID ID Validator for individuals
# Reference: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier
# REGEX: ^\d{4}-\d{4}-\d{4}-(\d{3}X|\d{4})$
#
my @name_fields = qw( creators contributors exhibitors producers conductors lyricists ); #which ever name fields you added 'orcid' to.
foreach my $name_field ( @name_fields )
{
if( $eprint->is_set( $name_field ) )
{
foreach my $creator ( @{ $eprint->value( $name_field ) } )
{
my $orcid = $creator->{orcid};
next unless defined $orcid;
if ($repository->get_repository->can_call ( "validators", "isValidORCID" ) )
{
if (!$repository->get_repository->call( [ "validators", "isValidORCID" ], $orcid ))
{
my $field_text = $repository->html_phrase( "eprint_fieldname_$name_field" );
my $field_frag = $repository->make_element( "span", class=>"ep_problem_field:$name_field" );
$field_frag->appendChild($field_text);
push @problems, $repository->html_phrase( "warnings:orcid_invalid",
orcid => $repository->get_repository->make_text($orcid),
field => $field_frag,
);
}
} else {
$repository->get_repository->log( "Can not call isValidORCID." );
}
}
}
}
</source>

Phrase for "warnings:orcid_invalid":

<source lang="xml">
<epp:phrase id="warnings:orcid_invalid">The ORCID ID: <epc:pin name="orcid"/> is not a valid ORCID ID as it does not conform to the ORCID ID specification. Please edit the <epc:pin name="field"/> with the associated ORCID or remove it from the name completely.</epp:phrase>
</source>

Additional Function that can be placed either at the end of eprints_validate.pl (after the final };) or elsewhere:
<source lang="perl">
############################################
# Function: isValidORCID
# Description: Used to validate ORCID IDs
#
# From: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier (Checksum)
#
$c->{validators}->{isValidORCID} = sub {
my $ORCID = $_[0];
#Check for valid length of 19 characters.
my $size = length($ORCID);
if ($size > 19 )
{
return 0;
} else {
#Check actual validity of the ID mathematically.
$ORCID =~ s/\-//g;
my @chars = split(//, $ORCID);
my $total = 0;
for ( my $i=0; $i<15; $i++) {
$total = ($total + $chars[$i]) *2;
}
my $remainder = $total % 11;
my $result = (12 - $remainder) % 11;
return ($chars[15] == ($result==10 ? 'X' : $result))
}
};
</source>

Additionally you will have to define a custom render to add the fields to be displayed in the abstract/summary page.

(Information courtesy of Brian Gregg - bdgregg@pitt.edu)

ORCID

2016-09-16T21:38:46Z

Bdgregg@pitt.edu: /* Notes from Pittsburgh: */ - Added another note.

This page has been created to gather information about how different EPrints repositories have integrated ORCID.
At this time (April 2016) there doesn't seem to be a 'best practice' approach that has been adopted widely - this will hopefully change over time.

If you are looking to retrieve publications from the ORCID service, the [http://bazaar.eprints.org/354/ Import from ORCID (Tier 1 API)] Bazaar package, or the [https://github.com/eprintsug/orcidt2 ORCID Tier 2 api framework] are good places to start.

2016-05-20 [[User:Alan.stiles@open.ac.uk|Alan Stiles]] at The Open University is working on a plugin to connect EPrints with ORCID via the Tier 2 Members API to retrieve ORCID ids and synchronise publications and affiliation details.

Some aspects that need to be considered when adopting ORCIDs, and making them available to other systems are:

* storing the ORCID (see: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier)
* rendering the ORCID in abstract pages (see [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier link above])
* exposing ORCIDs over OAI-PMH metadata profiles e.g. RIOXX

NB The examples below may refer to the 'creators' field - but the same approach could be used to extend other 'person' fields - e.g. contributors.

= Re-using creators.id subfield =

The creators.id field is labelled 'email' by default, but as it's an 'id' type field, it can be used to store ORCIDs.
To re-label the field, a simple addition to a phrase file in <code>archives/ARCHIVEID/cfg/lang/en/phrases/</code> needs to be made:
<source lang="xml">
<epp:phrase id="eprint_fieldname_creators_id">ORCID / Creators email (if known)</epp:phrase>
</source>

== Rendering the ORCID in a citation ==
The rendering of this field then needs to be changed to accommodate an author with an ORCID. The following script adds methods that can be called via the EPScript language:

<source lang="perl">
# add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/z_add_to_EPrints_Script_Compiled.pl
# Write into EPrints::Script::Compiled package to allow use of function in epscript
{
package EPrints::Script::Compiled;
use strict;

sub run_wrro_people_with_orcids
{
my( $self, $state, $value ) = @_;

my $session = $state->{session};
my $r = $state->{session}->make_doc_fragment;

my $creators = $value->[0];

foreach my $i (0..$#$creators){

my $creator = @$creators[$i];

if( $i > 0 ){
#not first item (or only one item)
if( $i == $#$creators ){
#last item
$r->appendChild( $session->make_text( " and " ) );
} else {
$r->appendChild( $session->make_text( ", " ) );
}
}

my $person_span = $session->make_element( "span", "class" => "person" );
$person_span->appendChild( $session->render_name( $creator->{name} ) );

my $id = $creator->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
my $orcid_span = $session->make_element( "span", "class" => "orcid" );

# According to https://orcid.org/trademark-and-id-display-guidelines
# "recommended display is a hyperlinked URI preceded by the iD icon"
# This looks terrible in a citation. Removed for the time being.
#
# my $orcid_link = $session->make_element(
# "a",
# "href" => "http://orcid.org/",
# "target" => "_blank",
# "class" => "orcid-icon"
# );
# $orcid_link->appendChild( $session->make_element(
# "img",
# "src" => "/images/orcid_16x16.png",
# "title" => "ORCID"
# ) );
# $orcid_span->appendChild( $orcid_link );

my $link = $session->make_element(
"a",
"href" => "http://orcid.org/$1",
"target" => "_blank",
);
$link->appendChild( $session->make_text( "orcid.org/$1" ) );

$orcid_span->appendChild( $session->make_text( "(" ) );
$orcid_span->appendChild( $link );
$orcid_span->appendChild( $session->make_text( ")" ) );

$person_span->appendChild( $session->make_text( " " ) );
$person_span->appendChild( $orcid_span );
}
$r->appendChild( $person_span );
}

return [ $r, "XHTML" ];
}

}
# END EPrints::Script::Compiled additions
</source>

You may also want a bit of CSS to style ORCID links
<source lang="css">
/* Add to e.g. ~/archives/ARCHIVEID/cfg/static/style/auto/zzz_orcid.css */
.person:hover {border-bottom: 1px dashed #a6ce39;}
.orcid {}
.orcid a:hover {
color: #a6ce39;
}
.orcid-icon {}
.orcid-icon img { vertical-align: text-bottom; margin: 0 4px 0 2px; }
</source>

And finally, you have to call the new EPScript function from a citation file e.g. <code>archives/ARCHIVEID/cfg/citations/eprint/default.xml</code>
<source lang="xml">

<print expr="wrro_people_with_orcids(creators)" />
</source>

== Exposing the ORCID in RIOXX ==
Based on re-using the creators.id field, this block of code over-writes the default <code>rioxx2_value_author</code> function.
<source lang="perl">
# Add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/zzz_rioxx2_overwrites.pl
$c->{rioxx2_value_author} = sub {
my( $eprint ) = @_;

my @authors;
for( @{ $eprint->value( "creators" ) } )
{
my $id = $_->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
id => "http://orcid.org/$1"
};
} else {
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
};
}
}

#NB If your corp_creators has DOIs or ISNIs for the entries, a similar method could be used to include these here.
foreach my $corp ( @{ $eprint->value( "corp_creators" ) } )
{
my $entry = {};
$entry->{name} = $corp;
push @authors, { author => $corp };
}

return \@authors;
};

</source>

= Add additional identifiers to creators =
Another approach to storing ORCIDs is to add an additional sub-field to the creator field.
This has been discussed on the Eprints tech list. If you know how to do this, please document it here!

This is how University of Bath has done it. We're getting the ORCID data from another system, so have used a text field to capture it for display. At present there is no special rendering on it, it's just displaying as a number.
<source lang="perl">
{
name => 'creators',
type => 'compound',
multiple => 1,
fields => [
{
sub_name => 'name',
type => 'name',
hide_honourific => 1,
hide_lineage => 1,
family_first => 1,
},
{
sub_name => 'id',
type => 'text',
input_cols => 20,
allow_null => 1,
},
{
sub_name => 'orcid',
type => 'text',
input_cols => 20,
allow_null => 1,
}

],
input_boxes => 4,
},
</source>
This is how University of Pittsburgh has done it:
<source lang="perl">
{
'name' => 'creators',
'type' => 'compound',
'multiple' => 1,
'fields' => [
{
'sub_name' => 'name',
'type' => 'name',
'hide_honourific' => 1,
'hide_lineage' => 1,
'family_first' => 1,
},
{
'sub_name' => 'email',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'id',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'orcid',
'type' => 'id',
'input_cols' => 19,
'allow_null' => 1,
},
],
'input_boxes' => 4,
'render_value' => 'custom_render_creators_with_orcid',
},

</source>

==Notes from Pittsburgh:==

We have added some ORCID functionality in our IR System here at the University of Pittsburgh. We however have not “linked” our IR with orcid.org in anyway such as we do not have a lookup user in ORCID or the ability to add publications from ORCID to our IR. The only link is the entering of the ORCID into the system so that it can be displayed.

An example record is available here: [http://d-scholarship.pitt.edu/28114/ http://d-scholarship.pitt.edu/28114/]

# Users have an ORCID field in their profile – user_fields.pl
# Any “Creator” types have an ORCID field added to the workflow – eprint_fields.pl
# We have added ORCID validation adhering to this document: [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier] - eprint_validate.pl
# We have added the ORCID to the “lookup” function to populate the ORCID field from any user entries in the database. – cgi/users/lookup/name
# We display the ORCID as such on the input form, where the green icon links out to our own orcid.pitt.edu site, but could be to orcid.org by default.
# We display the ORCID as such on the public display of the record where the ORCID is linked out to orcid.org (see [http://d-scholarship.pitt.edu/28114/ example record])

ORCID Validator - snippet for eprints_validate.pl
<source lang="perl">
# ORCID ID Validator for individuals
# Reference: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier
# REGEX: ^\d{4}-\d{4}-\d{4}-(\d{3}X|\d{4})$
#
my @name_fields = qw( creators contributors exhibitors producers conductors lyricists ); #which ever name fields you added 'orcid' to.
foreach my $name_field ( @name_fields )
{
if( $eprint->is_set( $name_field ) )
{
foreach my $creator ( @{ $eprint->value( $name_field ) } )
{
my $orcid = $creator->{orcid};
next unless defined $orcid;
if ($repository->get_repository->can_call ( "validators", "isValidORCID" ) )
{
if (!$repository->get_repository->call( [ "validators", "isValidORCID" ], $orcid ))
{
my $field_text = $repository->html_phrase( "eprint_fieldname_$name_field" );
my $field_frag = $repository->make_element( "span", class=>"ep_problem_field:$name_field" );
$field_frag->appendChild($field_text);
push @problems, $repository->html_phrase( "warnings:orcid_invalid",
orcid => $repository->get_repository->make_text($orcid),
field => $field_frag,
);
}
} else {
$repository->get_repository->log( "Can not call isValidORCID." );
}
}
}
}
</source>

Additional Function that can be placed either at the end of eprints_validate.pl (after the final };) or elsewhere:
<source lang="perl">
############################################
# Function: isValidORCID
# Description: Used to validate ORCID IDs
#
# From: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier (Checksum)
#
$c->{validators}->{isValidORCID} = sub {
my $ORCID = $_[0];
#Check for valid length of 19 characters.
my $size = length($ORCID);
if ($size > 19 )
{
return 0;
} else {
#Check actual validity of the ID mathematically.
$ORCID =~ s/\-//g;
my @chars = split(//, $ORCID);
my $total = 0;
for ( my $i=0; $i<15; $i++) {
$total = ($total + $chars[$i]) *2;
}
my $remainder = $total % 11;
my $result = (12 - $remainder) % 11;
return ($chars[15] == ($result==10 ? 'X' : $result))
}
};
</source>

Additionally you will have to define a custom render to add the fields to be displayed in the abstract/summary page.

(Information courtesy of Brian Gregg - bdgregg@pitt.edu)

ORCID

2016-09-16T21:06:41Z

Bdgregg@pitt.edu: /* Notes from Pittsburgh: */ - Added some additional code.

This page has been created to gather information about how different EPrints repositories have integrated ORCID.
At this time (April 2016) there doesn't seem to be a 'best practice' approach that has been adopted widely - this will hopefully change over time.

If you are looking to retrieve publications from the ORCID service, the [http://bazaar.eprints.org/354/ Import from ORCID (Tier 1 API)] Bazaar package, or the [https://github.com/eprintsug/orcidt2 ORCID Tier 2 api framework] are good places to start.

2016-05-20 [[User:Alan.stiles@open.ac.uk|Alan Stiles]] at The Open University is working on a plugin to connect EPrints with ORCID via the Tier 2 Members API to retrieve ORCID ids and synchronise publications and affiliation details.

Some aspects that need to be considered when adopting ORCIDs, and making them available to other systems are:

* storing the ORCID (see: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier)
* rendering the ORCID in abstract pages (see [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier link above])
* exposing ORCIDs over OAI-PMH metadata profiles e.g. RIOXX

NB The examples below may refer to the 'creators' field - but the same approach could be used to extend other 'person' fields - e.g. contributors.

= Re-using creators.id subfield =

The creators.id field is labelled 'email' by default, but as it's an 'id' type field, it can be used to store ORCIDs.
To re-label the field, a simple addition to a phrase file in <code>archives/ARCHIVEID/cfg/lang/en/phrases/</code> needs to be made:
<source lang="xml">
<epp:phrase id="eprint_fieldname_creators_id">ORCID / Creators email (if known)</epp:phrase>
</source>

== Rendering the ORCID in a citation ==
The rendering of this field then needs to be changed to accommodate an author with an ORCID. The following script adds methods that can be called via the EPScript language:

<source lang="perl">
# add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/z_add_to_EPrints_Script_Compiled.pl
# Write into EPrints::Script::Compiled package to allow use of function in epscript
{
package EPrints::Script::Compiled;
use strict;

sub run_wrro_people_with_orcids
{
my( $self, $state, $value ) = @_;

my $session = $state->{session};
my $r = $state->{session}->make_doc_fragment;

my $creators = $value->[0];

foreach my $i (0..$#$creators){

my $creator = @$creators[$i];

if( $i > 0 ){
#not first item (or only one item)
if( $i == $#$creators ){
#last item
$r->appendChild( $session->make_text( " and " ) );
} else {
$r->appendChild( $session->make_text( ", " ) );
}
}

my $person_span = $session->make_element( "span", "class" => "person" );
$person_span->appendChild( $session->render_name( $creator->{name} ) );

my $id = $creator->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
my $orcid_span = $session->make_element( "span", "class" => "orcid" );

# According to https://orcid.org/trademark-and-id-display-guidelines
# "recommended display is a hyperlinked URI preceded by the iD icon"
# This looks terrible in a citation. Removed for the time being.
#
# my $orcid_link = $session->make_element(
# "a",
# "href" => "http://orcid.org/",
# "target" => "_blank",
# "class" => "orcid-icon"
# );
# $orcid_link->appendChild( $session->make_element(
# "img",
# "src" => "/images/orcid_16x16.png",
# "title" => "ORCID"
# ) );
# $orcid_span->appendChild( $orcid_link );

my $link = $session->make_element(
"a",
"href" => "http://orcid.org/$1",
"target" => "_blank",
);
$link->appendChild( $session->make_text( "orcid.org/$1" ) );

$orcid_span->appendChild( $session->make_text( "(" ) );
$orcid_span->appendChild( $link );
$orcid_span->appendChild( $session->make_text( ")" ) );

$person_span->appendChild( $session->make_text( " " ) );
$person_span->appendChild( $orcid_span );
}
$r->appendChild( $person_span );
}

return [ $r, "XHTML" ];
}

}
# END EPrints::Script::Compiled additions
</source>

You may also want a bit of CSS to style ORCID links
<source lang="css">
/* Add to e.g. ~/archives/ARCHIVEID/cfg/static/style/auto/zzz_orcid.css */
.person:hover {border-bottom: 1px dashed #a6ce39;}
.orcid {}
.orcid a:hover {
color: #a6ce39;
}
.orcid-icon {}
.orcid-icon img { vertical-align: text-bottom; margin: 0 4px 0 2px; }
</source>

And finally, you have to call the new EPScript function from a citation file e.g. <code>archives/ARCHIVEID/cfg/citations/eprint/default.xml</code>
<source lang="xml">

<print expr="wrro_people_with_orcids(creators)" />
</source>

== Exposing the ORCID in RIOXX ==
Based on re-using the creators.id field, this block of code over-writes the default <code>rioxx2_value_author</code> function.
<source lang="perl">
# Add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/zzz_rioxx2_overwrites.pl
$c->{rioxx2_value_author} = sub {
my( $eprint ) = @_;

my @authors;
for( @{ $eprint->value( "creators" ) } )
{
my $id = $_->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
id => "http://orcid.org/$1"
};
} else {
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
};
}
}

#NB If your corp_creators has DOIs or ISNIs for the entries, a similar method could be used to include these here.
foreach my $corp ( @{ $eprint->value( "corp_creators" ) } )
{
my $entry = {};
$entry->{name} = $corp;
push @authors, { author => $corp };
}

return \@authors;
};

</source>

= Add additional identifiers to creators =
Another approach to storing ORCIDs is to add an additional sub-field to the creator field.
This has been discussed on the Eprints tech list. If you know how to do this, please document it here!

This is how University of Bath has done it. We're getting the ORCID data from another system, so have used a text field to capture it for display. At present there is no special rendering on it, it's just displaying as a number.
<source lang="perl">
{
name => 'creators',
type => 'compound',
multiple => 1,
fields => [
{
sub_name => 'name',
type => 'name',
hide_honourific => 1,
hide_lineage => 1,
family_first => 1,
},
{
sub_name => 'id',
type => 'text',
input_cols => 20,
allow_null => 1,
},
{
sub_name => 'orcid',
type => 'text',
input_cols => 20,
allow_null => 1,
}

],
input_boxes => 4,
},
</source>
This is how University of Pittsburgh has done it:
<source lang="perl">
{
'name' => 'creators',
'type' => 'compound',
'multiple' => 1,
'fields' => [
{
'sub_name' => 'name',
'type' => 'name',
'hide_honourific' => 1,
'hide_lineage' => 1,
'family_first' => 1,
},
{
'sub_name' => 'email',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'id',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'orcid',
'type' => 'id',
'input_cols' => 19,
'allow_null' => 1,
},
],
'input_boxes' => 4,
'render_value' => 'custom_render_creators_with_orcid',
},

</source>

==Notes from Pittsburgh:==

We have added some ORCID functionality in our IR System here at the University of Pittsburgh. We however have not “linked” our IR with orcid.org in anyway such as we do not have a lookup user in ORCID or the ability to add publications from ORCID to our IR. The only link is the entering of the ORCID into the system so that it can be displayed.

An example record is available here: [http://d-scholarship.pitt.edu/28114/ http://d-scholarship.pitt.edu/28114/]

# Users have an ORCID field in their profile – user_fields.pl
# Any “Creator” types have an ORCID field added to the workflow – eprint_fields.pl
# We have added ORCID validation adhering to this document: [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier] - eprint_validate.pl
# We have added the ORCID to the “lookup” function to populate the ORCID field from any user entries in the database. – cgi/users/lookup/name
# We display the ORCID as such on the input form, where the green icon links out to our own orcid.pitt.edu site, but could be to orcid.org by default.
# We display the ORCID as such on the public display of the record where the ORCID is linked out to orcid.org (see [http://d-scholarship.pitt.edu/28114/ example record])

ORCID Validator - snippet for eprints_validate.pl
<source lang="perl">
# ORCID ID Validator for individuals
# Reference: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier
# REGEX: ^\d{4}-\d{4}-\d{4}-(\d{3}X|\d{4})$
#
my @name_fields = qw( creators contributors exhibitors producers conductors lyricists ); #which ever name fields you added 'orcid' to.
foreach my $name_field ( @name_fields )
{
if( $eprint->is_set( $name_field ) )
{
foreach my $creator ( @{ $eprint->value( $name_field ) } )
{
my $orcid = $creator->{orcid};
next unless defined $orcid;
if ($repository->get_repository->can_call ( "validators", "isValidORCID" ) )
{
if (!$repository->get_repository->call( [ "validators", "isValidORCID" ], $orcid ))
{
my $field_text = $repository->html_phrase( "eprint_fieldname_$name_field" );
my $field_frag = $repository->make_element( "span", class=>"ep_problem_field:$name_field" );
$field_frag->appendChild($field_text);
push @problems, $repository->html_phrase( "warnings:orcid_invalid",
orcid => $repository->get_repository->make_text($orcid),
field => $field_frag,
);
}
} else {
$repository->get_repository->log( "Can not call isValidORCID." );
}
}
}
}
</source>

Additional Function that can be placed either at the end of eprints_validate.pl (after the final };) or elsewhere:
<source lang="perl">
############################################
# Function: isValidORCID
# Description: Used to validate ORCID IDs
#
# From: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier (Checksum)
#
$c->{validators}->{isValidORCID} = sub {
my $ORCID = $_[0];
#Check for valid length of 19 characters.
my $size = length($ORCID);
if ($size > 19 )
{
return 0;
} else {
#Check actual validity of the ID mathematically.
$ORCID =~ s/\-//g;
my @chars = split(//, $ORCID);
my $total = 0;
for ( my $i=0; $i<15; $i++) {
$total = ($total + $chars[$i]) *2;
}
my $remainder = $total % 11;
my $result = (12 - $remainder) % 11;
return ($chars[15] == ($result==10 ? 'X' : $result))
}
};
</source>

(Information courtesy of Brian Gregg - bdgregg@pitt.edu)

ORCID

2016-09-16T20:49:57Z

Bdgregg@pitt.edu: /* Notes from Pittsburgh: */ - clarification.

This page has been created to gather information about how different EPrints repositories have integrated ORCID.
At this time (April 2016) there doesn't seem to be a 'best practice' approach that has been adopted widely - this will hopefully change over time.

If you are looking to retrieve publications from the ORCID service, the [http://bazaar.eprints.org/354/ Import from ORCID (Tier 1 API)] Bazaar package, or the [https://github.com/eprintsug/orcidt2 ORCID Tier 2 api framework] are good places to start.

2016-05-20 [[User:Alan.stiles@open.ac.uk|Alan Stiles]] at The Open University is working on a plugin to connect EPrints with ORCID via the Tier 2 Members API to retrieve ORCID ids and synchronise publications and affiliation details.

Some aspects that need to be considered when adopting ORCIDs, and making them available to other systems are:

* storing the ORCID (see: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier)
* rendering the ORCID in abstract pages (see [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier link above])
* exposing ORCIDs over OAI-PMH metadata profiles e.g. RIOXX

NB The examples below may refer to the 'creators' field - but the same approach could be used to extend other 'person' fields - e.g. contributors.

= Re-using creators.id subfield =

The creators.id field is labelled 'email' by default, but as it's an 'id' type field, it can be used to store ORCIDs.
To re-label the field, a simple addition to a phrase file in <code>archives/ARCHIVEID/cfg/lang/en/phrases/</code> needs to be made:
<source lang="xml">
<epp:phrase id="eprint_fieldname_creators_id">ORCID / Creators email (if known)</epp:phrase>
</source>

== Rendering the ORCID in a citation ==
The rendering of this field then needs to be changed to accommodate an author with an ORCID. The following script adds methods that can be called via the EPScript language:

<source lang="perl">
# add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/z_add_to_EPrints_Script_Compiled.pl
# Write into EPrints::Script::Compiled package to allow use of function in epscript
{
package EPrints::Script::Compiled;
use strict;

sub run_wrro_people_with_orcids
{
my( $self, $state, $value ) = @_;

my $session = $state->{session};
my $r = $state->{session}->make_doc_fragment;

my $creators = $value->[0];

foreach my $i (0..$#$creators){

my $creator = @$creators[$i];

if( $i > 0 ){
#not first item (or only one item)
if( $i == $#$creators ){
#last item
$r->appendChild( $session->make_text( " and " ) );
} else {
$r->appendChild( $session->make_text( ", " ) );
}
}

my $person_span = $session->make_element( "span", "class" => "person" );
$person_span->appendChild( $session->render_name( $creator->{name} ) );

my $id = $creator->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
my $orcid_span = $session->make_element( "span", "class" => "orcid" );

# According to https://orcid.org/trademark-and-id-display-guidelines
# "recommended display is a hyperlinked URI preceded by the iD icon"
# This looks terrible in a citation. Removed for the time being.
#
# my $orcid_link = $session->make_element(
# "a",
# "href" => "http://orcid.org/",
# "target" => "_blank",
# "class" => "orcid-icon"
# );
# $orcid_link->appendChild( $session->make_element(
# "img",
# "src" => "/images/orcid_16x16.png",
# "title" => "ORCID"
# ) );
# $orcid_span->appendChild( $orcid_link );

my $link = $session->make_element(
"a",
"href" => "http://orcid.org/$1",
"target" => "_blank",
);
$link->appendChild( $session->make_text( "orcid.org/$1" ) );

$orcid_span->appendChild( $session->make_text( "(" ) );
$orcid_span->appendChild( $link );
$orcid_span->appendChild( $session->make_text( ")" ) );

$person_span->appendChild( $session->make_text( " " ) );
$person_span->appendChild( $orcid_span );
}
$r->appendChild( $person_span );
}

return [ $r, "XHTML" ];
}

}
# END EPrints::Script::Compiled additions
</source>

You may also want a bit of CSS to style ORCID links
<source lang="css">
/* Add to e.g. ~/archives/ARCHIVEID/cfg/static/style/auto/zzz_orcid.css */
.person:hover {border-bottom: 1px dashed #a6ce39;}
.orcid {}
.orcid a:hover {
color: #a6ce39;
}
.orcid-icon {}
.orcid-icon img { vertical-align: text-bottom; margin: 0 4px 0 2px; }
</source>

And finally, you have to call the new EPScript function from a citation file e.g. <code>archives/ARCHIVEID/cfg/citations/eprint/default.xml</code>
<source lang="xml">

<print expr="wrro_people_with_orcids(creators)" />
</source>

== Exposing the ORCID in RIOXX ==
Based on re-using the creators.id field, this block of code over-writes the default <code>rioxx2_value_author</code> function.
<source lang="perl">
# Add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/zzz_rioxx2_overwrites.pl
$c->{rioxx2_value_author} = sub {
my( $eprint ) = @_;

my @authors;
for( @{ $eprint->value( "creators" ) } )
{
my $id = $_->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
id => "http://orcid.org/$1"
};
} else {
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
};
}
}

#NB If your corp_creators has DOIs or ISNIs for the entries, a similar method could be used to include these here.
foreach my $corp ( @{ $eprint->value( "corp_creators" ) } )
{
my $entry = {};
$entry->{name} = $corp;
push @authors, { author => $corp };
}

return \@authors;
};

</source>

= Add additional identifiers to creators =
Another approach to storing ORCIDs is to add an additional sub-field to the creator field.
This has been discussed on the Eprints tech list. If you know how to do this, please document it here!

This is how University of Bath has done it. We're getting the ORCID data from another system, so have used a text field to capture it for display. At present there is no special rendering on it, it's just displaying as a number.
<source lang="perl">
{
name => 'creators',
type => 'compound',
multiple => 1,
fields => [
{
sub_name => 'name',
type => 'name',
hide_honourific => 1,
hide_lineage => 1,
family_first => 1,
},
{
sub_name => 'id',
type => 'text',
input_cols => 20,
allow_null => 1,
},
{
sub_name => 'orcid',
type => 'text',
input_cols => 20,
allow_null => 1,
}

],
input_boxes => 4,
},
</source>
This is how University of Pittsburgh has done it:
<source lang="perl">
{
'name' => 'creators',
'type' => 'compound',
'multiple' => 1,
'fields' => [
{
'sub_name' => 'name',
'type' => 'name',
'hide_honourific' => 1,
'hide_lineage' => 1,
'family_first' => 1,
},
{
'sub_name' => 'email',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'id',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'orcid',
'type' => 'id',
'input_cols' => 19,
'allow_null' => 1,
},
],
'input_boxes' => 4,
'render_value' => 'custom_render_creators_with_orcid',
},

</source>

==Notes from Pittsburgh:==

We have added some ORCID functionality in our IR System here at the University of Pittsburgh. We however have not “linked” our IR with orcid.org in anyway such as we do not have a lookup user in ORCID or the ability to add publications from ORCID to our IR. The only link is the entering of the ORCID into the system so that it can be displayed.

An example record is available here: [http://d-scholarship.pitt.edu/28114/ http://d-scholarship.pitt.edu/28114/]

# Users have an ORCID field in their profile – user_fields.pl
# Any “Creator” types have an ORCID field added to the workflow – eprint_fields.pl
# We have added ORCID validation adhering to this document: [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier] - eprint_validate.pl
# We have added the ORCID to the “lookup” function to populate the ORCID field from any user entries in the database. – cgi/users/lookup/name
# We display the ORCID as such on the input form, where the green icon links out to our own orcid.pitt.edu site, but could be to orcid.org by default.
# We display the ORCID as such on the public display of the record where the ORCID is linked out to orcid.org (see [http://d-scholarship.pitt.edu/28114/ example record])

(Information courtesy of Brian Gregg - bdgregg@pitt.edu)

How to use EPrints with HTTPS

2015-10-06T15:09:55Z

Bdgregg@pitt.edu: /* Updated to reflect more recent versions of EPrints */

{{manual}}
[[Category:Authentication]]
For information on setting up HTTPS on EPrints versions earlier than 3.0.5 see [[Https3]].

If you are using Debian/Ubuntu see [[HTTPS for Debian/Ubuntu]].

''Note: Setting up your Apache Web server is beyond the scope of this document. Please see your operating system documentation and the Apache documentation for assistance in setting up Apache in your environment.''

== Configuration ==

To start setting up your existing archive to work under HTTPS, you must first edit <tt>archives/[repoid]/cfg/cfg.d/10_core.pl</tt>. Initially it will probably look something like the following which is the basic 10_core.pl configuration file after you have run <tt>bin/epadmin create</tt> to setup your archive. Alternatively you could run <tt>bin/epadmin config_core [repoid]</tt> that will prompt you for the following information. It is suggested that you make a backup of the 10_core.pl file regardless before proceeding.

$c->{host} = 'your.dnshostname.org';
$c->{port} = 80;
$c->{aliases} = [];
$c->{securehost} = '';
$c->{secureport} = 443;
$c->{http_root} = undef;

Update the file to define the secure host and modify ports as needed. If your Apache web server is not using the standard ports (80,443) you can adjust the 'port' and 'secureport' parameters in the config file accordingly.

$c->{host} = 'your.dnshostname.org';
$c->{port} = 80;
$c->{aliases} = [];
$c->{securehost} = 'your.dnshostname.org';
$c->{secureport} = 443;
$c->{http_root} = undef;

These additional settings may (but rarely) come into play are the following for special or for older setups. In general these settings are only used when dealing with keeping settings from earlier versions of the EPrints software where you've migrated the 10_core.pl file from originally. These configuration parameters tend to be deprecated.

$c->{securepath} = '/secure';
$c->{https_root} = '/secure';
$c->{http_cgiroot} = '/cgi';
$c->{https_cgiroot} = '/secure/cgi';

== Generate the Apache Configuration File for HTTPS ==

Run <tt>bin/generate_apacheconf</tt> to generate the secure Apache configuration files and depending upon the version of EPrints you are using, it may copy the default template <tt>archives/[repoid]/cfg/lang/en/templates/default.xml</tt> to the template used for HTTPS <tt>archives/[repoid]/cfg/lang/en/templates/secure.xml</tt>. This will also setup the repository configuration file located in the <tt>/opt/eprints3/cfg/apache_ssl/</tt> directory named [repoid].conf.

== Add the Main Apache Config File to SSL Config ==

Depending upon the version of EPrints you are running there are a couple files that may be involved. It is recommended to run <tt>bin/generate_apacheconf --man</tt> or view the source of <tt>bin/generate_apacheconf</tt> file to understand what file(s) need to be setup. In general you will need to place a line like either of the following inside your Apache SSL Virtual Host declaration (most likely found in <tt>/etc/httpd/conf.d/mod_ssl.conf</tt> or <tt>/etc/httpd/conf.d/ssl.conf</tt>). Make sure that these lines are placed inside the <VirtualHost> Apache directive.

Include /opt/eprints3/archives/[repoid]/var/auto-secure.conf

Or

Include /opt/eprints3/cfg/apache_ssl.conf

== Restart Apache to pick up the changes to the Apache configuration ==
Consult your operating system documentation on how to restart service processes but in general you need to run one of the following commands either as <tt>root</tt> or using <tt>sudo</tt>:
# /sbin/service httpd restart

# /etc/init.d/apache2 restart

== Confirmation ==

Open your web browser and access your repository via its URL, this should be done over HTTP. When you click to login you should notice that you will be redirected to an HTTPS connection. Note that in general most tasks that require you to login are now redirected to an HTTPS connection otherwise an HTTP request will be used.

Views.pl

2015-08-27T14:25:42Z

Bdgregg@pitt.edu: Added the max_items view option per EP-Tech mailing list suggestion.

[[Category:Browse Views]]
[[Category:Documentation Needed]]
== Views ==
Conceptually a ''view'' is a browsable list of eprints split into ''menus'' and a ''list''.

<div align="center">
{| cellpadding="0" cellspacing="0" border="0"
|-
| style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px" |Menu1
|  
|  
|  
|  
|-
| style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px"|   Item1_1 ------
| style="font-size:10px"|--->
| style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px"|Menu2
|  
|  
|-
|style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; font-size:10px"|   Item1_2
|  
|style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px"|   Item2_1 -----
|style="font-size:10px"|--->
|style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px"|     LIST    
|-
|style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px"|   ....
|  
|style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px"|   Item2_2
| 
|style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px"|   ....
|-
|  
|  
|style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px"|   ....
|  
| 
|}
</div>
In a ''menu'' values of one (or more) fields are listed, and a link points to the collection of all items with that particular value in that field.

The ''list'' contains the final list of eprints with field values as determined by the menus above it.

== Options available for the views config ==
This link is an [http://wiki.eprints.org/w/Adding_new_views 'How to' about views] with examples.

The general form of views definition is

$c->{browse_views} = [
{ <first view definition> },
{ <second view definition> },
...
{ <last view definition> },
];

(be careful about commas and semicolons). The order of the view definitions determines the order in which these will appear in the <nowiki>http://repoid/view/</nowiki> page.

Each view definition is a collection of attributes, given as

attribute1 => value1,
attribute2 => value2,
...

(again, the ''value'' should end by a comma). The ''value'' can be
*''integer''
*''string'' enclosed by quotation marks (") or by apostrophes (')
*''array'' which starts by a square bracket [ followed by the elements of the array (separated by commas) and closed by ] or
*''hash'' which is a list of "attribute => value" pairs enclosed by curly brackets { and }.
Thus the browse_views definition is an array of hashes.

Attributes marked by (V) are ''view'' attributes and are in the view definition; attributes marked by (M) are ''menu'' attributes and should be used only in [[#Menu options|menu definitions]].

==Basic options==

Options in the first category are ''view'' options.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id (V)
| (mandatory) String, this is the ID by which you will refer to this view, and also the name of the top directory in <nowiki>http://repoid/view/</nowiki>. This is the value of the ''browse_link'' attribute in [[eprint_fields.pl]]. Example:

id => 'divisions',
|- valign="top"
|fields (V)
|(deprecated) This attribute describes the field(s) by which the view is built. It has been replaced by the more general [[#Menu options|menus]] attribute.
|- valign="top"
|hideempty (V)
allow_null (V)
new_column_at (V)
render_menu (V)
|These define the default values of the same attributes in all [[#Menu options|menus]]. I.e, if not defined otherwise there, they take this as the default value in this view. "Hideempty" is also used when rendering the [[#View list options|view]] list.
|- valign="top"
|menus (V)
|An array of ''[[#Menu options|menu descriptions]]''. Each ''menu'' is a refinement of the previous ones, and last menu points to the [[#View list options|view list(s)]]. In each menu, as minimum, you should give the field(s) which are used to define entries at that level. The menus definition looks like
menus => [
{ <first menu definition> },
{ <second level menu> },
{ <last level> },
],
You must have at least one menu level.
|- valign="top"
|template (V)
|Define an alternate template for all pages in this view. The template page should be a proper xml file in the <tt>repoid/cfg/lang/<langid>/templates/</tt> directory. The best way is to copy the default.xml file and edit it according to taste.
template => 'view_template',
|- valign="top"
|nolink (V)
|When this is set to 1 by adding
nolink => 1,
then this view won't appear in the outmost <nowiki>http://repoid/view/</nowiki> browse page.
|- valign="top"
| max_menu_age (V)
| Defaults to 86400 (one day in seconds). If the menus in this view has been generated more than that many seconds ago, it is regenerated.
|- valign="top"
| max_items (V)
|Defaults to 2000. If the items list is larger increase the number enough to accomodate the number of items needed to be displayed.
max_items => 3000,
|}

===View list options===
These are the options which determine how the last list page in the menu chain should look like. They must be entered at the outmost ''view'' level.
{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order (V)
|This defines how the items in the view list (at the lowest level) are ordered. The format is 'foo/-bar'. This means that the list will be sorted by 'foo' and then any equal 'foo' values will be reverse sorted by 'bar'. More than 2 fields can be specified. Example:
order => "-date/title",
|- valign="top"
|hideup (V)
|Don't show the "up one level" link in the list page. You ''must'' set this attribute for each menu separately, it is not inherited.
|- valign="top"
|hideempty (V)
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount (V)
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp (V)
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations (V)
|An array of strings describing different rendering of the items at the ''list''. For datails see [[#Variations|variations]]. Example:
variation => [ "creators_name;first_letter",
"type", "DEFAULT", ],
|- valign="top"
|layout (V)
|Possible values are
*paragraph (default)
*orderedlist
*unorderedlist
Determines how items in the list (or sublist) is rendered. In the first case each item is a paragraph by itself. In the other cases items are rendered as an ordered (unordered) list.
|- valign="top"
|citation (V)
|The citation style defined in archives/<REPOID>/cfg/citations/eprint/ which is used to render each item. Example:
citation => 'screen',
|- valign="top"
|max_list_age (V)
|Defaults to 86400 (one day in seconds). If the lists in this view were generated more than than many seconds ago, it is regenerated.
|}

===Variations===

Variations, if defined, determine how the final list is rendered. ''Variations'' is an array of strings, for example,

[ "creators_name;first_letter",
"type",
"DEFAULT",
]

For each string in the list, a different rendering is produced, and you can switch from one to the other. The variation "DEFAULT" is the default one, it is always a good practice to include it in the list. If no variation is given, "DEFAULT" is used.

A ''variation definition'' consists of a field name, followed by zero, one or more ''options'' after a semicolon. Options are separated by commas. An ''option'' is either a single attribute, or an attribute, an equal sign, and the value of the attribute. For example,
"creators_name;truncate=4,hideup"
sets the attribute value "truncate" to 4, and "hideup" to 1 (or true).

The following options are available. These options are ''part of the string'' defining the variation, and ''should not be entered'' as attributes.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|reverse
|Reverses the order in which the groupings are shown. Default is the ordervalue for that field (usually alphanumeric). Useful for dates as you may want the highest values first.
|- valign="top"
|filename
|Changes the filename of the view variation. The default is the name of the metadata field used, so if two variations use the same metadata field with different options, this is needed.
filename=different_filename
|- valign="top"
|first_value
|If a field is multiple, only use the first value. Otherwise each item will appear once for each value.
|- valign="top"
|first_initial
|If using a name, truncate the given name to the first initial. This will make items like "Les Carr" and "Leslie Carr" appear together. Note it will also make "John Smith" and "Jake Smith" appear together too, showing that you really never can win.
|- valign="top"
|first_letter
|The same as 'truncate=1'
|- valign="top"
|truncate
|Use the first X characters of a value to group by. truncate=4 may be useful for dates as it will group by the first four digits (the year) only.
truncate=4
|- valign="top"
|tags
|Useful for fields like keywords where values may be separated by commas or semi-colons. The value is split on these two characters ( , and ; ) and a heading is created for each.
|- valign="top"
|cloud
|Creates a tag cloud. Sets jump to 'plain', cloudmax to 200, cloudmin to 80 and no_separator, then resizes the jump-to links according to frequency of use.
|- valign="top"
|cloudmax
|The % size of the largest tag in a tag cloud.
|- valign="top"
|cloudmin
|The % size of the smallest tag in a tag cloud.
|- valign="top"
|jump
|Possible values are 'plain', 'default', and 'none'. Example:
jump=plain
When set to 'plain' turns off the 'jump to' text before the list of subheading navigation links. When 'none', then the 'jump' part is not rendered.
|- valign="top"
|no_seperator (sic)
|Turns of the separator between each subheading navigation link (by default a vertical bar symbol).
|- valign="top"
|string
|Uses values 'as is'. No ordervalues, no phrases.
|- valign="top"
|hideup (since 3.1.1)
|Defaults to "0". If set to "1" this hides the "up to parent" link (often you want to hide this on .include files)
|- valign="top"
|render_fn
|Name of a function to render this groupings list of items. For an example, see views_render_items_example.pl
|}

===Menu options===

These options can only be used in the '''menu definitions'''.

{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields (M)
|Obligatory, an array of field identifiers. Items in all fields are merged together. For example, to define a list of those those who are either authors or editors or both, use the definition

fields => [ "creators_id", "editors_id" ],

Even if there is a single field, you must use square brackets, such as

fields => [ "subjects" ],

<div style="color: #662211; background-color:#ddffdc; border:1px solid black; padding:3px;">'''Important!''' All fields must have the same type - i.e. you cannot mix titles and authors, say.</div>

You can also add extra rendering info to the field name, without the "render_" prefix. For example, to make a date have resolution year, you would write

fields => [ "date;res=year" ],

or, ordering authors by their ''given'' names rather than by their family names:

fields => [ "creators_name;order=gf" ],

You can add ";quiet" to the field name to force non-existing values to appear as empty space rather than the ugly "UNDEFINED" (see the allow_null property below). You can find the available rendering properties of different fields in the [[Metadata]] section.
|- valign="top"
|allow_null (M)
|The ''undefined'' value among the possible values of the fields does not show up in the generated view. To allow the undefined value to appear as well, set

allow_null => 1,

Beware: the title of the undefined entries will be the ugly UNDEFINED. You might consider to use the ";quiet" rendering option for field names.
|- valign="top"
|hideempty (M)
|If a category is empty, don't show it as an entry. Default value: show all entries, even if they contain no entries. Used only in menus, not at the lower level (list).
Example:

hideempty => 1,
|- valign="top"
|reverse_order (M)
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode (M)
|Possible values: ''[[#Sections|sections]]'' and ''default'' (default). When defined as ''sections'' then grouping can be defined by the following data:
* ''grouping_function'' (group by first character if not defined)
* ''group_sorting_function'' (how to sort members of a group)
* ''group_range_function''
* ''open_first_section'' the front page should show the first section
See [[#Sections|below]].
|- valign="top"
|hideup (M)
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu (M)
|The configuration parameter which renders this menu. This should be a string, and also you should define a routine with the same name. For example if you write
render_menu => 'render_view_menu_3col_boxes',
then this menu will be rendered by the routine which is defined in [[views_render_menu_example.pl]] as
$c->{render_view_menu_3col_boxes} = sub
{
...
}
See there for hints how to tweak your own routine.
|- valign="top"
|new_column_at (M)
|Used in menus (not lists) and in default mode. This is an array of integers representing the number of items in a view list before another column is added. For example:

[ 11 ]

The menu is rendered as a single column data if there are less than 11 entries, then there would be 2 columns.

[ 11, 21 ]

This would have one column if there were ten or less values, two columns if there are twenty or less, and three columns for all other cases.

[ 0, 0 ]

This would always have three columns.

[ 2, 3 ]

This would have one column for a single data, two columns for two, and three columns for three or more data.

Add one to the number of integers in the array and you get the maximum number of columns. The entries are evenly distributed in the columns.
|}

===Sections===

When a menu is using "sections", then items on the menu are grouped together. The exact method is defined by defining values for several options. These options go to the ''menus section'' as well.

{|border="1" cellpadding="4" cellspacing="0"
|-valign="top"
|grouping_function (M)
|This function determines how grouping is done. The following predefined functions can be used:
*"EPrints::Update::Views::group_by_a_to_z"
*"EPrints::Update::Views::group_by_first_character" (default)
*"EPrints::Update::Views::group_by_2_characters"
*"EPrints::Update::Views::group_by_3_characters"
*"EPrints::Update::Views::group_by_4_characters"
*"EPrints::Update::Views::group_by_5_characters"
with the usual meaning. If you use 'group_by_a_to_z', all entries not starting with a letter will be discarded.
|-valign="top"
|group_sorting_function (M)
|A costum function which sorts the group identifiers. The only available function
*"EPrints::Update::Views::default_sort"
sorts alphabetically.
|-valign="top"
|group_range_function (M)
|Splits the groups (as determined by the grouping function) into sections so that a group never splits. Groups are rendered separately, but a section is kept on a single page. Available grouping functions are
*"Eprints::Update::Views::no_ranges" (default)
*"EPrints::Update::Views::cluster_ranges_<range>"
where <range> is one of 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, and 200.
|-valign="top"
|open_first_section (M)
|if set, the first section is included in the front page.
|}

==Phrases==

Views can have their own titles and other phrases. If they do not exist, then a default one is used (usually containing the view's id). For examples, see the views.xml file.

{|border="1" cellpadding="3" cellspacing="0"
|-valign="top"
|viewname_eprint_<viewid>
|the name of the browse pages
|-valign="top"
|viewintro_<viewid>
|The phrase to replace the text "Please select a value to browse from the list below." in the top level menu
|-valign="top"
|viewintro_<viewid>/<value>
|Intro phrase on the next level
|-valign="top"
|viewtitle_eprint_<viewid>_menu_<level>
|Title of browse page at level <level>, which is 1, 2, ... In the phrase you can use the pins "value1", "value2", etc. where the number can be one less than the present level; the value of the pin is the actual value of the previous levels. See the example below.
|-valign="top"
|viewgroup_eprint_<viewid>_<filename>
|Used as a pin value for the title on the list pages, when [[#Variations|variations]] are used. <Filename> is the filename defined as the option of the variation, or, if it is not defined, then it is the fieldname at the beginning.
|-valign="top"
|viewtitle_eprint_<viewid>_list
|Title of the list pages of the view. You can use the same pins as before ("value1", "value2", etc.). If the list was generated by a [[#Variations|variation]] then the "grouping" pin is also available.
|}

The following example shows how to define these values.
<epp:phrase id="viewname_eprint_divisions">Divisions</epp:phrase>
<epp:phrase id="viewtitle_eprint_divisions_menu_1">
Browse by Division and Year</epp:phrase>
<epp:phrase id="viewtitle_eprint_divisions_menu_2">
Browse by Year where Division is
<epc:pin name="value1" /> </epp:phrase>

==Other==

{|border="1" cellpadding="4" cellspacing="0"
|heading_level
| ?
|-
|include
| ?
|-
|subheadings
| ?
|-
|nohtml
| ?
|-
|noindex
| ?
|}

=Example=
==EPrints 3.2 example==
===cfg/cfg.d/views.pl===
{ id => "target", # The 'name' for this view
allow_null => 0,
hide_empty => 1,
menus => [
{ fields => ["broker_reponame"], # The field(s) to use - in this case the 'reponame' sub-element of the 'broker' field
new_column_at => [0], # force 2 columns, even if the
# second is blank
mode => "sections",
open_first_section => 1,
group_range_function => "EPrints::Update::Views::cluster_ranges_30",
group_sorting_function => "EPrints::Update::Views::default_sort",
},
],
order => "-date/title",
citation => 'router', # This defines the file in cfg/citations/eprint/
layout => 'router', # This is used in Views.pm to determine how to
# join individual citations together...
},

This creates a view, which will be 2-columns wide.
Two important definitions here are:
* '''citation''' defines the citation file used to create the block of html for each record to be displayed, and
* '''layout''' indicates how those blocks are joined together.

====Layout====
'''Layout''' can be one of:
* paragraph (the default)
puts elements round each citation

* orderedlist
makes an ordered list (1,2,3,4 or whatever the CSS defines)

* unorderedlist
makes an unordered list

* ''anything else''
just puts a newline (in the page source) after each citation

====citation====
In our example, we're using a home-made citation layout

The citation file is in <code>/cfg/citations/eprint/</code>

In the above view, we have defined the citation format to be '''router''', therefore we need a file called '''router.xml''' in the citations directory.

Remember this format is used for each record, so needs to be complete in it's own right - and if you want records to line up vertically, you need to plan that in advance.

<?xml version="1.0" ?>

<cite:citation xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns="http://eprints.org/ep3/control" xmlns:cite="http://eprints.org/ep3/citation" >
<table class='ep_rt_citation'>;
<tr><td colspan='2'>
<choose>
<when test="type = 'book' and is_set( creators )">
<print expr="creators_name"/>
</when>
.... more code ....
</choose>
</td><td style="width:8em">
<if test="date">(<print expr="date" opts="res=year"/>)</if>
</td></tr>
<tr><td style="width:50%">
<cite:linkhere><xhtml:em><print expr="title" opts="magicstop"/></xhtml:em></cite:linkhere>
</td>
<choose>
.... more code
<when test="type = 'article'">
<td>
<if test="publication"><print expr="publication"/>
<if test="volume">, <print expr="volume"/></if>
<if test="number"> (<print expr="number"/>)</if>
.</if>
<if test="pagerange"> <print expr="pagerange"/>.</if>
</td><td>
<if test="issn"> ISSN <print expr="issn"/></if>
</td>
</when>
.... more code
</choose>
</tr>
<if test=" ! type.one_of( 'patent','thesis' )">
<if test="ispublished.one_of('unpub', 'submitted', 'inpress')">
<tr><td colspan='2'>
(<print expr="ispublished"/>)
</td></tr>
</if>
</if>
</table>
</cite:citation>

This creates a table for each record, and CSS is used to manage the size & position of the various elements

===cfg/cfg.d/eprint_render.pl===
When viewing a record, the main abstract view page can also be altered

In <code>cfg/cfg.d/eprint_render.pl</code>, towards the bottom of the subroutine <code>$c->{eprint_render}</code> is the following line:

my $page = $eprint->render_citation( "router_page", %fragments, flags=>$flags );

Here, '''router_page''' is the name of the citation file for creating the abstract page..... '''router_page.xml''' in this case