EPrints Documentation - User contributions [en-gb]

Secure login

2009-08-01T22:42:54Z

Laci@degas.ceu.hu: /* Caveats */

When logging into eprints, both username and password travel openly. Usually it is not a problem as eprints has its own authenticating mechanism, and stealing an eprints password gives the intruder very limited power. However when using centralized authentication (e.g., by [[LDAP]]) then protecting the password is more important. To prevent sniffing, login pages usually use secure connection. Here we discuss an easy way to set up eprints to use encoded password traffic.

__TOC__

==The idea==

Change the destination of the eprints login page to a secure host. On the secure host a script receives the data: login name and password (and maybe others), encodes it, and forwards the request with the encrypted data as payload to an unencrypted eprints page. The eprints page decrypts the data and uses it for authentication.

===Requirements===
You need a ''secure http server'' on the same main domain as your eprints server. For example, if eprints can be reached on the web address ''<nowiki>http://eprints.umb.edu</nowiki>'', then the secure server must have domain name ending with ''umb.edu'', for example ''<nowiki>https://secure.umb.edu</nowiki>.

You should set up a cgi executable directory on the secure host. The apache config extract below does exactly this so that ''<nowiki>https://secure.umb.edu/eprints/whatever</nowiki>'' requests the script ''/opt/cgi-bin/eprints/whatever'' to be executed:
<VirtualHost *:443>
DocumentRoot "/opt/secure"
SSLEngine on
ScriptAlias /eprints/ /opt/cgi-bin/eprints/
<Directory "/opt/cgi-bin/eprints">
AllowOverride None
Options +ExecCGI -MultiView +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Copy the [[#Secure login script|Secure login script]] below into the ''/opt/cgi-bin/eprints/'' directory (or whatever directory you've set up above); copy the [[#Receive data script|receive data script]] into eprints' ''/cgi/'' directory.

Finally [[#Patching Apache::Login |patch the Apache::Login module]] of eprints so that everything works smoothly.

===Caveats===
The login process now works as follows.
# when a page requires authentication, it creates a "login page" with destination at the secure web site
# data entered to the "login page" is sent encrypted to the secure site
# the secure site encrypts the payload, and redirects the browser to the unencrypted eprints page ''receive_data''
# ''receive_data'' decrypts the payload, checks credentials, logs in the user if everything checks, and then redirects the browser to the originating page.

What is lost in this process of two redirects is the error message when authentication fails. ''Receive_data'' cannot display the error message as its URL should not be displayed on the user's screen. The final page - which is the original one as well - cannot distinguish between an unsuccessful login and a reload, thus cannot display the error message as well. ''[http://en.wikipedia.org/wiki/C'est_la_vie C'est la vie]''.

The encrypted data the ''receive_data'' page receives can be a replay of a sniffed older communication. Thus this data should contain a timestamp which should be checked to be recent. It also means that '''the secure and eprint servers must synchronize their clocks'''.

The secure site can also check the credentials, and relay the result only. Interestingly, the result should be sent encrypted, as otherwise the secure site could be used as an [http://en.wikipedia.org/wiki/Oracle oracle] to tell whether the password is correct or not (ideal utility for a [http://en.wikipedia.org/wiki/Dictionary_attack dictionary attack]).

==Secure login script==
This script receives the login page over a secure connection. It encrypts the username, password, and other arguments, and relocates the page to eprints' ''receive_data'' page.

Using the secure site configuration above, this script should be copied to ''/opt/cgi-bin/eprints/login'' after changing the address to your own eprint server. And, of course, the script must be executable by the apache process.

##!/usr/bin/perl -w
## secure login script for eprints
## encrypt and automatically forward to /eprints
## Author: Laszlo Csirmaz, 2009
## You are free to use this script
use strict;
sub _RelocateTo {
my $arg=shift;
## CHANGE THIS ADDRESS TO YOUR EPRINT SERRVER'S
"<nowiki>http://eprints.umb.edu/cgi/receive_data?Q=$arg</nowiki>";
}
<nowiki><-- COPY THE CRYPTO ROUTINES HERE --></nowiki>
sub _html2ascii {
my $v=shift;
$v="" if(! defined $v);
$v=~ tr/+/ /;
$v=~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
return $v;
}
my $P={};
my $ct=$ENV{'CONTENT_TYPE');
if($ct && $ct =~ /multipart/i ){
use CGI qw( :cgi :form );
my $req=new CGI; # read all data in
my @pm=$req->param;
foreach my $key (@pm) {
$P->{$key} = _html2ascii($req->param($ley));
}
} elsif ( $ENV{'REQUEST_METHOD'} !~ /^get/i ) {
my $pm=""; while(<>){ $pm .= $_; }
my @pms=split(/&/,$pm);
foreach my $elem(@pms) {
my($t,$v)=split(/=/,$elem);
next if(! defined($t) );
$P->{_html2ascii($t)} = _html2ascii($v);
}
}
## we return the following arguments:
## target, loginparams, username, pw, timestamp
my $arg="";
for my $item ($P->{target},$P->{loginparams},
$P->{login_username}, $P->{login_password} ){
$item="" if(! $item)[
# replace '%' by '%a' and replace ':' by '%c'
$item =~ s/%/%a/g; $item =~ s/:/%c/g;
$arg .= "$item:";
}
my $addr = _RelocateTo( _EncodeValue( $arg . int(time/60) ) );
print "Content-Type: text/html; charset=utf-8\n",
"Location: $addr\n",
"\n",
"<html><head><title>Redirected</title></head>\n",
"<body>\n",
"This page should automatically relocated. If not,\n",
"please <a href=\"$addr\">click here</a>.\n",
"</body>\n",
"</html>\n",
"\n";
exit 0;

==Receive data script==
This script receives the encrypted data from the secure server, decrypts it and logs in the user. A 1 second delay is inserted if there is a problem with the credentials.

This script should be copied to the ''eprints/cgi/receive_data''. It calls the ''check_user_password'' configuration procedure if it is defined.
######################################################
# receive_data
# Part of EPrints 3.1
# Author: Laszlo Csirmaz
# You are free to use/modify this script
######################################################
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );
my $redirect_to="/cgi/users/home";
my $loginparams="";
my $OK=1;
my $arg = $session->param('Q');
if( $arg && length($arg) > 10 ){ #sanity check
$arg = _DecodeValue($arg);
## it is target:loginparams:uname:pw:timenow
$arg = "/cgi/users/home::::" if(!$arg);
my @list = split(/:/,$arg);
for my $i(0..4){
$list[$i]="" if(!$list[$i]);
$list[$i] =~ s/%c/:/g; $list[$i] =~ s/%a/%/g;
}
$OK=0 if( $list[4] !~ /^\d+$/ );
if($OK){
my $timediff = int(time/60) - $list[4];
#allow a 2 minute window
$OK=0 if( $timediff<-1 || $timediff > 2 );
}
$redirect_to = $list[0] if($list[0] =~ m#/# );
$loginparams = $list[1];
if($OK){
if( $session->valid_login($list[2],$list[3] ) ){
my $user = EPrints::DataObj::User::user_with_username(
$session,$list[2]);
$session->login($user);
$OK=2;
}
}
}
sleep 1 if( $OK != 2 ); # some problem, don't hurry
my $host = $session->{repository}->get_conf( "host" );
my $port = $session->{repository}->get_conf( "port" );
$redirect_to = "<nowiki>http://$host</nowiki>".($port!=80 :":$port":""). $redirect_to;
$redirect_to .= "?$loginparams" if($loginparams);
$session->redirect( $redirect_to );
$session->terminate;
exit 0;
<nowiki></nowiki>
While we made a lot of effort to protect the integrity and secrecy of the username and the data, nothing prevents a bad guy to submit bogus data to our secure script! Thus we relocate to the eprints repository addresses only, and accept the "relocate" argument only if it starts with a slash.

==Crypto routines==
These routines perform encryption and decryption. It is a lightweight version of more sophisticated ones, but (at least I hope) it is sufficient for this application. After the source there are some remarks for those interested.

<div style="padding:4px; background-color: #ffe0e0;border:1px solid #a06060;">'''Warning!''' The secret phrase in the second line should be changed to some secret value. And it should be the same in both copies.</div>
sub _secret {
"Whatever is your secret phrase, give anything here";
}
sub _intto64 { #a MIME64 type encoding
my $c=shift;
$c &=0x3F;
if($c<10){ return chr(48+$c); }
if($c<10+26){ return chr($c-10+65); }
if($c<10+26+26){ return chr($c-10-26+97); }
if($c==62){ return '_'; }
return '-';
}
sub _encode64 { #encoding three bytes to four chars
my($a,$b,$c)=@_;
$a &= 0xFF; $b &= 0xFF; $c &= 0xFF;
return _intto64($a>>2)._intto64(($a<<4)|($b>>4)).
_intto64(($b<<2)|($c>>6))._intto64($c);
}
sub _from64 { #decoding of the above
my $c=ord(shift||"0");
if($c==95){ return 62;}
if($c==45){ return 63;}
if($c<48+10){ return $c-48; }
if($c<65+26){ return $c-65+10; }
return $c-97+10+26;
}
sub _decode64 { # decoding four chars to three bytes
my($s)=shift;
my ($r1,$r2,$r3,$r4)=(
_from64($s),_from64(substr($s,1)),
_from64(substr($s,2)),_from64(substr($s,3)));
return ($r1<<18)|($r2<<12)|($r3<<6)|$r4;
}
sub _EncodeValue { ## encoded value should not end in a space
my($id) = @_;
use Digest::MD5;
my $salt=substr(Digest::MD5::md5_hex($id, _secret()),0,8);
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0; my $ssid="";
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed); my $idlen=length($id);
$id .= " "; # pad message by spaces
for(my $i=0;$i<$idlen;$i+=3){
#encode $id[0],$id[1],$id[2] as 4 chars
my $v=rand(0x1000000);
$ssid .= _encode64(ord(substr($id,$i))^($v>>16),
ord(substr($id,$i+1))^($v>>8),
ord(substr($id,$i+2))^$v);
}
return $salt.$ssid;
}
sub _DecodeValue {
my($s)=@_;
use Digest::MD5;
my($salt,$ssid)=(substr($s,0,8),substr($s,8));
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0;
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed);
my $id="";
for(my $i=0;$i<length($ssid)-3;$i+=4){
#decode next four chars
my $v=rand(0x1000000)^_decode64(substr($ssid,$i));
$id .= chr($v>>16) . chr(0xff&($v>>8)) . chr(0xff&$v);
}
$id =~ s/ +$//; ## strip spaces at the end
# $salt and $chksum should be equal
$id="" if ($salt ne substr(Digest::MD5::md5_hex($id, _secret()),0,8));
return $id;
}
'''Remarks:'''
*The MIME64-like encoding uses letters (both lower and upper case), digits and the characters - (minus) and _ (underscore). These are safe to use in an URL.
*Both encoding and decoding uses MD5 as the building block. The first eight characters of the ciphertext (encoded string) is used for two purposes. First, it acts as a salt, namely it is added to the secret phrase to derive the seed of the random number generator; second it is used to check message integrity, namely it should match the MD5 hash of the message ''and'' the secret phrase.
*Messages to be encrypted (plaintext) should not end by a space (spaces are used to pad the plaintext to have length divisible by three)
*The encryption is deterministic. Such a scheme is insecure in general. In our case, however, the plaintext contains a timestamp, thus - supposedly - the same message is never encrypted twice.
*Weak points of the scheme: only 32 bit MAC (and seed) value, and relying on perl's pseudorandom function.

==Patching Apache::Login==
We are making two changes to the ''perl_lib/EPrints/Apache/Login.pm'' module. First, always store the URI of the referring page in the hidden ''target'' variable. Second, set the address of the login page to the value of the configuration variable ''external_login_address'' whenever it is defined.

The instructions below are for Eprints version 3.1.3. Locate the line
my $form = $session->render_form( "POST" );
in the above module (it should be line 122). Replace it by the following:
##CSL Always use the "target" variable, and
## redirect to "external_login_address"
my $target = $session->param( "target" );
if(! defined($target) ){
$target = $session->get_uri;
}
my $form = $session->render_form(
"POST",
$session->get_repository->get_conf("external_login_address") );
If ''external_login_address'' is not defined, it has the same effect as the old code.
Roll down to line 142 and comment out this line (add # signs at the beginning):
## my $target = $session->param( "target" );
Finally save the file.

==Define "external_login_address"==
Add the definition of this variable to the file [[archives/ARCHIVEID/cfg/cfg.d/]][[user_login.pl]]:
$c->{external_login_address} = "<nowiki>https://secure.umb.edu/eprints/login</nowiki>";
In the same file you can define the sub ''check_user_password'' as explained in [[LDAP]] and [[LDAP user_login.pl]].

[[Category:Howto]]

Secure login

2009-08-01T22:34:38Z

Laci@degas.ceu.hu: /* Patching Apache::Login */

When logging into eprints, both username and password travel openly. Usually it is not a problem as eprints has its own authenticating mechanism, and stealing an eprints password gives the intruder very limited power. However when using centralized authentication (e.g., by [[LDAP]]) then protecting the password is more important. To prevent sniffing, login pages usually use secure connection. Here we discuss an easy way to set up eprints to use encoded password traffic.

__TOC__

==The idea==

Change the destination of the eprints login page to a secure host. On the secure host a script receives the data: login name and password (and maybe others), encodes it, and forwards the request with the encrypted data as payload to an unencrypted eprints page. The eprints page decrypts the data and uses it for authentication.

===Requirements===
You need a ''secure http server'' on the same main domain as your eprints server. For example, if eprints can be reached on the web address ''<nowiki>http://eprints.umb.edu</nowiki>'', then the secure server must have domain name ending with ''umb.edu'', for example ''<nowiki>https://secure.umb.edu</nowiki>.

You should set up a cgi executable directory on the secure host. The apache config extract below does exactly this so that ''<nowiki>https://secure.umb.edu/eprints/whatever</nowiki>'' requests the script ''/opt/cgi-bin/eprints/whatever'' to be executed:
<VirtualHost *:443>
DocumentRoot "/opt/secure"
SSLEngine on
ScriptAlias /eprints/ /opt/cgi-bin/eprints/
<Directory "/opt/cgi-bin/eprints">
AllowOverride None
Options +ExecCGI -MultiView +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Copy the [[#Secure login script|Secure login script]] below into the ''/opt/cgi-bin/eprints/'' directory (or whatever directory you've set up above); copy the [[#Receive data script|receive data script]] into eprints' ''/cgi/'' directory.

Finally [[#Patching Apache::Login |patch the Apache::Login module]] of eprints so that everything works smoothly.

===Caveats===
The login process now works as follows.
# when a page requires authentication, it creates a "login page" with destination at the secure web site
# data entered to the "login page" is sent encrypted to the secure site
# the secure site encrypts the payload, and redirects the browser to the unencrypted eprints page ''receive_data''
# ''receive_data'' decrypts the payload, checks credentials, logs in the user if everything checks, and then redirects the browser to the originating page.

What is lost in this process of two redirects is the error message when authentication fails. ''Receive_data'' cannot display the error message as its URL should not be displayed on the user's screen. The final page - which is the original one as well - cannot distinguish between an unsuccessful login and a reload, thus cannot display the error message as well. ''C'est la vie''.

The encrypted data the ''receive_data'' page receives can be a replay of a sniffed older communication. Thus this data should contain a timestamp which should be checked to be recent. It also means that '''the secure and eprint servers must synchronize their clocks'''.

The secure site can also check the credentials, and relay the result only. Interestingly, the result should be sent encrypted, as otherwise the secure site could be used as an [http://en.wikipedia.org/wiki/Oracle oracle] to tell whether the password is correct or not (ideal utility for a [http://en.wikipedia.org/wiki/Dictionary_attack dictionary attack]).

==Secure login script==
This script receives the login page over a secure connection. It encrypts the username, password, and other arguments, and relocates the page to eprints' ''receive_data'' page.

Using the secure site configuration above, this script should be copied to ''/opt/cgi-bin/eprints/login'' after changing the address to your own eprint server. And, of course, the script must be executable by the apache process.

##!/usr/bin/perl -w
## secure login script for eprints
## encrypt and automatically forward to /eprints
## Author: Laszlo Csirmaz, 2009
## You are free to use this script
use strict;
sub _RelocateTo {
my $arg=shift;
## CHANGE THIS ADDRESS TO YOUR EPRINT SERRVER'S
"<nowiki>http://eprints.umb.edu/cgi/receive_data?Q=$arg</nowiki>";
}
<nowiki><-- COPY THE CRYPTO ROUTINES HERE --></nowiki>
sub _html2ascii {
my $v=shift;
$v="" if(! defined $v);
$v=~ tr/+/ /;
$v=~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
return $v;
}
my $P={};
my $ct=$ENV{'CONTENT_TYPE');
if($ct && $ct =~ /multipart/i ){
use CGI qw( :cgi :form );
my $req=new CGI; # read all data in
my @pm=$req->param;
foreach my $key (@pm) {
$P->{$key} = _html2ascii($req->param($ley));
}
} elsif ( $ENV{'REQUEST_METHOD'} !~ /^get/i ) {
my $pm=""; while(<>){ $pm .= $_; }
my @pms=split(/&/,$pm);
foreach my $elem(@pms) {
my($t,$v)=split(/=/,$elem);
next if(! defined($t) );
$P->{_html2ascii($t)} = _html2ascii($v);
}
}
## we return the following arguments:
## target, loginparams, username, pw, timestamp
my $arg="";
for my $item ($P->{target},$P->{loginparams},
$P->{login_username}, $P->{login_password} ){
$item="" if(! $item)[
# replace '%' by '%a' and replace ':' by '%c'
$item =~ s/%/%a/g; $item =~ s/:/%c/g;
$arg .= "$item:";
}
my $addr = _RelocateTo( _EncodeValue( $arg . int(time/60) ) );
print "Content-Type: text/html; charset=utf-8\n",
"Location: $addr\n",
"\n",
"<html><head><title>Redirected</title></head>\n",
"<body>\n",
"This page should automatically relocated. If not,\n",
"please <a href=\"$addr\">click here</a>.\n",
"</body>\n",
"</html>\n",
"\n";
exit 0;

==Receive data script==
This script receives the encrypted data from the secure server, decrypts it and logs in the user. A 1 second delay is inserted if there is a problem with the credentials.

This script should be copied to the ''eprints/cgi/receive_data''. It calls the ''check_user_password'' configuration procedure if it is defined.
######################################################
# receive_data
# Part of EPrints 3.1
# Author: Laszlo Csirmaz
# You are free to use/modify this script
######################################################
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );
my $redirect_to="/cgi/users/home";
my $loginparams="";
my $OK=1;
my $arg = $session->param('Q');
if( $arg && length($arg) > 10 ){ #sanity check
$arg = _DecodeValue($arg);
## it is target:loginparams:uname:pw:timenow
$arg = "/cgi/users/home::::" if(!$arg);
my @list = split(/:/,$arg);
for my $i(0..4){
$list[$i]="" if(!$list[$i]);
$list[$i] =~ s/%c/:/g; $list[$i] =~ s/%a/%/g;
}
$OK=0 if( $list[4] !~ /^\d+$/ );
if($OK){
my $timediff = int(time/60) - $list[4];
#allow a 2 minute window
$OK=0 if( $timediff<-1 || $timediff > 2 );
}
$redirect_to = $list[0] if($list[0] =~ m#/# );
$loginparams = $list[1];
if($OK){
if( $session->valid_login($list[2],$list[3] ) ){
my $user = EPrints::DataObj::User::user_with_username(
$session,$list[2]);
$session->login($user);
$OK=2;
}
}
}
sleep 1 if( $OK != 2 ); # some problem, don't hurry
my $host = $session->{repository}->get_conf( "host" );
my $port = $session->{repository}->get_conf( "port" );
$redirect_to = "<nowiki>http://$host</nowiki>".($port!=80 :":$port":""). $redirect_to;
$redirect_to .= "?$loginparams" if($loginparams);
$session->redirect( $redirect_to );
$session->terminate;
exit 0;
<nowiki></nowiki>
While we made a lot of effort to protect the integrity and secrecy of the username and the data, nothing prevents a bad guy to submit bogus data to our secure script! Thus we relocate to the eprints repository addresses only, and accept the "relocate" argument only if it starts with a slash.

==Crypto routines==
These routines perform encryption and decryption. It is a lightweight version of more sophisticated ones, but (at least I hope) it is sufficient for this application. After the source there are some remarks for those interested.

<div style="padding:4px; background-color: #ffe0e0;border:1px solid #a06060;">'''Warning!''' The secret phrase in the second line should be changed to some secret value. And it should be the same in both copies.</div>
sub _secret {
"Whatever is your secret phrase, give anything here";
}
sub _intto64 { #a MIME64 type encoding
my $c=shift;
$c &=0x3F;
if($c<10){ return chr(48+$c); }
if($c<10+26){ return chr($c-10+65); }
if($c<10+26+26){ return chr($c-10-26+97); }
if($c==62){ return '_'; }
return '-';
}
sub _encode64 { #encoding three bytes to four chars
my($a,$b,$c)=@_;
$a &= 0xFF; $b &= 0xFF; $c &= 0xFF;
return _intto64($a>>2)._intto64(($a<<4)|($b>>4)).
_intto64(($b<<2)|($c>>6))._intto64($c);
}
sub _from64 { #decoding of the above
my $c=ord(shift||"0");
if($c==95){ return 62;}
if($c==45){ return 63;}
if($c<48+10){ return $c-48; }
if($c<65+26){ return $c-65+10; }
return $c-97+10+26;
}
sub _decode64 { # decoding four chars to three bytes
my($s)=shift;
my ($r1,$r2,$r3,$r4)=(
_from64($s),_from64(substr($s,1)),
_from64(substr($s,2)),_from64(substr($s,3)));
return ($r1<<18)|($r2<<12)|($r3<<6)|$r4;
}
sub _EncodeValue { ## encoded value should not end in a space
my($id) = @_;
use Digest::MD5;
my $salt=substr(Digest::MD5::md5_hex($id, _secret()),0,8);
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0; my $ssid="";
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed); my $idlen=length($id);
$id .= " "; # pad message by spaces
for(my $i=0;$i<$idlen;$i+=3){
#encode $id[0],$id[1],$id[2] as 4 chars
my $v=rand(0x1000000);
$ssid .= _encode64(ord(substr($id,$i))^($v>>16),
ord(substr($id,$i+1))^($v>>8),
ord(substr($id,$i+2))^$v);
}
return $salt.$ssid;
}
sub _DecodeValue {
my($s)=@_;
use Digest::MD5;
my($salt,$ssid)=(substr($s,0,8),substr($s,8));
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0;
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed);
my $id="";
for(my $i=0;$i<length($ssid)-3;$i+=4){
#decode next four chars
my $v=rand(0x1000000)^_decode64(substr($ssid,$i));
$id .= chr($v>>16) . chr(0xff&($v>>8)) . chr(0xff&$v);
}
$id =~ s/ +$//; ## strip spaces at the end
# $salt and $chksum should be equal
$id="" if ($salt ne substr(Digest::MD5::md5_hex($id, _secret()),0,8));
return $id;
}
'''Remarks:'''
*The MIME64-like encoding uses letters (both lower and upper case), digits and the characters - (minus) and _ (underscore). These are safe to use in an URL.
*Both encoding and decoding uses MD5 as the building block. The first eight characters of the ciphertext (encoded string) is used for two purposes. First, it acts as a salt, namely it is added to the secret phrase to derive the seed of the random number generator; second it is used to check message integrity, namely it should match the MD5 hash of the message ''and'' the secret phrase.
*Messages to be encrypted (plaintext) should not end by a space (spaces are used to pad the plaintext to have length divisible by three)
*The encryption is deterministic. Such a scheme is insecure in general. In our case, however, the plaintext contains a timestamp, thus - supposedly - the same message is never encrypted twice.
*Weak points of the scheme: only 32 bit MAC (and seed) value, and relying on perl's pseudorandom function.

==Patching Apache::Login==
We are making two changes to the ''perl_lib/EPrints/Apache/Login.pm'' module. First, always store the URI of the referring page in the hidden ''target'' variable. Second, set the address of the login page to the value of the configuration variable ''external_login_address'' whenever it is defined.

The instructions below are for Eprints version 3.1.3. Locate the line
my $form = $session->render_form( "POST" );
in the above module (it should be line 122). Replace it by the following:
##CSL Always use the "target" variable, and
## redirect to "external_login_address"
my $target = $session->param( "target" );
if(! defined($target) ){
$target = $session->get_uri;
}
my $form = $session->render_form(
"POST",
$session->get_repository->get_conf("external_login_address") );
If ''external_login_address'' is not defined, it has the same effect as the old code.
Roll down to line 142 and comment out this line (add # signs at the beginning):
## my $target = $session->param( "target" );
Finally save the file.

==Define "external_login_address"==
Add the definition of this variable to the file [[archives/ARCHIVEID/cfg/cfg.d/]][[user_login.pl]]:
$c->{external_login_address} = "<nowiki>https://secure.umb.edu/eprints/login</nowiki>";
In the same file you can define the sub ''check_user_password'' as explained in [[LDAP]] and [[LDAP user_login.pl]].

[[Category:Howto]]

Secure login

2009-08-01T22:28:55Z

Laci@degas.ceu.hu: /* Caveats */

When logging into eprints, both username and password travel openly. Usually it is not a problem as eprints has its own authenticating mechanism, and stealing an eprints password gives the intruder very limited power. However when using centralized authentication (e.g., by [[LDAP]]) then protecting the password is more important. To prevent sniffing, login pages usually use secure connection. Here we discuss an easy way to set up eprints to use encoded password traffic.

__TOC__

==The idea==

Change the destination of the eprints login page to a secure host. On the secure host a script receives the data: login name and password (and maybe others), encodes it, and forwards the request with the encrypted data as payload to an unencrypted eprints page. The eprints page decrypts the data and uses it for authentication.

===Requirements===
You need a ''secure http server'' on the same main domain as your eprints server. For example, if eprints can be reached on the web address ''<nowiki>http://eprints.umb.edu</nowiki>'', then the secure server must have domain name ending with ''umb.edu'', for example ''<nowiki>https://secure.umb.edu</nowiki>.

You should set up a cgi executable directory on the secure host. The apache config extract below does exactly this so that ''<nowiki>https://secure.umb.edu/eprints/whatever</nowiki>'' requests the script ''/opt/cgi-bin/eprints/whatever'' to be executed:
<VirtualHost *:443>
DocumentRoot "/opt/secure"
SSLEngine on
ScriptAlias /eprints/ /opt/cgi-bin/eprints/
<Directory "/opt/cgi-bin/eprints">
AllowOverride None
Options +ExecCGI -MultiView +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Copy the [[#Secure login script|Secure login script]] below into the ''/opt/cgi-bin/eprints/'' directory (or whatever directory you've set up above); copy the [[#Receive data script|receive data script]] into eprints' ''/cgi/'' directory.

Finally [[#Patching Apache::Login |patch the Apache::Login module]] of eprints so that everything works smoothly.

===Caveats===
The login process now works as follows.
# when a page requires authentication, it creates a "login page" with destination at the secure web site
# data entered to the "login page" is sent encrypted to the secure site
# the secure site encrypts the payload, and redirects the browser to the unencrypted eprints page ''receive_data''
# ''receive_data'' decrypts the payload, checks credentials, logs in the user if everything checks, and then redirects the browser to the originating page.

What is lost in this process of two redirects is the error message when authentication fails. ''Receive_data'' cannot display the error message as its URL should not be displayed on the user's screen. The final page - which is the original one as well - cannot distinguish between an unsuccessful login and a reload, thus cannot display the error message as well. ''C'est la vie''.

The encrypted data the ''receive_data'' page receives can be a replay of a sniffed older communication. Thus this data should contain a timestamp which should be checked to be recent. It also means that '''the secure and eprint servers must synchronize their clocks'''.

The secure site can also check the credentials, and relay the result only. Interestingly, the result should be sent encrypted, as otherwise the secure site could be used as an [http://en.wikipedia.org/wiki/Oracle oracle] to tell whether the password is correct or not (ideal utility for a [http://en.wikipedia.org/wiki/Dictionary_attack dictionary attack]).

==Secure login script==
This script receives the login page over a secure connection. It encrypts the username, password, and other arguments, and relocates the page to eprints' ''receive_data'' page.

Using the secure site configuration above, this script should be copied to ''/opt/cgi-bin/eprints/login'' after changing the address to your own eprint server. And, of course, the script must be executable by the apache process.

##!/usr/bin/perl -w
## secure login script for eprints
## encrypt and automatically forward to /eprints
## Author: Laszlo Csirmaz, 2009
## You are free to use this script
use strict;
sub _RelocateTo {
my $arg=shift;
## CHANGE THIS ADDRESS TO YOUR EPRINT SERRVER'S
"<nowiki>http://eprints.umb.edu/cgi/receive_data?Q=$arg</nowiki>";
}
<nowiki><-- COPY THE CRYPTO ROUTINES HERE --></nowiki>
sub _html2ascii {
my $v=shift;
$v="" if(! defined $v);
$v=~ tr/+/ /;
$v=~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
return $v;
}
my $P={};
my $ct=$ENV{'CONTENT_TYPE');
if($ct && $ct =~ /multipart/i ){
use CGI qw( :cgi :form );
my $req=new CGI; # read all data in
my @pm=$req->param;
foreach my $key (@pm) {
$P->{$key} = _html2ascii($req->param($ley));
}
} elsif ( $ENV{'REQUEST_METHOD'} !~ /^get/i ) {
my $pm=""; while(<>){ $pm .= $_; }
my @pms=split(/&/,$pm);
foreach my $elem(@pms) {
my($t,$v)=split(/=/,$elem);
next if(! defined($t) );
$P->{_html2ascii($t)} = _html2ascii($v);
}
}
## we return the following arguments:
## target, loginparams, username, pw, timestamp
my $arg="";
for my $item ($P->{target},$P->{loginparams},
$P->{login_username}, $P->{login_password} ){
$item="" if(! $item)[
# replace '%' by '%a' and replace ':' by '%c'
$item =~ s/%/%a/g; $item =~ s/:/%c/g;
$arg .= "$item:";
}
my $addr = _RelocateTo( _EncodeValue( $arg . int(time/60) ) );
print "Content-Type: text/html; charset=utf-8\n",
"Location: $addr\n",
"\n",
"<html><head><title>Redirected</title></head>\n",
"<body>\n",
"This page should automatically relocated. If not,\n",
"please <a href=\"$addr\">click here</a>.\n",
"</body>\n",
"</html>\n",
"\n";
exit 0;

==Receive data script==
This script receives the encrypted data from the secure server, decrypts it and logs in the user. A 1 second delay is inserted if there is a problem with the credentials.

This script should be copied to the ''eprints/cgi/receive_data''. It calls the ''check_user_password'' configuration procedure if it is defined.
######################################################
# receive_data
# Part of EPrints 3.1
# Author: Laszlo Csirmaz
# You are free to use/modify this script
######################################################
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );
my $redirect_to="/cgi/users/home";
my $loginparams="";
my $OK=1;
my $arg = $session->param('Q');
if( $arg && length($arg) > 10 ){ #sanity check
$arg = _DecodeValue($arg);
## it is target:loginparams:uname:pw:timenow
$arg = "/cgi/users/home::::" if(!$arg);
my @list = split(/:/,$arg);
for my $i(0..4){
$list[$i]="" if(!$list[$i]);
$list[$i] =~ s/%c/:/g; $list[$i] =~ s/%a/%/g;
}
$OK=0 if( $list[4] !~ /^\d+$/ );
if($OK){
my $timediff = int(time/60) - $list[4];
#allow a 2 minute window
$OK=0 if( $timediff<-1 || $timediff > 2 );
}
$redirect_to = $list[0] if($list[0] =~ m#/# );
$loginparams = $list[1];
if($OK){
if( $session->valid_login($list[2],$list[3] ) ){
my $user = EPrints::DataObj::User::user_with_username(
$session,$list[2]);
$session->login($user);
$OK=2;
}
}
}
sleep 1 if( $OK != 2 ); # some problem, don't hurry
my $host = $session->{repository}->get_conf( "host" );
my $port = $session->{repository}->get_conf( "port" );
$redirect_to = "<nowiki>http://$host</nowiki>".($port!=80 :":$port":""). $redirect_to;
$redirect_to .= "?$loginparams" if($loginparams);
$session->redirect( $redirect_to );
$session->terminate;
exit 0;
<nowiki></nowiki>
While we made a lot of effort to protect the integrity and secrecy of the username and the data, nothing prevents a bad guy to submit bogus data to our secure script! Thus we relocate to the eprints repository addresses only, and accept the "relocate" argument only if it starts with a slash.

==Crypto routines==
These routines perform encryption and decryption. It is a lightweight version of more sophisticated ones, but (at least I hope) it is sufficient for this application. After the source there are some remarks for those interested.

<div style="padding:4px; background-color: #ffe0e0;border:1px solid #a06060;">'''Warning!''' The secret phrase in the second line should be changed to some secret value. And it should be the same in both copies.</div>
sub _secret {
"Whatever is your secret phrase, give anything here";
}
sub _intto64 { #a MIME64 type encoding
my $c=shift;
$c &=0x3F;
if($c<10){ return chr(48+$c); }
if($c<10+26){ return chr($c-10+65); }
if($c<10+26+26){ return chr($c-10-26+97); }
if($c==62){ return '_'; }
return '-';
}
sub _encode64 { #encoding three bytes to four chars
my($a,$b,$c)=@_;
$a &= 0xFF; $b &= 0xFF; $c &= 0xFF;
return _intto64($a>>2)._intto64(($a<<4)|($b>>4)).
_intto64(($b<<2)|($c>>6))._intto64($c);
}
sub _from64 { #decoding of the above
my $c=ord(shift||"0");
if($c==95){ return 62;}
if($c==45){ return 63;}
if($c<48+10){ return $c-48; }
if($c<65+26){ return $c-65+10; }
return $c-97+10+26;
}
sub _decode64 { # decoding four chars to three bytes
my($s)=shift;
my ($r1,$r2,$r3,$r4)=(
_from64($s),_from64(substr($s,1)),
_from64(substr($s,2)),_from64(substr($s,3)));
return ($r1<<18)|($r2<<12)|($r3<<6)|$r4;
}
sub _EncodeValue { ## encoded value should not end in a space
my($id) = @_;
use Digest::MD5;
my $salt=substr(Digest::MD5::md5_hex($id, _secret()),0,8);
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0; my $ssid="";
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed); my $idlen=length($id);
$id .= " "; # pad message by spaces
for(my $i=0;$i<$idlen;$i+=3){
#encode $id[0],$id[1],$id[2] as 4 chars
my $v=rand(0x1000000);
$ssid .= _encode64(ord(substr($id,$i))^($v>>16),
ord(substr($id,$i+1))^($v>>8),
ord(substr($id,$i+2))^$v);
}
return $salt.$ssid;
}
sub _DecodeValue {
my($s)=@_;
use Digest::MD5;
my($salt,$ssid)=(substr($s,0,8),substr($s,8));
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0;
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed);
my $id="";
for(my $i=0;$i<length($ssid)-3;$i+=4){
#decode next four chars
my $v=rand(0x1000000)^_decode64(substr($ssid,$i));
$id .= chr($v>>16) . chr(0xff&($v>>8)) . chr(0xff&$v);
}
$id =~ s/ +$//; ## strip spaces at the end
# $salt and $chksum should be equal
$id="" if ($salt ne substr(Digest::MD5::md5_hex($id, _secret()),0,8));
return $id;
}
'''Remarks:'''
*The MIME64-like encoding uses letters (both lower and upper case), digits and the characters - (minus) and _ (underscore). These are safe to use in an URL.
*Both encoding and decoding uses MD5 as the building block. The first eight characters of the ciphertext (encoded string) is used for two purposes. First, it acts as a salt, namely it is added to the secret phrase to derive the seed of the random number generator; second it is used to check message integrity, namely it should match the MD5 hash of the message ''and'' the secret phrase.
*Messages to be encrypted (plaintext) should not end by a space (spaces are used to pad the plaintext to have length divisible by three)
*The encryption is deterministic. Such a scheme is insecure in general. In our case, however, the plaintext contains a timestamp, thus - supposedly - the same message is never encrypted twice.
*Weak points of the scheme: only 32 bit MAC (and seed) value, and relying on perl's pseudorandom function.

==Patching Apache::Login==
We are making two changes to the ''perl_lib/EPrints/Apache/Login.pm'' module. First, always store the URI of the referring page in the hidden ''target'' variable. Second, set the address of the login page to the value of the configuration variable ''external_login_address'' whenever it is defined.

The instructions below are for Eprints version 1.3.1. Locate the line
my $form = $session->render_form( "POST" );
in the above module (it should be line 122). Replace it by the following:
##CSL Always use the "target" variable, and
## redirect to "external_login_address"
my $target = $session->param( "target" );
if(! defined($target) ){
$target = $session->get_uri;
}
my $form = $session->render_form(
"POST",
$session->get_repository->get_conf("external_login_address") );
If ''external_login_address'' is not defined, it has the same effect as the old code.
Roll down to line 142 and comment out this line (add # signs at the beginning):
## my $target = $session->param( "target" );
Finally save the file.

==Define "external_login_address"==
Add the definition of this variable to the file [[archives/ARCHIVEID/cfg/cfg.d/]][[user_login.pl]]:
$c->{external_login_address} = "<nowiki>https://secure.umb.edu/eprints/login</nowiki>";
In the same file you can define the sub ''check_user_password'' as explained in [[LDAP]] and [[LDAP user_login.pl]].

[[Category:Howto]]

Secure login

2009-08-01T22:25:40Z

Laci@degas.ceu.hu: /* Caveats */

When logging into eprints, both username and password travel openly. Usually it is not a problem as eprints has its own authenticating mechanism, and stealing an eprints password gives the intruder very limited power. However when using centralized authentication (e.g., by [[LDAP]]) then protecting the password is more important. To prevent sniffing, login pages usually use secure connection. Here we discuss an easy way to set up eprints to use encoded password traffic.

__TOC__

==The idea==

Change the destination of the eprints login page to a secure host. On the secure host a script receives the data: login name and password (and maybe others), encodes it, and forwards the request with the encrypted data as payload to an unencrypted eprints page. The eprints page decrypts the data and uses it for authentication.

===Requirements===
You need a ''secure http server'' on the same main domain as your eprints server. For example, if eprints can be reached on the web address ''<nowiki>http://eprints.umb.edu</nowiki>'', then the secure server must have domain name ending with ''umb.edu'', for example ''<nowiki>https://secure.umb.edu</nowiki>.

You should set up a cgi executable directory on the secure host. The apache config extract below does exactly this so that ''<nowiki>https://secure.umb.edu/eprints/whatever</nowiki>'' requests the script ''/opt/cgi-bin/eprints/whatever'' to be executed:
<VirtualHost *:443>
DocumentRoot "/opt/secure"
SSLEngine on
ScriptAlias /eprints/ /opt/cgi-bin/eprints/
<Directory "/opt/cgi-bin/eprints">
AllowOverride None
Options +ExecCGI -MultiView +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Copy the [[#Secure login script|Secure login script]] below into the ''/opt/cgi-bin/eprints/'' directory (or whatever directory you've set up above); copy the [[#Receive data script|receive data script]] into eprints' ''/cgi/'' directory.

Finally [[#Patching Apache::Login |patch the Apache::Login module]] of eprints so that everything works smoothly.

===Caveats===
The login process now works as follows.
# when a page requires authentication, it creates a "login page" with destination at the secure web site
# data entered to the "login page" is sent encrypted to the secure site
# the secure site encrypts the payload, and redirects the browser to the unencrypted eprints page ''receive_data''
# ''receive_data'' decrypts the payload, checks credentials, logs in the user if everything checks, and then redirects the browser to the originating page.

What is lost in this process of two redirects is the error message when authentication fails. ''Receive_data'' cannot display the error message as its URL should not be displayed on the user's screen. The final page - which is the original one as well - cannot distinguish between an unsuccessful login and a reload, thus cannot display the error message as well. ''C'est la vie''.

The encrypted data the ''receive_data'' page receives can be a replay of a sniffed older communication. Thus this data should contain a timestamp which should be checked to be recent. It also means that '''the secure and eprint servers must synchronize their clocks'''.

The secure site can also check the credentials, and relay the result only. Interestingly, the result should be sent encrypted, as otherwise the secure site could be used as an oracle to tell whether the password is correct or not (ideal utility for a [http://en.wikipedia.org/wiki/Dictionary_attack dictionary attack]).

==Secure login script==
This script receives the login page over a secure connection. It encrypts the username, password, and other arguments, and relocates the page to eprints' ''receive_data'' page.

Using the secure site configuration above, this script should be copied to ''/opt/cgi-bin/eprints/login'' after changing the address to your own eprint server. And, of course, the script must be executable by the apache process.

##!/usr/bin/perl -w
## secure login script for eprints
## encrypt and automatically forward to /eprints
## Author: Laszlo Csirmaz, 2009
## You are free to use this script
use strict;
sub _RelocateTo {
my $arg=shift;
## CHANGE THIS ADDRESS TO YOUR EPRINT SERRVER'S
"<nowiki>http://eprints.umb.edu/cgi/receive_data?Q=$arg</nowiki>";
}
<nowiki><-- COPY THE CRYPTO ROUTINES HERE --></nowiki>
sub _html2ascii {
my $v=shift;
$v="" if(! defined $v);
$v=~ tr/+/ /;
$v=~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
return $v;
}
my $P={};
my $ct=$ENV{'CONTENT_TYPE');
if($ct && $ct =~ /multipart/i ){
use CGI qw( :cgi :form );
my $req=new CGI; # read all data in
my @pm=$req->param;
foreach my $key (@pm) {
$P->{$key} = _html2ascii($req->param($ley));
}
} elsif ( $ENV{'REQUEST_METHOD'} !~ /^get/i ) {
my $pm=""; while(<>){ $pm .= $_; }
my @pms=split(/&/,$pm);
foreach my $elem(@pms) {
my($t,$v)=split(/=/,$elem);
next if(! defined($t) );
$P->{_html2ascii($t)} = _html2ascii($v);
}
}
## we return the following arguments:
## target, loginparams, username, pw, timestamp
my $arg="";
for my $item ($P->{target},$P->{loginparams},
$P->{login_username}, $P->{login_password} ){
$item="" if(! $item)[
# replace '%' by '%a' and replace ':' by '%c'
$item =~ s/%/%a/g; $item =~ s/:/%c/g;
$arg .= "$item:";
}
my $addr = _RelocateTo( _EncodeValue( $arg . int(time/60) ) );
print "Content-Type: text/html; charset=utf-8\n",
"Location: $addr\n",
"\n",
"<html><head><title>Redirected</title></head>\n",
"<body>\n",
"This page should automatically relocated. If not,\n",
"please <a href=\"$addr\">click here</a>.\n",
"</body>\n",
"</html>\n",
"\n";
exit 0;

==Receive data script==
This script receives the encrypted data from the secure server, decrypts it and logs in the user. A 1 second delay is inserted if there is a problem with the credentials.

This script should be copied to the ''eprints/cgi/receive_data''. It calls the ''check_user_password'' configuration procedure if it is defined.
######################################################
# receive_data
# Part of EPrints 3.1
# Author: Laszlo Csirmaz
# You are free to use/modify this script
######################################################
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );
my $redirect_to="/cgi/users/home";
my $loginparams="";
my $OK=1;
my $arg = $session->param('Q');
if( $arg && length($arg) > 10 ){ #sanity check
$arg = _DecodeValue($arg);
## it is target:loginparams:uname:pw:timenow
$arg = "/cgi/users/home::::" if(!$arg);
my @list = split(/:/,$arg);
for my $i(0..4){
$list[$i]="" if(!$list[$i]);
$list[$i] =~ s/%c/:/g; $list[$i] =~ s/%a/%/g;
}
$OK=0 if( $list[4] !~ /^\d+$/ );
if($OK){
my $timediff = int(time/60) - $list[4];
#allow a 2 minute window
$OK=0 if( $timediff<-1 || $timediff > 2 );
}
$redirect_to = $list[0] if($list[0] =~ m#/# );
$loginparams = $list[1];
if($OK){
if( $session->valid_login($list[2],$list[3] ) ){
my $user = EPrints::DataObj::User::user_with_username(
$session,$list[2]);
$session->login($user);
$OK=2;
}
}
}
sleep 1 if( $OK != 2 ); # some problem, don't hurry
my $host = $session->{repository}->get_conf( "host" );
my $port = $session->{repository}->get_conf( "port" );
$redirect_to = "<nowiki>http://$host</nowiki>".($port!=80 :":$port":""). $redirect_to;
$redirect_to .= "?$loginparams" if($loginparams);
$session->redirect( $redirect_to );
$session->terminate;
exit 0;
<nowiki></nowiki>
While we made a lot of effort to protect the integrity and secrecy of the username and the data, nothing prevents a bad guy to submit bogus data to our secure script! Thus we relocate to the eprints repository addresses only, and accept the "relocate" argument only if it starts with a slash.

==Crypto routines==
These routines perform encryption and decryption. It is a lightweight version of more sophisticated ones, but (at least I hope) it is sufficient for this application. After the source there are some remarks for those interested.

<div style="padding:4px; background-color: #ffe0e0;border:1px solid #a06060;">'''Warning!''' The secret phrase in the second line should be changed to some secret value. And it should be the same in both copies.</div>
sub _secret {
"Whatever is your secret phrase, give anything here";
}
sub _intto64 { #a MIME64 type encoding
my $c=shift;
$c &=0x3F;
if($c<10){ return chr(48+$c); }
if($c<10+26){ return chr($c-10+65); }
if($c<10+26+26){ return chr($c-10-26+97); }
if($c==62){ return '_'; }
return '-';
}
sub _encode64 { #encoding three bytes to four chars
my($a,$b,$c)=@_;
$a &= 0xFF; $b &= 0xFF; $c &= 0xFF;
return _intto64($a>>2)._intto64(($a<<4)|($b>>4)).
_intto64(($b<<2)|($c>>6))._intto64($c);
}
sub _from64 { #decoding of the above
my $c=ord(shift||"0");
if($c==95){ return 62;}
if($c==45){ return 63;}
if($c<48+10){ return $c-48; }
if($c<65+26){ return $c-65+10; }
return $c-97+10+26;
}
sub _decode64 { # decoding four chars to three bytes
my($s)=shift;
my ($r1,$r2,$r3,$r4)=(
_from64($s),_from64(substr($s,1)),
_from64(substr($s,2)),_from64(substr($s,3)));
return ($r1<<18)|($r2<<12)|($r3<<6)|$r4;
}
sub _EncodeValue { ## encoded value should not end in a space
my($id) = @_;
use Digest::MD5;
my $salt=substr(Digest::MD5::md5_hex($id, _secret()),0,8);
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0; my $ssid="";
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed); my $idlen=length($id);
$id .= " "; # pad message by spaces
for(my $i=0;$i<$idlen;$i+=3){
#encode $id[0],$id[1],$id[2] as 4 chars
my $v=rand(0x1000000);
$ssid .= _encode64(ord(substr($id,$i))^($v>>16),
ord(substr($id,$i+1))^($v>>8),
ord(substr($id,$i+2))^$v);
}
return $salt.$ssid;
}
sub _DecodeValue {
my($s)=@_;
use Digest::MD5;
my($salt,$ssid)=(substr($s,0,8),substr($s,8));
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0;
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed);
my $id="";
for(my $i=0;$i<length($ssid)-3;$i+=4){
#decode next four chars
my $v=rand(0x1000000)^_decode64(substr($ssid,$i));
$id .= chr($v>>16) . chr(0xff&($v>>8)) . chr(0xff&$v);
}
$id =~ s/ +$//; ## strip spaces at the end
# $salt and $chksum should be equal
$id="" if ($salt ne substr(Digest::MD5::md5_hex($id, _secret()),0,8));
return $id;
}
'''Remarks:'''
*The MIME64-like encoding uses letters (both lower and upper case), digits and the characters - (minus) and _ (underscore). These are safe to use in an URL.
*Both encoding and decoding uses MD5 as the building block. The first eight characters of the ciphertext (encoded string) is used for two purposes. First, it acts as a salt, namely it is added to the secret phrase to derive the seed of the random number generator; second it is used to check message integrity, namely it should match the MD5 hash of the message ''and'' the secret phrase.
*Messages to be encrypted (plaintext) should not end by a space (spaces are used to pad the plaintext to have length divisible by three)
*The encryption is deterministic. Such a scheme is insecure in general. In our case, however, the plaintext contains a timestamp, thus - supposedly - the same message is never encrypted twice.
*Weak points of the scheme: only 32 bit MAC (and seed) value, and relying on perl's pseudorandom function.

==Patching Apache::Login==
We are making two changes to the ''perl_lib/EPrints/Apache/Login.pm'' module. First, always store the URI of the referring page in the hidden ''target'' variable. Second, set the address of the login page to the value of the configuration variable ''external_login_address'' whenever it is defined.

The instructions below are for Eprints version 1.3.1. Locate the line
my $form = $session->render_form( "POST" );
in the above module (it should be line 122). Replace it by the following:
##CSL Always use the "target" variable, and
## redirect to "external_login_address"
my $target = $session->param( "target" );
if(! defined($target) ){
$target = $session->get_uri;
}
my $form = $session->render_form(
"POST",
$session->get_repository->get_conf("external_login_address") );
If ''external_login_address'' is not defined, it has the same effect as the old code.
Roll down to line 142 and comment out this line (add # signs at the beginning):
## my $target = $session->param( "target" );
Finally save the file.

==Define "external_login_address"==
Add the definition of this variable to the file [[archives/ARCHIVEID/cfg/cfg.d/]][[user_login.pl]]:
$c->{external_login_address} = "<nowiki>https://secure.umb.edu/eprints/login</nowiki>";
In the same file you can define the sub ''check_user_password'' as explained in [[LDAP]] and [[LDAP user_login.pl]].

[[Category:Howto]]

Secure login

2009-08-01T22:23:18Z

Laci@degas.ceu.hu: /* Caveats */

When logging into eprints, both username and password travel openly. Usually it is not a problem as eprints has its own authenticating mechanism, and stealing an eprints password gives the intruder very limited power. However when using centralized authentication (e.g., by [[LDAP]]) then protecting the password is more important. To prevent sniffing, login pages usually use secure connection. Here we discuss an easy way to set up eprints to use encoded password traffic.

__TOC__

==The idea==

Change the destination of the eprints login page to a secure host. On the secure host a script receives the data: login name and password (and maybe others), encodes it, and forwards the request with the encrypted data as payload to an unencrypted eprints page. The eprints page decrypts the data and uses it for authentication.

===Requirements===
You need a ''secure http server'' on the same main domain as your eprints server. For example, if eprints can be reached on the web address ''<nowiki>http://eprints.umb.edu</nowiki>'', then the secure server must have domain name ending with ''umb.edu'', for example ''<nowiki>https://secure.umb.edu</nowiki>.

You should set up a cgi executable directory on the secure host. The apache config extract below does exactly this so that ''<nowiki>https://secure.umb.edu/eprints/whatever</nowiki>'' requests the script ''/opt/cgi-bin/eprints/whatever'' to be executed:
<VirtualHost *:443>
DocumentRoot "/opt/secure"
SSLEngine on
ScriptAlias /eprints/ /opt/cgi-bin/eprints/
<Directory "/opt/cgi-bin/eprints">
AllowOverride None
Options +ExecCGI -MultiView +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Copy the [[#Secure login script|Secure login script]] below into the ''/opt/cgi-bin/eprints/'' directory (or whatever directory you've set up above); copy the [[#Receive data script|receive data script]] into eprints' ''/cgi/'' directory.

Finally [[#Patching Apache::Login |patch the Apache::Login module]] of eprints so that everything works smoothly.

===Caveats===
The login process now works as follows.
# when a page requires authentication, it creates a "login page" with destination at the secure web site
# data entered to the "login page" is sent encrypted to the secure site
# the secure site encrypts the payload, and redirects the browser to the unencrypted eprints page ''receive_data''
# ''receive_data'' decrypts the payload, checks credentials, logs in the user if everything checks, and then redirects the browser to the originating page.

What is lost in this process of two redirects is the error message when authentication fails. ''Receive_data'' cannot display the error message as its URL should not be displayed on the user's screen. The final page - which is the original one as well - cannot distinguish between an unsuccessful login and a reload, thus cannot display the error message as well. ''C'est la vie''.

The encrypted data the ''receive_data'' page receives can be a replay of a sniffed older communication. Thus this data should contain a timestamp which should be checked to be recent.

The secure site can also check the credentials, and relay the result only. Interestingly, the result should be sent encrypted, as otherwise the secure site could be used as an oracle to tell whether the password is correct or not (ideal utility for a [http://en.wikipedia.org/wiki/Dictionary_attack dictionary attack]).

==Secure login script==
This script receives the login page over a secure connection. It encrypts the username, password, and other arguments, and relocates the page to eprints' ''receive_data'' page.

Using the secure site configuration above, this script should be copied to ''/opt/cgi-bin/eprints/login'' after changing the address to your own eprint server. And, of course, the script must be executable by the apache process.

##!/usr/bin/perl -w
## secure login script for eprints
## encrypt and automatically forward to /eprints
## Author: Laszlo Csirmaz, 2009
## You are free to use this script
use strict;
sub _RelocateTo {
my $arg=shift;
## CHANGE THIS ADDRESS TO YOUR EPRINT SERRVER'S
"<nowiki>http://eprints.umb.edu/cgi/receive_data?Q=$arg</nowiki>";
}
<nowiki><-- COPY THE CRYPTO ROUTINES HERE --></nowiki>
sub _html2ascii {
my $v=shift;
$v="" if(! defined $v);
$v=~ tr/+/ /;
$v=~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
return $v;
}
my $P={};
my $ct=$ENV{'CONTENT_TYPE');
if($ct && $ct =~ /multipart/i ){
use CGI qw( :cgi :form );
my $req=new CGI; # read all data in
my @pm=$req->param;
foreach my $key (@pm) {
$P->{$key} = _html2ascii($req->param($ley));
}
} elsif ( $ENV{'REQUEST_METHOD'} !~ /^get/i ) {
my $pm=""; while(<>){ $pm .= $_; }
my @pms=split(/&/,$pm);
foreach my $elem(@pms) {
my($t,$v)=split(/=/,$elem);
next if(! defined($t) );
$P->{_html2ascii($t)} = _html2ascii($v);
}
}
## we return the following arguments:
## target, loginparams, username, pw, timestamp
my $arg="";
for my $item ($P->{target},$P->{loginparams},
$P->{login_username}, $P->{login_password} ){
$item="" if(! $item)[
# replace '%' by '%a' and replace ':' by '%c'
$item =~ s/%/%a/g; $item =~ s/:/%c/g;
$arg .= "$item:";
}
my $addr = _RelocateTo( _EncodeValue( $arg . int(time/60) ) );
print "Content-Type: text/html; charset=utf-8\n",
"Location: $addr\n",
"\n",
"<html><head><title>Redirected</title></head>\n",
"<body>\n",
"This page should automatically relocated. If not,\n",
"please <a href=\"$addr\">click here</a>.\n",
"</body>\n",
"</html>\n",
"\n";
exit 0;

==Receive data script==
This script receives the encrypted data from the secure server, decrypts it and logs in the user. A 1 second delay is inserted if there is a problem with the credentials.

This script should be copied to the ''eprints/cgi/receive_data''. It calls the ''check_user_password'' configuration procedure if it is defined.
######################################################
# receive_data
# Part of EPrints 3.1
# Author: Laszlo Csirmaz
# You are free to use/modify this script
######################################################
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );
my $redirect_to="/cgi/users/home";
my $loginparams="";
my $OK=1;
my $arg = $session->param('Q');
if( $arg && length($arg) > 10 ){ #sanity check
$arg = _DecodeValue($arg);
## it is target:loginparams:uname:pw:timenow
$arg = "/cgi/users/home::::" if(!$arg);
my @list = split(/:/,$arg);
for my $i(0..4){
$list[$i]="" if(!$list[$i]);
$list[$i] =~ s/%c/:/g; $list[$i] =~ s/%a/%/g;
}
$OK=0 if( $list[4] !~ /^\d+$/ );
if($OK){
my $timediff = int(time/60) - $list[4];
#allow a 2 minute window
$OK=0 if( $timediff<-1 || $timediff > 2 );
}
$redirect_to = $list[0] if($list[0] =~ m#/# );
$loginparams = $list[1];
if($OK){
if( $session->valid_login($list[2],$list[3] ) ){
my $user = EPrints::DataObj::User::user_with_username(
$session,$list[2]);
$session->login($user);
$OK=2;
}
}
}
sleep 1 if( $OK != 2 ); # some problem, don't hurry
my $host = $session->{repository}->get_conf( "host" );
my $port = $session->{repository}->get_conf( "port" );
$redirect_to = "<nowiki>http://$host</nowiki>".($port!=80 :":$port":""). $redirect_to;
$redirect_to .= "?$loginparams" if($loginparams);
$session->redirect( $redirect_to );
$session->terminate;
exit 0;
<nowiki></nowiki>
While we made a lot of effort to protect the integrity and secrecy of the username and the data, nothing prevents a bad guy to submit bogus data to our secure script! Thus we relocate to the eprints repository addresses only, and accept the "relocate" argument only if it starts with a slash.

==Crypto routines==
These routines perform encryption and decryption. It is a lightweight version of more sophisticated ones, but (at least I hope) it is sufficient for this application. After the source there are some remarks for those interested.

<div style="padding:4px; background-color: #ffe0e0;border:1px solid #a06060;">'''Warning!''' The secret phrase in the second line should be changed to some secret value. And it should be the same in both copies.</div>
sub _secret {
"Whatever is your secret phrase, give anything here";
}
sub _intto64 { #a MIME64 type encoding
my $c=shift;
$c &=0x3F;
if($c<10){ return chr(48+$c); }
if($c<10+26){ return chr($c-10+65); }
if($c<10+26+26){ return chr($c-10-26+97); }
if($c==62){ return '_'; }
return '-';
}
sub _encode64 { #encoding three bytes to four chars
my($a,$b,$c)=@_;
$a &= 0xFF; $b &= 0xFF; $c &= 0xFF;
return _intto64($a>>2)._intto64(($a<<4)|($b>>4)).
_intto64(($b<<2)|($c>>6))._intto64($c);
}
sub _from64 { #decoding of the above
my $c=ord(shift||"0");
if($c==95){ return 62;}
if($c==45){ return 63;}
if($c<48+10){ return $c-48; }
if($c<65+26){ return $c-65+10; }
return $c-97+10+26;
}
sub _decode64 { # decoding four chars to three bytes
my($s)=shift;
my ($r1,$r2,$r3,$r4)=(
_from64($s),_from64(substr($s,1)),
_from64(substr($s,2)),_from64(substr($s,3)));
return ($r1<<18)|($r2<<12)|($r3<<6)|$r4;
}
sub _EncodeValue { ## encoded value should not end in a space
my($id) = @_;
use Digest::MD5;
my $salt=substr(Digest::MD5::md5_hex($id, _secret()),0,8);
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0; my $ssid="";
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed); my $idlen=length($id);
$id .= " "; # pad message by spaces
for(my $i=0;$i<$idlen;$i+=3){
#encode $id[0],$id[1],$id[2] as 4 chars
my $v=rand(0x1000000);
$ssid .= _encode64(ord(substr($id,$i))^($v>>16),
ord(substr($id,$i+1))^($v>>8),
ord(substr($id,$i+2))^$v);
}
return $salt.$ssid;
}
sub _DecodeValue {
my($s)=@_;
use Digest::MD5;
my($salt,$ssid)=(substr($s,0,8),substr($s,8));
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0;
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed);
my $id="";
for(my $i=0;$i<length($ssid)-3;$i+=4){
#decode next four chars
my $v=rand(0x1000000)^_decode64(substr($ssid,$i));
$id .= chr($v>>16) . chr(0xff&($v>>8)) . chr(0xff&$v);
}
$id =~ s/ +$//; ## strip spaces at the end
# $salt and $chksum should be equal
$id="" if ($salt ne substr(Digest::MD5::md5_hex($id, _secret()),0,8));
return $id;
}
'''Remarks:'''
*The MIME64-like encoding uses letters (both lower and upper case), digits and the characters - (minus) and _ (underscore). These are safe to use in an URL.
*Both encoding and decoding uses MD5 as the building block. The first eight characters of the ciphertext (encoded string) is used for two purposes. First, it acts as a salt, namely it is added to the secret phrase to derive the seed of the random number generator; second it is used to check message integrity, namely it should match the MD5 hash of the message ''and'' the secret phrase.
*Messages to be encrypted (plaintext) should not end by a space (spaces are used to pad the plaintext to have length divisible by three)
*The encryption is deterministic. Such a scheme is insecure in general. In our case, however, the plaintext contains a timestamp, thus - supposedly - the same message is never encrypted twice.
*Weak points of the scheme: only 32 bit MAC (and seed) value, and relying on perl's pseudorandom function.

==Patching Apache::Login==
We are making two changes to the ''perl_lib/EPrints/Apache/Login.pm'' module. First, always store the URI of the referring page in the hidden ''target'' variable. Second, set the address of the login page to the value of the configuration variable ''external_login_address'' whenever it is defined.

The instructions below are for Eprints version 1.3.1. Locate the line
my $form = $session->render_form( "POST" );
in the above module (it should be line 122). Replace it by the following:
##CSL Always use the "target" variable, and
## redirect to "external_login_address"
my $target = $session->param( "target" );
if(! defined($target) ){
$target = $session->get_uri;
}
my $form = $session->render_form(
"POST",
$session->get_repository->get_conf("external_login_address") );
If ''external_login_address'' is not defined, it has the same effect as the old code.
Roll down to line 142 and comment out this line (add # signs at the beginning):
## my $target = $session->param( "target" );
Finally save the file.

==Define "external_login_address"==
Add the definition of this variable to the file [[archives/ARCHIVEID/cfg/cfg.d/]][[user_login.pl]]:
$c->{external_login_address} = "<nowiki>https://secure.umb.edu/eprints/login</nowiki>";
In the same file you can define the sub ''check_user_password'' as explained in [[LDAP]] and [[LDAP user_login.pl]].

[[Category:Howto]]

Secure login

2009-08-01T22:21:40Z

Laci@degas.ceu.hu: /* Requirements */

When logging into eprints, both username and password travel openly. Usually it is not a problem as eprints has its own authenticating mechanism, and stealing an eprints password gives the intruder very limited power. However when using centralized authentication (e.g., by [[LDAP]]) then protecting the password is more important. To prevent sniffing, login pages usually use secure connection. Here we discuss an easy way to set up eprints to use encoded password traffic.

__TOC__

==The idea==

Change the destination of the eprints login page to a secure host. On the secure host a script receives the data: login name and password (and maybe others), encodes it, and forwards the request with the encrypted data as payload to an unencrypted eprints page. The eprints page decrypts the data and uses it for authentication.

===Requirements===
You need a ''secure http server'' on the same main domain as your eprints server. For example, if eprints can be reached on the web address ''<nowiki>http://eprints.umb.edu</nowiki>'', then the secure server must have domain name ending with ''umb.edu'', for example ''<nowiki>https://secure.umb.edu</nowiki>.

You should set up a cgi executable directory on the secure host. The apache config extract below does exactly this so that ''<nowiki>https://secure.umb.edu/eprints/whatever</nowiki>'' requests the script ''/opt/cgi-bin/eprints/whatever'' to be executed:
<VirtualHost *:443>
DocumentRoot "/opt/secure"
SSLEngine on
ScriptAlias /eprints/ /opt/cgi-bin/eprints/
<Directory "/opt/cgi-bin/eprints">
AllowOverride None
Options +ExecCGI -MultiView +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Copy the [[#Secure login script|Secure login script]] below into the ''/opt/cgi-bin/eprints/'' directory (or whatever directory you've set up above); copy the [[#Receive data script|receive data script]] into eprints' ''/cgi/'' directory.

Finally [[#Patching Apache::Login |patch the Apache::Login module]] of eprints so that everything works smoothly.

===Caveats===
The login process now works as follows.
# when a page requires authentication, it creates a "login page" with destination at the secure web site
# the "login page" is sent encrypted to the secure site
# the secure site encrypts the payload, and redirects the browser to an unencrypted eprints page ''receive_data''
# ''receive_data'' decrypts the payload, checks credentials, logs in the user if everything checks, and then redirects the browser to the originating page.

What is lost in this process of two redirects is the error message when authentication fails. ''Receive_data'' cannot display the error message as its URL should not be displayed on the user's screen. The final page - which is the original one as well - cannot distinguish between an unsuccessful login and a reload, thus cannot display the error message as well. ''C'est la vie''.

The encrypted data the ''receive_data'' page receives can be a replay of a sniffed older communication. Thus this data should contain a timestamp which should be checked to be recent.

The secure site can also check the credentials, and relay the result only. Interestingly, the result should be sent encrypted, as otherwise the secure site could be used as an oracle to tell whether the password is correct or not (ideal utility for a [http://en.wikipedia.org/wiki/Dictionary_attack dictionary attack]).

==Secure login script==
This script receives the login page over a secure connection. It encrypts the username, password, and other arguments, and relocates the page to eprints' ''receive_data'' page.

Using the secure site configuration above, this script should be copied to ''/opt/cgi-bin/eprints/login'' after changing the address to your own eprint server. And, of course, the script must be executable by the apache process.

##!/usr/bin/perl -w
## secure login script for eprints
## encrypt and automatically forward to /eprints
## Author: Laszlo Csirmaz, 2009
## You are free to use this script
use strict;
sub _RelocateTo {
my $arg=shift;
## CHANGE THIS ADDRESS TO YOUR EPRINT SERRVER'S
"<nowiki>http://eprints.umb.edu/cgi/receive_data?Q=$arg</nowiki>";
}
<nowiki><-- COPY THE CRYPTO ROUTINES HERE --></nowiki>
sub _html2ascii {
my $v=shift;
$v="" if(! defined $v);
$v=~ tr/+/ /;
$v=~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
return $v;
}
my $P={};
my $ct=$ENV{'CONTENT_TYPE');
if($ct && $ct =~ /multipart/i ){
use CGI qw( :cgi :form );
my $req=new CGI; # read all data in
my @pm=$req->param;
foreach my $key (@pm) {
$P->{$key} = _html2ascii($req->param($ley));
}
} elsif ( $ENV{'REQUEST_METHOD'} !~ /^get/i ) {
my $pm=""; while(<>){ $pm .= $_; }
my @pms=split(/&/,$pm);
foreach my $elem(@pms) {
my($t,$v)=split(/=/,$elem);
next if(! defined($t) );
$P->{_html2ascii($t)} = _html2ascii($v);
}
}
## we return the following arguments:
## target, loginparams, username, pw, timestamp
my $arg="";
for my $item ($P->{target},$P->{loginparams},
$P->{login_username}, $P->{login_password} ){
$item="" if(! $item)[
# replace '%' by '%a' and replace ':' by '%c'
$item =~ s/%/%a/g; $item =~ s/:/%c/g;
$arg .= "$item:";
}
my $addr = _RelocateTo( _EncodeValue( $arg . int(time/60) ) );
print "Content-Type: text/html; charset=utf-8\n",
"Location: $addr\n",
"\n",
"<html><head><title>Redirected</title></head>\n",
"<body>\n",
"This page should automatically relocated. If not,\n",
"please <a href=\"$addr\">click here</a>.\n",
"</body>\n",
"</html>\n",
"\n";
exit 0;

==Receive data script==
This script receives the encrypted data from the secure server, decrypts it and logs in the user. A 1 second delay is inserted if there is a problem with the credentials.

This script should be copied to the ''eprints/cgi/receive_data''. It calls the ''check_user_password'' configuration procedure if it is defined.
######################################################
# receive_data
# Part of EPrints 3.1
# Author: Laszlo Csirmaz
# You are free to use/modify this script
######################################################
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );
my $redirect_to="/cgi/users/home";
my $loginparams="";
my $OK=1;
my $arg = $session->param('Q');
if( $arg && length($arg) > 10 ){ #sanity check
$arg = _DecodeValue($arg);
## it is target:loginparams:uname:pw:timenow
$arg = "/cgi/users/home::::" if(!$arg);
my @list = split(/:/,$arg);
for my $i(0..4){
$list[$i]="" if(!$list[$i]);
$list[$i] =~ s/%c/:/g; $list[$i] =~ s/%a/%/g;
}
$OK=0 if( $list[4] !~ /^\d+$/ );
if($OK){
my $timediff = int(time/60) - $list[4];
#allow a 2 minute window
$OK=0 if( $timediff<-1 || $timediff > 2 );
}
$redirect_to = $list[0] if($list[0] =~ m#/# );
$loginparams = $list[1];
if($OK){
if( $session->valid_login($list[2],$list[3] ) ){
my $user = EPrints::DataObj::User::user_with_username(
$session,$list[2]);
$session->login($user);
$OK=2;
}
}
}
sleep 1 if( $OK != 2 ); # some problem, don't hurry
my $host = $session->{repository}->get_conf( "host" );
my $port = $session->{repository}->get_conf( "port" );
$redirect_to = "<nowiki>http://$host</nowiki>".($port!=80 :":$port":""). $redirect_to;
$redirect_to .= "?$loginparams" if($loginparams);
$session->redirect( $redirect_to );
$session->terminate;
exit 0;
<nowiki></nowiki>
While we made a lot of effort to protect the integrity and secrecy of the username and the data, nothing prevents a bad guy to submit bogus data to our secure script! Thus we relocate to the eprints repository addresses only, and accept the "relocate" argument only if it starts with a slash.

==Crypto routines==
These routines perform encryption and decryption. It is a lightweight version of more sophisticated ones, but (at least I hope) it is sufficient for this application. After the source there are some remarks for those interested.

<div style="padding:4px; background-color: #ffe0e0;border:1px solid #a06060;">'''Warning!''' The secret phrase in the second line should be changed to some secret value. And it should be the same in both copies.</div>
sub _secret {
"Whatever is your secret phrase, give anything here";
}
sub _intto64 { #a MIME64 type encoding
my $c=shift;
$c &=0x3F;
if($c<10){ return chr(48+$c); }
if($c<10+26){ return chr($c-10+65); }
if($c<10+26+26){ return chr($c-10-26+97); }
if($c==62){ return '_'; }
return '-';
}
sub _encode64 { #encoding three bytes to four chars
my($a,$b,$c)=@_;
$a &= 0xFF; $b &= 0xFF; $c &= 0xFF;
return _intto64($a>>2)._intto64(($a<<4)|($b>>4)).
_intto64(($b<<2)|($c>>6))._intto64($c);
}
sub _from64 { #decoding of the above
my $c=ord(shift||"0");
if($c==95){ return 62;}
if($c==45){ return 63;}
if($c<48+10){ return $c-48; }
if($c<65+26){ return $c-65+10; }
return $c-97+10+26;
}
sub _decode64 { # decoding four chars to three bytes
my($s)=shift;
my ($r1,$r2,$r3,$r4)=(
_from64($s),_from64(substr($s,1)),
_from64(substr($s,2)),_from64(substr($s,3)));
return ($r1<<18)|($r2<<12)|($r3<<6)|$r4;
}
sub _EncodeValue { ## encoded value should not end in a space
my($id) = @_;
use Digest::MD5;
my $salt=substr(Digest::MD5::md5_hex($id, _secret()),0,8);
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0; my $ssid="";
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed); my $idlen=length($id);
$id .= " "; # pad message by spaces
for(my $i=0;$i<$idlen;$i+=3){
#encode $id[0],$id[1],$id[2] as 4 chars
my $v=rand(0x1000000);
$ssid .= _encode64(ord(substr($id,$i))^($v>>16),
ord(substr($id,$i+1))^($v>>8),
ord(substr($id,$i+2))^$v);
}
return $salt.$ssid;
}
sub _DecodeValue {
my($s)=@_;
use Digest::MD5;
my($salt,$ssid)=(substr($s,0,8),substr($s,8));
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0;
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed);
my $id="";
for(my $i=0;$i<length($ssid)-3;$i+=4){
#decode next four chars
my $v=rand(0x1000000)^_decode64(substr($ssid,$i));
$id .= chr($v>>16) . chr(0xff&($v>>8)) . chr(0xff&$v);
}
$id =~ s/ +$//; ## strip spaces at the end
# $salt and $chksum should be equal
$id="" if ($salt ne substr(Digest::MD5::md5_hex($id, _secret()),0,8));
return $id;
}
'''Remarks:'''
*The MIME64-like encoding uses letters (both lower and upper case), digits and the characters - (minus) and _ (underscore). These are safe to use in an URL.
*Both encoding and decoding uses MD5 as the building block. The first eight characters of the ciphertext (encoded string) is used for two purposes. First, it acts as a salt, namely it is added to the secret phrase to derive the seed of the random number generator; second it is used to check message integrity, namely it should match the MD5 hash of the message ''and'' the secret phrase.
*Messages to be encrypted (plaintext) should not end by a space (spaces are used to pad the plaintext to have length divisible by three)
*The encryption is deterministic. Such a scheme is insecure in general. In our case, however, the plaintext contains a timestamp, thus - supposedly - the same message is never encrypted twice.
*Weak points of the scheme: only 32 bit MAC (and seed) value, and relying on perl's pseudorandom function.

==Patching Apache::Login==
We are making two changes to the ''perl_lib/EPrints/Apache/Login.pm'' module. First, always store the URI of the referring page in the hidden ''target'' variable. Second, set the address of the login page to the value of the configuration variable ''external_login_address'' whenever it is defined.

The instructions below are for Eprints version 1.3.1. Locate the line
my $form = $session->render_form( "POST" );
in the above module (it should be line 122). Replace it by the following:
##CSL Always use the "target" variable, and
## redirect to "external_login_address"
my $target = $session->param( "target" );
if(! defined($target) ){
$target = $session->get_uri;
}
my $form = $session->render_form(
"POST",
$session->get_repository->get_conf("external_login_address") );
If ''external_login_address'' is not defined, it has the same effect as the old code.
Roll down to line 142 and comment out this line (add # signs at the beginning):
## my $target = $session->param( "target" );
Finally save the file.

==Define "external_login_address"==
Add the definition of this variable to the file [[archives/ARCHIVEID/cfg/cfg.d/]][[user_login.pl]]:
$c->{external_login_address} = "<nowiki>https://secure.umb.edu/eprints/login</nowiki>";
In the same file you can define the sub ''check_user_password'' as explained in [[LDAP]] and [[LDAP user_login.pl]].

[[Category:Howto]]

Secure login

2009-07-27T20:08:44Z

Laci@degas.ceu.hu: /* Receive data script */

When logging into eprints, both username and password travel openly. Usually it is not a problem as eprints has its own authenticating mechanism, and stealing an eprints password gives the intruder very limited power. However when using centralized authentication (e.g., by [[LDAP]]) then protecting the password is more important. To prevent sniffing, login pages usually use secure connection. Here we discuss an easy way to set up eprints to use encoded password traffic.

__TOC__

==The idea==

Change the destination of the eprints login page to a secure host. On the secure host a script receives the data: login name and password (and maybe others), encodes it, and forwards the request with the encrypted data as payload to an unencrypted eprints page. The eprints page decrypts the data and uses it for authentication.

===Requirements===
You need a ''secure http server'' on the same main domain as your your eprints server. For example, if eprints can be reached on the web address ''<nowiki>http://eprints.umb.edu</nowiki>'', then the secure server must have domain name ending with ''umb.edu'', for example ''<nowiki>https://secure.umb.edu</nowiki>.

You should set up a cgi executable directory on the secure host. The apache config extract below does exactly this so that ''<nowiki>https://secure.umb.edu/eprints/whatever</nowiki>'' requests the script ''/opt/cgi-bin/eprints/whatever'' to be executed:
<VirtualHost *:443>
DocumentRoot "/opt/secure"
SSLEngine on
ScriptAlias /eprints/ /opt/cgi-bin/eprints/
<Directory "/opt/cgi-bin/eprints">
AllowOverride None
Options +ExecCGI -MultiView +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Copy the [[#Secure login script|Secure login script]] below into the ''/opt/cgi-bin/eprints/'' directory (or whatever directory you've set up above); copy the [[#Receive data script|receive data script]] into eprints' ''/cgi/'' directory.

Finally [[#Patching Apache::Login |patch the Apache::Login module]] of eprints so that everything works smoothly.

===Caveats===
The login process now works as follows.
# when a page requires authentication, it creates a "login page" with destination at the secure web site
# the "login page" is sent encrypted to the secure site
# the secure site encrypts the payload, and redirects the browser to an unencrypted eprints page ''receive_data''
# ''receive_data'' decrypts the payload, checks credentials, logs in the user if everything checks, and then redirects the browser to the originating page.

What is lost in this process of two redirects is the error message when authentication fails. ''Receive_data'' cannot display the error message as its URL should not be displayed on the user's screen. The final page - which is the original one as well - cannot distinguish between an unsuccessful login and a reload, thus cannot display the error message as well. ''C'est la vie''.

The encrypted data the ''receive_data'' page receives can be a replay of a sniffed older communication. Thus this data should contain a timestamp which should be checked to be recent.

The secure site can also check the credentials, and relay the result only. Interestingly, the result should be sent encrypted, as otherwise the secure site could be used as an oracle to tell whether the password is correct or not (ideal utility for a [http://en.wikipedia.org/wiki/Dictionary_attack dictionary attack]).

==Secure login script==
This script receives the login page over a secure connection. It encrypts the username, password, and other arguments, and relocates the page to eprints' ''receive_data'' page.

Using the secure site configuration above, this script should be copied to ''/opt/cgi-bin/eprints/login'' after changing the address to your own eprint server. And, of course, the script must be executable by the apache process.

##!/usr/bin/perl -w
## secure login script for eprints
## encrypt and automatically forward to /eprints
## Author: Laszlo Csirmaz, 2009
## You are free to use this script
use strict;
sub _RelocateTo {
my $arg=shift;
## CHANGE THIS ADDRESS TO YOUR EPRINT SERRVER'S
"<nowiki>http://eprints.umb.edu/cgi/receive_data?Q=$arg</nowiki>";
}
<nowiki><-- COPY THE CRYPTO ROUTINES HERE --></nowiki>
sub _html2ascii {
my $v=shift;
$v="" if(! defined $v);
$v=~ tr/+/ /;
$v=~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
return $v;
}
my $P={};
my $ct=$ENV{'CONTENT_TYPE');
if($ct && $ct =~ /multipart/i ){
use CGI qw( :cgi :form );
my $req=new CGI; # read all data in
my @pm=$req->param;
foreach my $key (@pm) {
$P->{$key} = _html2ascii($req->param($ley));
}
} elsif ( $ENV{'REQUEST_METHOD'} !~ /^get/i ) {
my $pm=""; while(<>){ $pm .= $_; }
my @pms=split(/&/,$pm);
foreach my $elem(@pms) {
my($t,$v)=split(/=/,$elem);
next if(! defined($t) );
$P->{_html2ascii($t)} = _html2ascii($v);
}
}
## we return the following arguments:
## target, loginparams, username, pw, timestamp
my $arg="";
for my $item ($P->{target},$P->{loginparams},
$P->{login_username}, $P->{login_password} ){
$item="" if(! $item)[
# replace '%' by '%a' and replace ':' by '%c'
$item =~ s/%/%a/g; $item =~ s/:/%c/g;
$arg .= "$item:";
}
my $addr = _RelocateTo( _EncodeValue( $arg . int(time/60) ) );
print "Content-Type: text/html; charset=utf-8\n",
"Location: $addr\n",
"\n",
"<html><head><title>Redirected</title></head>\n",
"<body>\n",
"This page should automatically relocated. If not,\n",
"please <a href=\"$addr\">click here</a>.\n",
"</body>\n",
"</html>\n",
"\n";
exit 0;

==Receive data script==
This script receives the encrypted data from the secure server, decrypts it and logs in the user. A 1 second delay is inserted if there is a problem with the credentials.

This script should be copied to the ''eprints/cgi/receive_data''. It calls the ''check_user_password'' configuration procedure if it is defined.
######################################################
# receive_data
# Part of EPrints 3.1
# Author: Laszlo Csirmaz
# You are free to use/modify this script
######################################################
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );
my $redirect_to="/cgi/users/home";
my $loginparams="";
my $OK=1;
my $arg = $session->param('Q');
if( $arg && length($arg) > 10 ){ #sanity check
$arg = _DecodeValue($arg);
## it is target:loginparams:uname:pw:timenow
$arg = "/cgi/users/home::::" if(!$arg);
my @list = split(/:/,$arg);
for my $i(0..4){
$list[$i]="" if(!$list[$i]);
$list[$i] =~ s/%c/:/g; $list[$i] =~ s/%a/%/g;
}
$OK=0 if( $list[4] !~ /^\d+$/ );
if($OK){
my $timediff = int(time/60) - $list[4];
#allow a 2 minute window
$OK=0 if( $timediff<-1 || $timediff > 2 );
}
$redirect_to = $list[0] if($list[0] =~ m#/# );
$loginparams = $list[1];
if($OK){
if( $session->valid_login($list[2],$list[3] ) ){
my $user = EPrints::DataObj::User::user_with_username(
$session,$list[2]);
$session->login($user);
$OK=2;
}
}
}
sleep 1 if( $OK != 2 ); # some problem, don't hurry
my $host = $session->{repository}->get_conf( "host" );
my $port = $session->{repository}->get_conf( "port" );
$redirect_to = "<nowiki>http://$host</nowiki>".($port!=80 :":$port":""). $redirect_to;
$redirect_to .= "?$loginparams" if($loginparams);
$session->redirect( $redirect_to );
$session->terminate;
exit 0;
<nowiki></nowiki>
While we made a lot of effort to protect the integrity and secrecy of the username and the data, nothing prevents a bad guy to submit bogus data to our secure script! Thus we relocate to the eprints repository addresses only, and accept the "relocate" argument only if it starts with a slash.

==Crypto routines==
These routines perform encryption and decryption. It is a lightweight version of more sophisticated ones, but (at least I hope) it is sufficient for this application. After the source there are some remarks for those interested.

<div style="padding:4px; background-color: #ffe0e0;border:1px solid #a06060;">'''Warning!''' The secret phrase in the second line should be changed to some secret value. And it should be the same in both copies.</div>
sub _secret {
"Whatever is your secret phrase, give anything here";
}
sub _intto64 { #a MIME64 type encoding
my $c=shift;
$c &=0x3F;
if($c<10){ return chr(48+$c); }
if($c<10+26){ return chr($c-10+65); }
if($c<10+26+26){ return chr($c-10-26+97); }
if($c==62){ return '_'; }
return '-';
}
sub _encode64 { #encoding three bytes to four chars
my($a,$b,$c)=@_;
$a &= 0xFF; $b &= 0xFF; $c &= 0xFF;
return _intto64($a>>2)._intto64(($a<<4)|($b>>4)).
_intto64(($b<<2)|($c>>6))._intto64($c);
}
sub _from64 { #decoding of the above
my $c=ord(shift||"0");
if($c==95){ return 62;}
if($c==45){ return 63;}
if($c<48+10){ return $c-48; }
if($c<65+26){ return $c-65+10; }
return $c-97+10+26;
}
sub _decode64 { # decoding four chars to three bytes
my($s)=shift;
my ($r1,$r2,$r3,$r4)=(
_from64($s),_from64(substr($s,1)),
_from64(substr($s,2)),_from64(substr($s,3)));
return ($r1<<18)|($r2<<12)|($r3<<6)|$r4;
}
sub _EncodeValue { ## encoded value should not end in a space
my($id) = @_;
use Digest::MD5;
my $salt=substr(Digest::MD5::md5_hex($id, _secret()),0,8);
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0; my $ssid="";
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed); my $idlen=length($id);
$id .= " "; # pad message by spaces
for(my $i=0;$i<$idlen;$i+=3){
#encode $id[0],$id[1],$id[2] as 4 chars
my $v=rand(0x1000000);
$ssid .= _encode64(ord(substr($id,$i))^($v>>16),
ord(substr($id,$i+1))^($v>>8),
ord(substr($id,$i+2))^$v);
}
return $salt.$ssid;
}
sub _DecodeValue {
my($s)=@_;
use Digest::MD5;
my($salt,$ssid)=(substr($s,0,8),substr($s,8));
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0;
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed);
my $id="";
for(my $i=0;$i<length($ssid)-3;$i+=4){
#decode next four chars
my $v=rand(0x1000000)^_decode64(substr($ssid,$i));
$id .= chr($v>>16) . chr(0xff&($v>>8)) . chr(0xff&$v);
}
$id =~ s/ +$//; ## strip spaces at the end
# $salt and $chksum should be equal
$id="" if ($salt ne substr(Digest::MD5::md5_hex($id, _secret()),0,8));
return $id;
}
'''Remarks:'''
*The MIME64-like encoding uses letters (both lower and upper case), digits and the characters - (minus) and _ (underscore). These are safe to use in an URL.
*Both encoding and decoding uses MD5 as the building block. The first eight characters of the ciphertext (encoded string) is used for two purposes. First, it acts as a salt, namely it is added to the secret phrase to derive the seed of the random number generator; second it is used to check message integrity, namely it should match the MD5 hash of the message ''and'' the secret phrase.
*Messages to be encrypted (plaintext) should not end by a space (spaces are used to pad the plaintext to have length divisible by three)
*The encryption is deterministic. Such a scheme is insecure in general. In our case, however, the plaintext contains a timestamp, thus - supposedly - the same message is never encrypted twice.
*Weak points of the scheme: only 32 bit MAC (and seed) value, and relying on perl's pseudorandom function.

==Patching Apache::Login==
We are making two changes to the ''perl_lib/EPrints/Apache/Login.pm'' module. First, always store the URI of the referring page in the hidden ''target'' variable. Second, set the address of the login page to the value of the configuration variable ''external_login_address'' whenever it is defined.

The instructions below are for Eprints version 1.3.1. Locate the line
my $form = $session->render_form( "POST" );
in the above module (it should be line 122). Replace it by the following:
##CSL Always use the "target" variable, and
## redirect to "external_login_address"
my $target = $session->param( "target" );
if(! defined($target) ){
$target = $session->get_uri;
}
my $form = $session->render_form(
"POST",
$session->get_repository->get_conf("external_login_address") );
If ''external_login_address'' is not defined, it has the same effect as the old code.
Roll down to line 142 and comment out this line (add # signs at the beginning):
## my $target = $session->param( "target" );
Finally save the file.

==Define "external_login_address"==
Add the definition of this variable to the file [[archives/ARCHIVEID/cfg/cfg.d/]][[user_login.pl]]:
$c->{external_login_address} = "<nowiki>https://secure.umb.edu/eprints/login</nowiki>";
In the same file you can define the sub ''check_user_password'' as explained in [[LDAP]] and [[LDAP user_login.pl]].

[[Category:Howto]]

Secure login

2009-07-27T19:53:26Z

Laci@degas.ceu.hu: /* Caveats */

When logging into eprints, both username and password travel openly. Usually it is not a problem as eprints has its own authenticating mechanism, and stealing an eprints password gives the intruder very limited power. However when using centralized authentication (e.g., by [[LDAP]]) then protecting the password is more important. To prevent sniffing, login pages usually use secure connection. Here we discuss an easy way to set up eprints to use encoded password traffic.

__TOC__

==The idea==

Change the destination of the eprints login page to a secure host. On the secure host a script receives the data: login name and password (and maybe others), encodes it, and forwards the request with the encrypted data as payload to an unencrypted eprints page. The eprints page decrypts the data and uses it for authentication.

===Requirements===
You need a ''secure http server'' on the same main domain as your your eprints server. For example, if eprints can be reached on the web address ''<nowiki>http://eprints.umb.edu</nowiki>'', then the secure server must have domain name ending with ''umb.edu'', for example ''<nowiki>https://secure.umb.edu</nowiki>.

You should set up a cgi executable directory on the secure host. The apache config extract below does exactly this so that ''<nowiki>https://secure.umb.edu/eprints/whatever</nowiki>'' requests the script ''/opt/cgi-bin/eprints/whatever'' to be executed:
<VirtualHost *:443>
DocumentRoot "/opt/secure"
SSLEngine on
ScriptAlias /eprints/ /opt/cgi-bin/eprints/
<Directory "/opt/cgi-bin/eprints">
AllowOverride None
Options +ExecCGI -MultiView +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Copy the [[#Secure login script|Secure login script]] below into the ''/opt/cgi-bin/eprints/'' directory (or whatever directory you've set up above); copy the [[#Receive data script|receive data script]] into eprints' ''/cgi/'' directory.

Finally [[#Patching Apache::Login |patch the Apache::Login module]] of eprints so that everything works smoothly.

===Caveats===
The login process now works as follows.
# when a page requires authentication, it creates a "login page" with destination at the secure web site
# the "login page" is sent encrypted to the secure site
# the secure site encrypts the payload, and redirects the browser to an unencrypted eprints page ''receive_data''
# ''receive_data'' decrypts the payload, checks credentials, logs in the user if everything checks, and then redirects the browser to the originating page.

What is lost in this process of two redirects is the error message when authentication fails. ''Receive_data'' cannot display the error message as its URL should not be displayed on the user's screen. The final page - which is the original one as well - cannot distinguish between an unsuccessful login and a reload, thus cannot display the error message as well. ''C'est la vie''.

The encrypted data the ''receive_data'' page receives can be a replay of a sniffed older communication. Thus this data should contain a timestamp which should be checked to be recent.

The secure site can also check the credentials, and relay the result only. Interestingly, the result should be sent encrypted, as otherwise the secure site could be used as an oracle to tell whether the password is correct or not (ideal utility for a [http://en.wikipedia.org/wiki/Dictionary_attack dictionary attack]).

==Secure login script==
This script receives the login page over a secure connection. It encrypts the username, password, and other arguments, and relocates the page to eprints' ''receive_data'' page.

Using the secure site configuration above, this script should be copied to ''/opt/cgi-bin/eprints/login'' after changing the address to your own eprint server. And, of course, the script must be executable by the apache process.

##!/usr/bin/perl -w
## secure login script for eprints
## encrypt and automatically forward to /eprints
## Author: Laszlo Csirmaz, 2009
## You are free to use this script
use strict;
sub _RelocateTo {
my $arg=shift;
## CHANGE THIS ADDRESS TO YOUR EPRINT SERRVER'S
"<nowiki>http://eprints.umb.edu/cgi/receive_data?Q=$arg</nowiki>";
}
<nowiki><-- COPY THE CRYPTO ROUTINES HERE --></nowiki>
sub _html2ascii {
my $v=shift;
$v="" if(! defined $v);
$v=~ tr/+/ /;
$v=~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
return $v;
}
my $P={};
my $ct=$ENV{'CONTENT_TYPE');
if($ct && $ct =~ /multipart/i ){
use CGI qw( :cgi :form );
my $req=new CGI; # read all data in
my @pm=$req->param;
foreach my $key (@pm) {
$P->{$key} = _html2ascii($req->param($ley));
}
} elsif ( $ENV{'REQUEST_METHOD'} !~ /^get/i ) {
my $pm=""; while(<>){ $pm .= $_; }
my @pms=split(/&/,$pm);
foreach my $elem(@pms) {
my($t,$v)=split(/=/,$elem);
next if(! defined($t) );
$P->{_html2ascii($t)} = _html2ascii($v);
}
}
## we return the following arguments:
## target, loginparams, username, pw, timestamp
my $arg="";
for my $item ($P->{target},$P->{loginparams},
$P->{login_username}, $P->{login_password} ){
$item="" if(! $item)[
# replace '%' by '%a' and replace ':' by '%c'
$item =~ s/%/%a/g; $item =~ s/:/%c/g;
$arg .= "$item:";
}
my $addr = _RelocateTo( _EncodeValue( $arg . int(time/60) ) );
print "Content-Type: text/html; charset=utf-8\n",
"Location: $addr\n",
"\n",
"<html><head><title>Redirected</title></head>\n",
"<body>\n",
"This page should automatically relocated. If not,\n",
"please <a href=\"$addr\">click here</a>.\n",
"</body>\n",
"</html>\n",
"\n";
exit 0;

==Receive data script==
This script receives the encrypted data from the secure server, decrypts it and logs in the user. A 1 second delay is inserted if there is a problem with the credentials.

This script should be copied to the ''eprints/cgi/receive_data''. It calls the ''check_user_password'' configuration procedure if it is defined.
######################################################
# receive_data
# Part of EPrints 3.1
# Author: Laszlo Csirmaz
# You are free to use/modify this script
######################################################
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );
my $redirect_to="/cgi/users/home";
my $loginparams="";
my $OK=1;
my $arg = $session->param('Q');
if( $arg && length($arg) > 10 ){ #sanity check
$arg = _DecodeValue($arg);
## it is target:loginparams:uname:pw:timenow
$arg = "/cgi/users/home::::" if(!$arg);
my @list = split(/:/,$arg);
for my $i(0..4){
$list[$i]="" if(!$list[$i]);
$list[$i] =~ s/%c/:/g; $list[$i] =~ s/%a/%/g;
}
$OK=0 if( $list[4] !~ /^\d$/ );
if($OK){
my $timediff = int(time/60) - $list[4];
#allow a 2 minute window
$OK=0 if( $timediff<-1 || $timediff > 2 );
}
$redirect_to = $list[0] if($list[0] =~ m#/# );
$loginparams = $list[1];
if($OK){
if( $session->valid_login($list[2],$list[3] ) ){
my $user = EPrints::DataObj::User::user_with_username(
$session,$list[2]);
$session->login($user);
$OK=2;
}
}
}
sleep 1 if( $OK != 2 ); # some problem, don't hurry
my $host = $session->{repository}->get_conf( "host" );
my $port = $session->{repository}->get_conf( "port" );
$redirect_to = "<nowiki>http://$host</nowiki>".($port!=80 :":$port":""). $redirect_to;
$redirect_to .= "?$loginparams" if($loginparams);
$session->redirect( $redirect_to );
$session->terminate;
exit 0;
<nowiki></nowiki>
While we made a lot of effort to protect the integrity and secrecy of the username and the data, nothing prevents a bad guy to submit bogus data to our secure script! Thus we relocate to the eprints repository addresses only, and accept the "relocate" argument only if it starts with a slash.

==Crypto routines==
These routines perform encryption and decryption. It is a lightweight version of more sophisticated ones, but (at least I hope) it is sufficient for this application. After the source there are some remarks for those interested.

<div style="padding:4px; background-color: #ffe0e0;border:1px solid #a06060;">'''Warning!''' The secret phrase in the second line should be changed to some secret value. And it should be the same in both copies.</div>
sub _secret {
"Whatever is your secret phrase, give anything here";
}
sub _intto64 { #a MIME64 type encoding
my $c=shift;
$c &=0x3F;
if($c<10){ return chr(48+$c); }
if($c<10+26){ return chr($c-10+65); }
if($c<10+26+26){ return chr($c-10-26+97); }
if($c==62){ return '_'; }
return '-';
}
sub _encode64 { #encoding three bytes to four chars
my($a,$b,$c)=@_;
$a &= 0xFF; $b &= 0xFF; $c &= 0xFF;
return _intto64($a>>2)._intto64(($a<<4)|($b>>4)).
_intto64(($b<<2)|($c>>6))._intto64($c);
}
sub _from64 { #decoding of the above
my $c=ord(shift||"0");
if($c==95){ return 62;}
if($c==45){ return 63;}
if($c<48+10){ return $c-48; }
if($c<65+26){ return $c-65+10; }
return $c-97+10+26;
}
sub _decode64 { # decoding four chars to three bytes
my($s)=shift;
my ($r1,$r2,$r3,$r4)=(
_from64($s),_from64(substr($s,1)),
_from64(substr($s,2)),_from64(substr($s,3)));
return ($r1<<18)|($r2<<12)|($r3<<6)|$r4;
}
sub _EncodeValue { ## encoded value should not end in a space
my($id) = @_;
use Digest::MD5;
my $salt=substr(Digest::MD5::md5_hex($id, _secret()),0,8);
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0; my $ssid="";
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed); my $idlen=length($id);
$id .= " "; # pad message by spaces
for(my $i=0;$i<$idlen;$i+=3){
#encode $id[0],$id[1],$id[2] as 4 chars
my $v=rand(0x1000000);
$ssid .= _encode64(ord(substr($id,$i))^($v>>16),
ord(substr($id,$i+1))^($v>>8),
ord(substr($id,$i+2))^$v);
}
return $salt.$ssid;
}
sub _DecodeValue {
my($s)=@_;
use Digest::MD5;
my($salt,$ssid)=(substr($s,0,8),substr($s,8));
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0;
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed);
my $id="";
for(my $i=0;$i<length($ssid)-3;$i+=4){
#decode next four chars
my $v=rand(0x1000000)^_decode64(substr($ssid,$i));
$id .= chr($v>>16) . chr(0xff&($v>>8)) . chr(0xff&$v);
}
$id =~ s/ +$//; ## strip spaces at the end
# $salt and $chksum should be equal
$id="" if ($salt ne substr(Digest::MD5::md5_hex($id, _secret()),0,8));
return $id;
}
'''Remarks:'''
*The MIME64-like encoding uses letters (both lower and upper case), digits and the characters - (minus) and _ (underscore). These are safe to use in an URL.
*Both encoding and decoding uses MD5 as the building block. The first eight characters of the ciphertext (encoded string) is used for two purposes. First, it acts as a salt, namely it is added to the secret phrase to derive the seed of the random number generator; second it is used to check message integrity, namely it should match the MD5 hash of the message ''and'' the secret phrase.
*Messages to be encrypted (plaintext) should not end by a space (spaces are used to pad the plaintext to have length divisible by three)
*The encryption is deterministic. Such a scheme is insecure in general. In our case, however, the plaintext contains a timestamp, thus - supposedly - the same message is never encrypted twice.
*Weak points of the scheme: only 32 bit MAC (and seed) value, and relying on perl's pseudorandom function.

==Patching Apache::Login==
We are making two changes to the ''perl_lib/EPrints/Apache/Login.pm'' module. First, always store the URI of the referring page in the hidden ''target'' variable. Second, set the address of the login page to the value of the configuration variable ''external_login_address'' whenever it is defined.

The instructions below are for Eprints version 1.3.1. Locate the line
my $form = $session->render_form( "POST" );
in the above module (it should be line 122). Replace it by the following:
##CSL Always use the "target" variable, and
## redirect to "external_login_address"
my $target = $session->param( "target" );
if(! defined($target) ){
$target = $session->get_uri;
}
my $form = $session->render_form(
"POST",
$session->get_repository->get_conf("external_login_address") );
If ''external_login_address'' is not defined, it has the same effect as the old code.
Roll down to line 142 and comment out this line (add # signs at the beginning):
## my $target = $session->param( "target" );
Finally save the file.

==Define "external_login_address"==
Add the definition of this variable to the file [[archives/ARCHIVEID/cfg/cfg.d/]][[user_login.pl]]:
$c->{external_login_address} = "<nowiki>https://secure.umb.edu/eprints/login</nowiki>";
In the same file you can define the sub ''check_user_password'' as explained in [[LDAP]] and [[LDAP user_login.pl]].

[[Category:Howto]]

Secure login

2009-07-27T19:48:08Z

Laci@degas.ceu.hu:

When logging into eprints, both username and password travel openly. Usually it is not a problem as eprints has its own authenticating mechanism, and stealing an eprints password gives the intruder very limited power. However when using centralized authentication (e.g., by [[LDAP]]) then protecting the password is more important. To prevent sniffing, login pages usually use secure connection. Here we discuss an easy way to set up eprints to use encoded password traffic.

__TOC__

==The idea==

Change the destination of the eprints login page to a secure host. On the secure host a script receives the data: login name and password (and maybe others), encodes it, and forwards the request with the encrypted data as payload to an unencrypted eprints page. The eprints page decrypts the data and uses it for authentication.

===Requirements===
You need a ''secure http server'' on the same main domain as your your eprints server. For example, if eprints can be reached on the web address ''<nowiki>http://eprints.umb.edu</nowiki>'', then the secure server must have domain name ending with ''umb.edu'', for example ''<nowiki>https://secure.umb.edu</nowiki>.

You should set up a cgi executable directory on the secure host. The apache config extract below does exactly this so that ''<nowiki>https://secure.umb.edu/eprints/whatever</nowiki>'' requests the script ''/opt/cgi-bin/eprints/whatever'' to be executed:
<VirtualHost *:443>
DocumentRoot "/opt/secure"
SSLEngine on
ScriptAlias /eprints/ /opt/cgi-bin/eprints/
<Directory "/opt/cgi-bin/eprints">
AllowOverride None
Options +ExecCGI -MultiView +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Copy the [[#Secure login script|Secure login script]] below into the ''/opt/cgi-bin/eprints/'' directory (or whatever directory you've set up above); copy the [[#Receive data script|receive data script]] into eprints' ''/cgi/'' directory.

Finally [[#Patching Apache::Login |patch the Apache::Login module]] of eprints so that everything works smoothly.

===Caveats===
The login process now works as follows.
# when a page requires authentication, it creates a "login page" with destination at the secure web site
# the "login page" is sent encrypted to the secure site
# the secure site encrypts the payload, and redirects the browser to an unencrypted eprints page ''receive_data''
# ''receive_data'' decrypts the payload, checks credentials, logs in the user if everything checks, and then redirects the browser to the originating page.

What is lost in this process of two redirects is the error message when authentication fails. ''Receive_data'' cannot display the error message as its URL should not be displayed on the user's screen. The final page - which is the original one as well - cannot distinguish between an unsuccessful login and a reload, thus cannot display the error message as well. ''C'est la vie''.

The encrypted data the ''receive_data'' page receives can be a replay of a sniffed older communication. Thus this data should contain a timestamp and checked to be recent.

The secure site can also check the credentials, and relay the result only. Interestingly, the result should be sent encrypted, as otherwise the secure site could be used as an oracle to tell whether the password is correct or not (ideal for a [http://en.wikipedia.org/wiki/Dictionary_attack dictionary attack]).

==Secure login script==
This script receives the login page over a secure connection. It encrypts the username, password, and other arguments, and relocates the page to eprints' ''receive_data'' page.

Using the secure site configuration above, this script should be copied to ''/opt/cgi-bin/eprints/login'' after changing the address to your own eprint server. And, of course, the script must be executable by the apache process.

##!/usr/bin/perl -w
## secure login script for eprints
## encrypt and automatically forward to /eprints
## Author: Laszlo Csirmaz, 2009
## You are free to use this script
use strict;
sub _RelocateTo {
my $arg=shift;
## CHANGE THIS ADDRESS TO YOUR EPRINT SERRVER'S
"<nowiki>http://eprints.umb.edu/cgi/receive_data?Q=$arg</nowiki>";
}
<nowiki><-- COPY THE CRYPTO ROUTINES HERE --></nowiki>
sub _html2ascii {
my $v=shift;
$v="" if(! defined $v);
$v=~ tr/+/ /;
$v=~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
return $v;
}
my $P={};
my $ct=$ENV{'CONTENT_TYPE');
if($ct && $ct =~ /multipart/i ){
use CGI qw( :cgi :form );
my $req=new CGI; # read all data in
my @pm=$req->param;
foreach my $key (@pm) {
$P->{$key} = _html2ascii($req->param($ley));
}
} elsif ( $ENV{'REQUEST_METHOD'} !~ /^get/i ) {
my $pm=""; while(<>){ $pm .= $_; }
my @pms=split(/&/,$pm);
foreach my $elem(@pms) {
my($t,$v)=split(/=/,$elem);
next if(! defined($t) );
$P->{_html2ascii($t)} = _html2ascii($v);
}
}
## we return the following arguments:
## target, loginparams, username, pw, timestamp
my $arg="";
for my $item ($P->{target},$P->{loginparams},
$P->{login_username}, $P->{login_password} ){
$item="" if(! $item)[
# replace '%' by '%a' and replace ':' by '%c'
$item =~ s/%/%a/g; $item =~ s/:/%c/g;
$arg .= "$item:";
}
my $addr = _RelocateTo( _EncodeValue( $arg . int(time/60) ) );
print "Content-Type: text/html; charset=utf-8\n",
"Location: $addr\n",
"\n",
"<html><head><title>Redirected</title></head>\n",
"<body>\n",
"This page should automatically relocated. If not,\n",
"please <a href=\"$addr\">click here</a>.\n",
"</body>\n",
"</html>\n",
"\n";
exit 0;

==Receive data script==
This script receives the encrypted data from the secure server, decrypts it and logs in the user. A 1 second delay is inserted if there is a problem with the credentials.

This script should be copied to the ''eprints/cgi/receive_data''. It calls the ''check_user_password'' configuration procedure if it is defined.
######################################################
# receive_data
# Part of EPrints 3.1
# Author: Laszlo Csirmaz
# You are free to use/modify this script
######################################################
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );
my $redirect_to="/cgi/users/home";
my $loginparams="";
my $OK=1;
my $arg = $session->param('Q');
if( $arg && length($arg) > 10 ){ #sanity check
$arg = _DecodeValue($arg);
## it is target:loginparams:uname:pw:timenow
$arg = "/cgi/users/home::::" if(!$arg);
my @list = split(/:/,$arg);
for my $i(0..4){
$list[$i]="" if(!$list[$i]);
$list[$i] =~ s/%c/:/g; $list[$i] =~ s/%a/%/g;
}
$OK=0 if( $list[4] !~ /^\d$/ );
if($OK){
my $timediff = int(time/60) - $list[4];
#allow a 2 minute window
$OK=0 if( $timediff<-1 || $timediff > 2 );
}
$redirect_to = $list[0] if($list[0] =~ m#/# );
$loginparams = $list[1];
if($OK){
if( $session->valid_login($list[2],$list[3] ) ){
my $user = EPrints::DataObj::User::user_with_username(
$session,$list[2]);
$session->login($user);
$OK=2;
}
}
}
sleep 1 if( $OK != 2 ); # some problem, don't hurry
my $host = $session->{repository}->get_conf( "host" );
my $port = $session->{repository}->get_conf( "port" );
$redirect_to = "<nowiki>http://$host</nowiki>".($port!=80 :":$port":""). $redirect_to;
$redirect_to .= "?$loginparams" if($loginparams);
$session->redirect( $redirect_to );
$session->terminate;
exit 0;
<nowiki></nowiki>
While we made a lot of effort to protect the integrity and secrecy of the username and the data, nothing prevents a bad guy to submit bogus data to our secure script! Thus we relocate to the eprints repository addresses only, and accept the "relocate" argument only if it starts with a slash.

==Crypto routines==
These routines perform encryption and decryption. It is a lightweight version of more sophisticated ones, but (at least I hope) it is sufficient for this application. After the source there are some remarks for those interested.

<div style="padding:4px; background-color: #ffe0e0;border:1px solid #a06060;">'''Warning!''' The secret phrase in the second line should be changed to some secret value. And it should be the same in both copies.</div>
sub _secret {
"Whatever is your secret phrase, give anything here";
}
sub _intto64 { #a MIME64 type encoding
my $c=shift;
$c &=0x3F;
if($c<10){ return chr(48+$c); }
if($c<10+26){ return chr($c-10+65); }
if($c<10+26+26){ return chr($c-10-26+97); }
if($c==62){ return '_'; }
return '-';
}
sub _encode64 { #encoding three bytes to four chars
my($a,$b,$c)=@_;
$a &= 0xFF; $b &= 0xFF; $c &= 0xFF;
return _intto64($a>>2)._intto64(($a<<4)|($b>>4)).
_intto64(($b<<2)|($c>>6))._intto64($c);
}
sub _from64 { #decoding of the above
my $c=ord(shift||"0");
if($c==95){ return 62;}
if($c==45){ return 63;}
if($c<48+10){ return $c-48; }
if($c<65+26){ return $c-65+10; }
return $c-97+10+26;
}
sub _decode64 { # decoding four chars to three bytes
my($s)=shift;
my ($r1,$r2,$r3,$r4)=(
_from64($s),_from64(substr($s,1)),
_from64(substr($s,2)),_from64(substr($s,3)));
return ($r1<<18)|($r2<<12)|($r3<<6)|$r4;
}
sub _EncodeValue { ## encoded value should not end in a space
my($id) = @_;
use Digest::MD5;
my $salt=substr(Digest::MD5::md5_hex($id, _secret()),0,8);
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0; my $ssid="";
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed); my $idlen=length($id);
$id .= " "; # pad message by spaces
for(my $i=0;$i<$idlen;$i+=3){
#encode $id[0],$id[1],$id[2] as 4 chars
my $v=rand(0x1000000);
$ssid .= _encode64(ord(substr($id,$i))^($v>>16),
ord(substr($id,$i+1))^($v>>8),
ord(substr($id,$i+2))^$v);
}
return $salt.$ssid;
}
sub _DecodeValue {
my($s)=@_;
use Digest::MD5;
my($salt,$ssid)=(substr($s,0,8),substr($s,8));
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0;
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed);
my $id="";
for(my $i=0;$i<length($ssid)-3;$i+=4){
#decode next four chars
my $v=rand(0x1000000)^_decode64(substr($ssid,$i));
$id .= chr($v>>16) . chr(0xff&($v>>8)) . chr(0xff&$v);
}
$id =~ s/ +$//; ## strip spaces at the end
# $salt and $chksum should be equal
$id="" if ($salt ne substr(Digest::MD5::md5_hex($id, _secret()),0,8));
return $id;
}
'''Remarks:'''
*The MIME64-like encoding uses letters (both lower and upper case), digits and the characters - (minus) and _ (underscore). These are safe to use in an URL.
*Both encoding and decoding uses MD5 as the building block. The first eight characters of the ciphertext (encoded string) is used for two purposes. First, it acts as a salt, namely it is added to the secret phrase to derive the seed of the random number generator; second it is used to check message integrity, namely it should match the MD5 hash of the message ''and'' the secret phrase.
*Messages to be encrypted (plaintext) should not end by a space (spaces are used to pad the plaintext to have length divisible by three)
*The encryption is deterministic. Such a scheme is insecure in general. In our case, however, the plaintext contains a timestamp, thus - supposedly - the same message is never encrypted twice.
*Weak points of the scheme: only 32 bit MAC (and seed) value, and relying on perl's pseudorandom function.

==Patching Apache::Login==
We are making two changes to the ''perl_lib/EPrints/Apache/Login.pm'' module. First, always store the URI of the referring page in the hidden ''target'' variable. Second, set the address of the login page to the value of the configuration variable ''external_login_address'' whenever it is defined.

The instructions below are for Eprints version 1.3.1. Locate the line
my $form = $session->render_form( "POST" );
in the above module (it should be line 122). Replace it by the following:
##CSL Always use the "target" variable, and
## redirect to "external_login_address"
my $target = $session->param( "target" );
if(! defined($target) ){
$target = $session->get_uri;
}
my $form = $session->render_form(
"POST",
$session->get_repository->get_conf("external_login_address") );
If ''external_login_address'' is not defined, it has the same effect as the old code.
Roll down to line 142 and comment out this line (add # signs at the beginning):
## my $target = $session->param( "target" );
Finally save the file.

==Define "external_login_address"==
Add the definition of this variable to the file [[archives/ARCHIVEID/cfg/cfg.d/]][[user_login.pl]]:
$c->{external_login_address} = "<nowiki>https://secure.umb.edu/eprints/login</nowiki>";
In the same file you can define the sub ''check_user_password'' as explained in [[LDAP]] and [[LDAP user_login.pl]].

[[Category:Howto]]

Secure login

2009-07-27T19:46:51Z

Laci@degas.ceu.hu: /* Patching Apache::Login */

When logging into eprints, both username and password travel openly. Usually it is not a problem as eprints has its own authenticating mechanism, and stealing an eprints password gives the intruder very limited power. However when using centralized authentication (e.g., by [[LDAP]]) then protecting the password is more important. To prevent sniffing login pages usually use secure connection. Here we discuss an easy way to set up eprints to use encoded password traffic.

__TOC__

==The idea==

Change the destination of the eprints login page to a secure host. On the secure host a script receives the data: login name and password (and maybe others), encodes it, and forwards the request with the encrypted data as payload to an unencrypted eprints page. The eprints page decrypts the data and uses it for authentication.

===Requirements===
You need a ''secure http server'' on the same main domain as your your eprints server. For example, if eprints can be reached on the web address ''<nowiki>http://eprints.umb.edu</nowiki>'', then the secure server must have domain name ending with ''umb.edu'', for example ''<nowiki>https://secure.umb.edu</nowiki>.

You should set up a cgi executable directory on the secure host. The apache config extract below does exactly this so that ''<nowiki>https://secure.umb.edu/eprints/whatever</nowiki>'' requests the script ''/opt/cgi-bin/eprints/whatever'' to be executed:
<VirtualHost *:443>
DocumentRoot "/opt/secure"
SSLEngine on
ScriptAlias /eprints/ /opt/cgi-bin/eprints/
<Directory "/opt/cgi-bin/eprints">
AllowOverride None
Options +ExecCGI -MultiView +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Copy the [[#Secure login script|Secure login script]] below into the ''/opt/cgi-bin/eprints/'' directory (or whatever directory you've set up above); copy the [[#Receive data script|receive data script]] into eprints' ''/cgi/'' directory.

Finally [[#Patching Apache::Login |patch the Apache::Login module]] of eprints so that everything works smoothly.

===Caveats===
The login process now works as follows.
# when a page requires authentication, it creates a "login page" with destination at the secure web site
# the "login page" is sent encrypted to the secure site
# the secure site encrypts the payload, and redirects the browser to an unencrypted eprints page ''receive_data''
# ''receive_data'' decrypts the payload, checks credentials, logs in the user if everything checks, and then redirects the browser to the originating page.

What is lost in this process of two redirects is the error message when authentication fails. ''Receive_data'' cannot display the error message as its URL should not be displayed on the user's screen. The final page - which is the original one as well - cannot distinguish between an unsuccessful login and a reload, thus cannot display the error message as well. ''C'est la vie''.

The encrypted data the ''receive_data'' page receives can be a replay of a sniffed older communication. Thus this data should contain a timestamp and checked to be recent.

The secure site can also check the credentials, and relay the result only. Interestingly, the result should be sent encrypted, as otherwise the secure site could be used as an oracle to tell whether the password is correct or not (ideal for a [http://en.wikipedia.org/wiki/Dictionary_attack dictionary attack]).

==Secure login script==
This script receives the login page over a secure connection. It encrypts the username, password, and other arguments, and relocates the page to eprints' ''receive_data'' page.

Using the secure site configuration above, this script should be copied to ''/opt/cgi-bin/eprints/login'' after changing the address to your own eprint server. And, of course, the script must be executable by the apache process.

##!/usr/bin/perl -w
## secure login script for eprints
## encrypt and automatically forward to /eprints
## Author: Laszlo Csirmaz, 2009
## You are free to use this script
use strict;
sub _RelocateTo {
my $arg=shift;
## CHANGE THIS ADDRESS TO YOUR EPRINT SERRVER'S
"<nowiki>http://eprints.umb.edu/cgi/receive_data?Q=$arg</nowiki>";
}
<nowiki><-- COPY THE CRYPTO ROUTINES HERE --></nowiki>
sub _html2ascii {
my $v=shift;
$v="" if(! defined $v);
$v=~ tr/+/ /;
$v=~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
return $v;
}
my $P={};
my $ct=$ENV{'CONTENT_TYPE');
if($ct && $ct =~ /multipart/i ){
use CGI qw( :cgi :form );
my $req=new CGI; # read all data in
my @pm=$req->param;
foreach my $key (@pm) {
$P->{$key} = _html2ascii($req->param($ley));
}
} elsif ( $ENV{'REQUEST_METHOD'} !~ /^get/i ) {
my $pm=""; while(<>){ $pm .= $_; }
my @pms=split(/&/,$pm);
foreach my $elem(@pms) {
my($t,$v)=split(/=/,$elem);
next if(! defined($t) );
$P->{_html2ascii($t)} = _html2ascii($v);
}
}
## we return the following arguments:
## target, loginparams, username, pw, timestamp
my $arg="";
for my $item ($P->{target},$P->{loginparams},
$P->{login_username}, $P->{login_password} ){
$item="" if(! $item)[
# replace '%' by '%a' and replace ':' by '%c'
$item =~ s/%/%a/g; $item =~ s/:/%c/g;
$arg .= "$item:";
}
my $addr = _RelocateTo( _EncodeValue( $arg . int(time/60) ) );
print "Content-Type: text/html; charset=utf-8\n",
"Location: $addr\n",
"\n",
"<html><head><title>Redirected</title></head>\n",
"<body>\n",
"This page should automatically relocated. If not,\n",
"please <a href=\"$addr\">click here</a>.\n",
"</body>\n",
"</html>\n",
"\n";
exit 0;

==Receive data script==
This script receives the encrypted data from the secure server, decrypts it and logs in the user. A 1 second delay is inserted if there is a problem with the credentials.

This script should be copied to the ''eprints/cgi/receive_data''. It calls the ''check_user_password'' configuration procedure if it is defined.
######################################################
# receive_data
# Part of EPrints 3.1
# Author: Laszlo Csirmaz
# You are free to use/modify this script
######################################################
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );
my $redirect_to="/cgi/users/home";
my $loginparams="";
my $OK=1;
my $arg = $session->param('Q');
if( $arg && length($arg) > 10 ){ #sanity check
$arg = _DecodeValue($arg);
## it is target:loginparams:uname:pw:timenow
$arg = "/cgi/users/home::::" if(!$arg);
my @list = split(/:/,$arg);
for my $i(0..4){
$list[$i]="" if(!$list[$i]);
$list[$i] =~ s/%c/:/g; $list[$i] =~ s/%a/%/g;
}
$OK=0 if( $list[4] !~ /^\d$/ );
if($OK){
my $timediff = int(time/60) - $list[4];
#allow a 2 minute window
$OK=0 if( $timediff<-1 || $timediff > 2 );
}
$redirect_to = $list[0] if($list[0] =~ m#/# );
$loginparams = $list[1];
if($OK){
if( $session->valid_login($list[2],$list[3] ) ){
my $user = EPrints::DataObj::User::user_with_username(
$session,$list[2]);
$session->login($user);
$OK=2;
}
}
}
sleep 1 if( $OK != 2 ); # some problem, don't hurry
my $host = $session->{repository}->get_conf( "host" );
my $port = $session->{repository}->get_conf( "port" );
$redirect_to = "<nowiki>http://$host</nowiki>".($port!=80 :":$port":""). $redirect_to;
$redirect_to .= "?$loginparams" if($loginparams);
$session->redirect( $redirect_to );
$session->terminate;
exit 0;
<nowiki></nowiki>
While we made a lot of effort to protect the integrity and secrecy of the username and the data, nothing prevents a bad guy to submit bogus data to our secure script! Thus we relocate to the eprints repository addresses only, and accept the "relocate" argument only if it starts with a slash.

==Crypto routines==
These routines perform encryption and decryption. It is a lightweight version of more sophisticated ones, but (at least I hope) it is sufficient for this application. After the source there are some remarks for those interested.

<div style="padding:4px; background-color: #ffe0e0;border:1px solid #a06060;">'''Warning!''' The secret phrase in the second line should be changed to some secret value. And it should be the same in both copies.</div>
sub _secret {
"Whatever is your secret phrase, give anything here";
}
sub _intto64 { #a MIME64 type encoding
my $c=shift;
$c &=0x3F;
if($c<10){ return chr(48+$c); }
if($c<10+26){ return chr($c-10+65); }
if($c<10+26+26){ return chr($c-10-26+97); }
if($c==62){ return '_'; }
return '-';
}
sub _encode64 { #encoding three bytes to four chars
my($a,$b,$c)=@_;
$a &= 0xFF; $b &= 0xFF; $c &= 0xFF;
return _intto64($a>>2)._intto64(($a<<4)|($b>>4)).
_intto64(($b<<2)|($c>>6))._intto64($c);
}
sub _from64 { #decoding of the above
my $c=ord(shift||"0");
if($c==95){ return 62;}
if($c==45){ return 63;}
if($c<48+10){ return $c-48; }
if($c<65+26){ return $c-65+10; }
return $c-97+10+26;
}
sub _decode64 { # decoding four chars to three bytes
my($s)=shift;
my ($r1,$r2,$r3,$r4)=(
_from64($s),_from64(substr($s,1)),
_from64(substr($s,2)),_from64(substr($s,3)));
return ($r1<<18)|($r2<<12)|($r3<<6)|$r4;
}
sub _EncodeValue { ## encoded value should not end in a space
my($id) = @_;
use Digest::MD5;
my $salt=substr(Digest::MD5::md5_hex($id, _secret()),0,8);
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0; my $ssid="";
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed); my $idlen=length($id);
$id .= " "; # pad message by spaces
for(my $i=0;$i<$idlen;$i+=3){
#encode $id[0],$id[1],$id[2] as 4 chars
my $v=rand(0x1000000);
$ssid .= _encode64(ord(substr($id,$i))^($v>>16),
ord(substr($id,$i+1))^($v>>8),
ord(substr($id,$i+2))^$v);
}
return $salt.$ssid;
}
sub _DecodeValue {
my($s)=@_;
use Digest::MD5;
my($salt,$ssid)=(substr($s,0,8),substr($s,8));
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0;
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed);
my $id="";
for(my $i=0;$i<length($ssid)-3;$i+=4){
#decode next four chars
my $v=rand(0x1000000)^_decode64(substr($ssid,$i));
$id .= chr($v>>16) . chr(0xff&($v>>8)) . chr(0xff&$v);
}
$id =~ s/ +$//; ## strip spaces at the end
# $salt and $chksum should be equal
$id="" if ($salt ne substr(Digest::MD5::md5_hex($id, _secret()),0,8));
return $id;
}
'''Remarks:'''
*The MIME64-like encoding uses letters (both lower and upper case), digits and the characters - (minus) and _ (underscore). These are safe to use in an URL.
*Both encoding and decoding uses MD5 as the building block. The first eight characters of the ciphertext (encoded string) is used for two purposes. First, it acts as a salt, namely it is added to the secret phrase to derive the seed of the random number generator; second it is used to check message integrity, namely it should match the MD5 hash of the message ''and'' the secret phrase.
*Messages to be encrypted (plaintext) should not end by a space (spaces are used to pad the plaintext to have length divisible by three)
*The encryption is deterministic. Such a scheme is insecure in general. In our case, however, the plaintext contains a timestamp, thus - supposedly - the same message is never encrypted twice.
*Weak points of the scheme: only 32 bit MAC (and seed) value, and relying on perl's pseudorandom function.

==Patching Apache::Login==
We are making two changes to the ''perl_lib/EPrints/Apache/Login.pm'' module. First, always store the URI of the referring page in the hidden ''target'' variable. Second, set the address of the login page to the value of the configuration variable ''external_login_address'' whenever it is defined.

The instructions below are for Eprints version 1.3.1. Locate the line
my $form = $session->render_form( "POST" );
in the above module (it should be line 122). Replace it by the following:
##CSL Always use the "target" variable, and
## redirect to "external_login_address"
my $target = $session->param( "target" );
if(! defined($target) ){
$target = $session->get_uri;
}
my $form = $session->render_form(
"POST",
$session->get_repository->get_conf("external_login_address") );
If ''external_login_address'' is not defined, it has the same effect as the old code.
Roll down to line 142 and comment out this line (add # signs at the beginning):
## my $target = $session->param( "target" );
Finally save the file.

==Define "external_login_address"==
Add the definition of this variable to the file [[archives/ARCHIVEID/cfg/cfg.d/]][[user_login.pl]]:
$c->{external_login_address} = "<nowiki>https://secure.umb.edu/eprints/login</nowiki>";
In the same file you can define the sub ''check_user_password'' as explained in [[LDAP]] and [[LDAP user_login.pl]].

[[Category:Howto]]

Secure login

2009-07-27T19:31:58Z

Laci@degas.ceu.hu: /* Patching Apache::Login */

When logging into eprints, both username and password travel openly. Usually it is not a problem as eprints has its own authenticating mechanism, and stealing an eprints password gives the intruder very limited power. However when using centralized authentication (e.g., by [[LDAP]]) then protecting the password is more important. To prevent sniffing login pages usually use secure connection. Here we discuss an easy way to set up eprints to use encoded password traffic.

__TOC__

==The idea==

Change the destination of the eprints login page to a secure host. On the secure host a script receives the data: login name and password (and maybe others), encodes it, and forwards the request with the encrypted data as payload to an unencrypted eprints page. The eprints page decrypts the data and uses it for authentication.

===Requirements===
You need a ''secure http server'' on the same main domain as your your eprints server. For example, if eprints can be reached on the web address ''<nowiki>http://eprints.umb.edu</nowiki>'', then the secure server must have domain name ending with ''umb.edu'', for example ''<nowiki>https://secure.umb.edu</nowiki>.

You should set up a cgi executable directory on the secure host. The apache config extract below does exactly this so that ''<nowiki>https://secure.umb.edu/eprints/whatever</nowiki>'' requests the script ''/opt/cgi-bin/eprints/whatever'' to be executed:
<VirtualHost *:443>
DocumentRoot "/opt/secure"
SSLEngine on
ScriptAlias /eprints/ /opt/cgi-bin/eprints/
<Directory "/opt/cgi-bin/eprints">
AllowOverride None
Options +ExecCGI -MultiView +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Copy the [[#Secure login script|Secure login script]] below into the ''/opt/cgi-bin/eprints/'' directory (or whatever directory you've set up above); copy the [[#Receive data script|receive data script]] into eprints' ''/cgi/'' directory.

Finally [[#Patching Apache::Login |patch the Apache::Login module]] of eprints so that everything works smoothly.

===Caveats===
The login process now works as follows.
# when a page requires authentication, it creates a "login page" with destination at the secure web site
# the "login page" is sent encrypted to the secure site
# the secure site encrypts the payload, and redirects the browser to an unencrypted eprints page ''receive_data''
# ''receive_data'' decrypts the payload, checks credentials, logs in the user if everything checks, and then redirects the browser to the originating page.

What is lost in this process of two redirects is the error message when authentication fails. ''Receive_data'' cannot display the error message as its URL should not be displayed on the user's screen. The final page - which is the original one as well - cannot distinguish between an unsuccessful login and a reload, thus cannot display the error message as well. ''C'est la vie''.

The encrypted data the ''receive_data'' page receives can be a replay of a sniffed older communication. Thus this data should contain a timestamp and checked to be recent.

The secure site can also check the credentials, and relay the result only. Interestingly, the result should be sent encrypted, as otherwise the secure site could be used as an oracle to tell whether the password is correct or not (ideal for a [http://en.wikipedia.org/wiki/Dictionary_attack dictionary attack]).

==Secure login script==
This script receives the login page over a secure connection. It encrypts the username, password, and other arguments, and relocates the page to eprints' ''receive_data'' page.

Using the secure site configuration above, this script should be copied to ''/opt/cgi-bin/eprints/login'' after changing the address to your own eprint server. And, of course, the script must be executable by the apache process.

##!/usr/bin/perl -w
## secure login script for eprints
## encrypt and automatically forward to /eprints
## Author: Laszlo Csirmaz, 2009
## You are free to use this script
use strict;
sub _RelocateTo {
my $arg=shift;
## CHANGE THIS ADDRESS TO YOUR EPRINT SERRVER'S
"<nowiki>http://eprints.umb.edu/cgi/receive_data?Q=$arg</nowiki>";
}
<nowiki><-- COPY THE CRYPTO ROUTINES HERE --></nowiki>
sub _html2ascii {
my $v=shift;
$v="" if(! defined $v);
$v=~ tr/+/ /;
$v=~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
return $v;
}
my $P={};
my $ct=$ENV{'CONTENT_TYPE');
if($ct && $ct =~ /multipart/i ){
use CGI qw( :cgi :form );
my $req=new CGI; # read all data in
my @pm=$req->param;
foreach my $key (@pm) {
$P->{$key} = _html2ascii($req->param($ley));
}
} elsif ( $ENV{'REQUEST_METHOD'} !~ /^get/i ) {
my $pm=""; while(<>){ $pm .= $_; }
my @pms=split(/&/,$pm);
foreach my $elem(@pms) {
my($t,$v)=split(/=/,$elem);
next if(! defined($t) );
$P->{_html2ascii($t)} = _html2ascii($v);
}
}
## we return the following arguments:
## target, loginparams, username, pw, timestamp
my $arg="";
for my $item ($P->{target},$P->{loginparams},
$P->{login_username}, $P->{login_password} ){
$item="" if(! $item)[
# replace '%' by '%a' and replace ':' by '%c'
$item =~ s/%/%a/g; $item =~ s/:/%c/g;
$arg .= "$item:";
}
my $addr = _RelocateTo( _EncodeValue( $arg . int(time/60) ) );
print "Content-Type: text/html; charset=utf-8\n",
"Location: $addr\n",
"\n",
"<html><head><title>Redirected</title></head>\n",
"<body>\n",
"This page should automatically relocated. If not,\n",
"please <a href=\"$addr\">click here</a>.\n",
"</body>\n",
"</html>\n",
"\n";
exit 0;

==Receive data script==
This script receives the encrypted data from the secure server, decrypts it and logs in the user. A 1 second delay is inserted if there is a problem with the credentials.

This script should be copied to the ''eprints/cgi/receive_data''. It calls the ''check_user_password'' configuration procedure if it is defined.
######################################################
# receive_data
# Part of EPrints 3.1
# Author: Laszlo Csirmaz
# You are free to use/modify this script
######################################################
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );
my $redirect_to="/cgi/users/home";
my $loginparams="";
my $OK=1;
my $arg = $session->param('Q');
if( $arg && length($arg) > 10 ){ #sanity check
$arg = _DecodeValue($arg);
## it is target:loginparams:uname:pw:timenow
$arg = "/cgi/users/home::::" if(!$arg);
my @list = split(/:/,$arg);
for my $i(0..4){
$list[$i]="" if(!$list[$i]);
$list[$i] =~ s/%c/:/g; $list[$i] =~ s/%a/%/g;
}
$OK=0 if( $list[4] !~ /^\d$/ );
if($OK){
my $timediff = int(time/60) - $list[4];
#allow a 2 minute window
$OK=0 if( $timediff<-1 || $timediff > 2 );
}
$redirect_to = $list[0] if($list[0] =~ m#/# );
$loginparams = $list[1];
if($OK){
if( $session->valid_login($list[2],$list[3] ) ){
my $user = EPrints::DataObj::User::user_with_username(
$session,$list[2]);
$session->login($user);
$OK=2;
}
}
}
sleep 1 if( $OK != 2 ); # some problem, don't hurry
my $host = $session->{repository}->get_conf( "host" );
my $port = $session->{repository}->get_conf( "port" );
$redirect_to = "<nowiki>http://$host</nowiki>".($port!=80 :":$port":""). $redirect_to;
$redirect_to .= "?$loginparams" if($loginparams);
$session->redirect( $redirect_to );
$session->terminate;
exit 0;
<nowiki></nowiki>
While we made a lot of effort to protect the integrity and secrecy of the username and the data, nothing prevents a bad guy to submit bogus data to our secure script! Thus we relocate to the eprints repository addresses only, and accept the "relocate" argument only if it starts with a slash.

==Crypto routines==
These routines perform encryption and decryption. It is a lightweight version of more sophisticated ones, but (at least I hope) it is sufficient for this application. After the source there are some remarks for those interested.

<div style="padding:4px; background-color: #ffe0e0;border:1px solid #a06060;">'''Warning!''' The secret phrase in the second line should be changed to some secret value. And it should be the same in both copies.</div>
sub _secret {
"Whatever is your secret phrase, give anything here";
}
sub _intto64 { #a MIME64 type encoding
my $c=shift;
$c &=0x3F;
if($c<10){ return chr(48+$c); }
if($c<10+26){ return chr($c-10+65); }
if($c<10+26+26){ return chr($c-10-26+97); }
if($c==62){ return '_'; }
return '-';
}
sub _encode64 { #encoding three bytes to four chars
my($a,$b,$c)=@_;
$a &= 0xFF; $b &= 0xFF; $c &= 0xFF;
return _intto64($a>>2)._intto64(($a<<4)|($b>>4)).
_intto64(($b<<2)|($c>>6))._intto64($c);
}
sub _from64 { #decoding of the above
my $c=ord(shift||"0");
if($c==95){ return 62;}
if($c==45){ return 63;}
if($c<48+10){ return $c-48; }
if($c<65+26){ return $c-65+10; }
return $c-97+10+26;
}
sub _decode64 { # decoding four chars to three bytes
my($s)=shift;
my ($r1,$r2,$r3,$r4)=(
_from64($s),_from64(substr($s,1)),
_from64(substr($s,2)),_from64(substr($s,3)));
return ($r1<<18)|($r2<<12)|($r3<<6)|$r4;
}
sub _EncodeValue { ## encoded value should not end in a space
my($id) = @_;
use Digest::MD5;
my $salt=substr(Digest::MD5::md5_hex($id, _secret()),0,8);
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0; my $ssid="";
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed); my $idlen=length($id);
$id .= " "; # pad message by spaces
for(my $i=0;$i<$idlen;$i+=3){
#encode $id[0],$id[1],$id[2] as 4 chars
my $v=rand(0x1000000);
$ssid .= _encode64(ord(substr($id,$i))^($v>>16),
ord(substr($id,$i+1))^($v>>8),
ord(substr($id,$i+2))^$v);
}
return $salt.$ssid;
}
sub _DecodeValue {
my($s)=@_;
use Digest::MD5;
my($salt,$ssid)=(substr($s,0,8),substr($s,8));
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0;
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed);
my $id="";
for(my $i=0;$i<length($ssid)-3;$i+=4){
#decode next four chars
my $v=rand(0x1000000)^_decode64(substr($ssid,$i));
$id .= chr($v>>16) . chr(0xff&($v>>8)) . chr(0xff&$v);
}
$id =~ s/ +$//; ## strip spaces at the end
# $salt and $chksum should be equal
$id="" if ($salt ne substr(Digest::MD5::md5_hex($id, _secret()),0,8));
return $id;
}
'''Remarks:'''
*The MIME64-like encoding uses letters (both lower and upper case), digits and the characters - (minus) and _ (underscore). These are safe to use in an URL.
*Both encoding and decoding uses MD5 as the building block. The first eight characters of the ciphertext (encoded string) is used for two purposes. First, it acts as a salt, namely it is added to the secret phrase to derive the seed of the random number generator; second it is used to check message integrity, namely it should match the MD5 hash of the message ''and'' the secret phrase.
*Messages to be encrypted (plaintext) should not end by a space (spaces are used to pad the plaintext to have length divisible by three)
*The encryption is deterministic. Such a scheme is insecure in general. In our case, however, the plaintext contains a timestamp, thus - supposedly - the same message is never encrypted twice.
*Weak points of the scheme: only 32 bit MAC (and seed) value, and relying on perl's pseudorandom function.

==Patching Apache::Login==
We are making two changes to the ''perl_lib/EPrints/Apache/Login.pm'' module. First, always store the URI of the referring page in the hidden ''target'' variable. Second, set the address of the login page to the value of the configuration variable ''external_login_address'' whenever it is defined.

The instructions below are for Eprints version 1.3.1. Locate the line
my $form = $session->render_form( "POST" );
in the above module (it should be line 122). Replace it by the following:
##CSL Always use the "target" variable, and
## redirect to "external_login_address"
my $target = $session->param( "target" );
if(! defined($target) ){
$target = $session->get_uri;
}
my $form = $session->render_form(
"POST",
$session->get_repository->get_conf("external_login_address") );
If ''external_login_address'' is not defined, it has the same effect as the old code.
Roll down to line 142 and comment out this line (add # signs at the beginning):
## my $target = $session->param( "target" );
Save the file.

[[Category:Howto]]

Secure login

2009-07-27T19:01:14Z

Laci@degas.ceu.hu: /* Secure login script */

When logging into eprints, both username and password travel openly. Usually it is not a problem as eprints has its own authenticating mechanism, and stealing an eprints password gives the intruder very limited power. However when using centralized authentication (e.g., by [[LDAP]]) then protecting the password is more important. To prevent sniffing login pages usually use secure connection. Here we discuss an easy way to set up eprints to use encoded password traffic.

__TOC__

==The idea==

Change the destination of the eprints login page to a secure host. On the secure host a script receives the data: login name and password (and maybe others), encodes it, and forwards the request with the encrypted data as payload to an unencrypted eprints page. The eprints page decrypts the data and uses it for authentication.

===Requirements===
You need a ''secure http server'' on the same main domain as your your eprints server. For example, if eprints can be reached on the web address ''<nowiki>http://eprints.umb.edu</nowiki>'', then the secure server must have domain name ending with ''umb.edu'', for example ''<nowiki>https://secure.umb.edu</nowiki>.

You should set up a cgi executable directory on the secure host. The apache config extract below does exactly this so that ''<nowiki>https://secure.umb.edu/eprints/whatever</nowiki>'' requests the script ''/opt/cgi-bin/eprints/whatever'' to be executed:
<VirtualHost *:443>
DocumentRoot "/opt/secure"
SSLEngine on
ScriptAlias /eprints/ /opt/cgi-bin/eprints/
<Directory "/opt/cgi-bin/eprints">
AllowOverride None
Options +ExecCGI -MultiView +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Copy the [[#Secure login script|Secure login script]] below into the ''/opt/cgi-bin/eprints/'' directory (or whatever directory you've set up above); copy the [[#Receive data script|receive data script]] into eprints' ''/cgi/'' directory.

Finally [[#Patching Apache::Login |patch the Apache::Login module]] of eprints so that everything works smoothly.

===Caveats===
The login process now works as follows.
# when a page requires authentication, it creates a "login page" with destination at the secure web site
# the "login page" is sent encrypted to the secure site
# the secure site encrypts the payload, and redirects the browser to an unencrypted eprints page ''receive_data''
# ''receive_data'' decrypts the payload, checks credentials, logs in the user if everything checks, and then redirects the browser to the originating page.

What is lost in this process of two redirects is the error message when authentication fails. ''Receive_data'' cannot display the error message as its URL should not be displayed on the user's screen. The final page - which is the original one as well - cannot distinguish between an unsuccessful login and a reload, thus cannot display the error message as well. ''C'est la vie''.

The encrypted data the ''receive_data'' page receives can be a replay of a sniffed older communication. Thus this data should contain a timestamp and checked to be recent.

The secure site can also check the credentials, and relay the result only. Interestingly, the result should be sent encrypted, as otherwise the secure site could be used as an oracle to tell whether the password is correct or not (ideal for a [http://en.wikipedia.org/wiki/Dictionary_attack dictionary attack]).

==Secure login script==
This script receives the login page over a secure connection. It encrypts the username, password, and other arguments, and relocates the page to eprints' ''receive_data'' page.

Using the secure site configuration above, this script should be copied to ''/opt/cgi-bin/eprints/login'' after changing the address to your own eprint server. And, of course, the script must be executable by the apache process.

##!/usr/bin/perl -w
## secure login script for eprints
## encrypt and automatically forward to /eprints
## Author: Laszlo Csirmaz, 2009
## You are free to use this script
use strict;
sub _RelocateTo {
my $arg=shift;
## CHANGE THIS ADDRESS TO YOUR EPRINT SERRVER'S
"<nowiki>http://eprints.umb.edu/cgi/receive_data?Q=$arg</nowiki>";
}
<nowiki><-- COPY THE CRYPTO ROUTINES HERE --></nowiki>
sub _html2ascii {
my $v=shift;
$v="" if(! defined $v);
$v=~ tr/+/ /;
$v=~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
return $v;
}
my $P={};
my $ct=$ENV{'CONTENT_TYPE');
if($ct && $ct =~ /multipart/i ){
use CGI qw( :cgi :form );
my $req=new CGI; # read all data in
my @pm=$req->param;
foreach my $key (@pm) {
$P->{$key} = _html2ascii($req->param($ley));
}
} elsif ( $ENV{'REQUEST_METHOD'} !~ /^get/i ) {
my $pm=""; while(<>){ $pm .= $_; }
my @pms=split(/&/,$pm);
foreach my $elem(@pms) {
my($t,$v)=split(/=/,$elem);
next if(! defined($t) );
$P->{_html2ascii($t)} = _html2ascii($v);
}
}
## we return the following arguments:
## target, loginparams, username, pw, timestamp
my $arg="";
for my $item ($P->{target},$P->{loginparams},
$P->{login_username}, $P->{login_password} ){
$item="" if(! $item)[
# replace '%' by '%a' and replace ':' by '%c'
$item =~ s/%/%a/g; $item =~ s/:/%c/g;
$arg .= "$item:";
}
my $addr = _RelocateTo( _EncodeValue( $arg . int(time/60) ) );
print "Content-Type: text/html; charset=utf-8\n",
"Location: $addr\n",
"\n",
"<html><head><title>Redirected</title></head>\n",
"<body>\n",
"This page should automatically relocated. If not,\n",
"please <a href=\"$addr\">click here</a>.\n",
"</body>\n",
"</html>\n",
"\n";
exit 0;

==Receive data script==
This script receives the encrypted data from the secure server, decrypts it and logs in the user. A 1 second delay is inserted if there is a problem with the credentials.

This script should be copied to the ''eprints/cgi/receive_data''. It calls the ''check_user_password'' configuration procedure if it is defined.
######################################################
# receive_data
# Part of EPrints 3.1
# Author: Laszlo Csirmaz
# You are free to use/modify this script
######################################################
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );
my $redirect_to="/cgi/users/home";
my $loginparams="";
my $OK=1;
my $arg = $session->param('Q');
if( $arg && length($arg) > 10 ){ #sanity check
$arg = _DecodeValue($arg);
## it is target:loginparams:uname:pw:timenow
$arg = "/cgi/users/home::::" if(!$arg);
my @list = split(/:/,$arg);
for my $i(0..4){
$list[$i]="" if(!$list[$i]);
$list[$i] =~ s/%c/:/g; $list[$i] =~ s/%a/%/g;
}
$OK=0 if( $list[4] !~ /^\d$/ );
if($OK){
my $timediff = int(time/60) - $list[4];
#allow a 2 minute window
$OK=0 if( $timediff<-1 || $timediff > 2 );
}
$redirect_to = $list[0] if($list[0] =~ m#/# );
$loginparams = $list[1];
if($OK){
if( $session->valid_login($list[2],$list[3] ) ){
my $user = EPrints::DataObj::User::user_with_username(
$session,$list[2]);
$session->login($user);
$OK=2;
}
}
}
sleep 1 if( $OK != 2 ); # some problem, don't hurry
my $host = $session->{repository}->get_conf( "host" );
my $port = $session->{repository}->get_conf( "port" );
$redirect_to = "<nowiki>http://$host</nowiki>".($port!=80 :":$port":""). $redirect_to;
$redirect_to .= "?$loginparams" if($loginparams);
$session->redirect( $redirect_to );
$session->terminate;
exit 0;
<nowiki></nowiki>
While we made a lot of effort to protect the integrity and secrecy of the username and the data, nothing prevents a bad guy to submit bogus data to our secure script! Thus we relocate to the eprints repository addresses only, and accept the "relocate" argument only if it starts with a slash.

==Crypto routines==
These routines perform encryption and decryption. It is a lightweight version of more sophisticated ones, but (at least I hope) it is sufficient for this application. After the source there are some remarks for those interested.

<div style="padding:4px; background-color: #ffe0e0;border:1px solid #a06060;">'''Warning!''' The secret phrase in the second line should be changed to some secret value. And it should be the same in both copies.</div>
sub _secret {
"Whatever is your secret phrase, give anything here";
}
sub _intto64 { #a MIME64 type encoding
my $c=shift;
$c &=0x3F;
if($c<10){ return chr(48+$c); }
if($c<10+26){ return chr($c-10+65); }
if($c<10+26+26){ return chr($c-10-26+97); }
if($c==62){ return '_'; }
return '-';
}
sub _encode64 { #encoding three bytes to four chars
my($a,$b,$c)=@_;
$a &= 0xFF; $b &= 0xFF; $c &= 0xFF;
return _intto64($a>>2)._intto64(($a<<4)|($b>>4)).
_intto64(($b<<2)|($c>>6))._intto64($c);
}
sub _from64 { #decoding of the above
my $c=ord(shift||"0");
if($c==95){ return 62;}
if($c==45){ return 63;}
if($c<48+10){ return $c-48; }
if($c<65+26){ return $c-65+10; }
return $c-97+10+26;
}
sub _decode64 { # decoding four chars to three bytes
my($s)=shift;
my ($r1,$r2,$r3,$r4)=(
_from64($s),_from64(substr($s,1)),
_from64(substr($s,2)),_from64(substr($s,3)));
return ($r1<<18)|($r2<<12)|($r3<<6)|$r4;
}
sub _EncodeValue { ## encoded value should not end in a space
my($id) = @_;
use Digest::MD5;
my $salt=substr(Digest::MD5::md5_hex($id, _secret()),0,8);
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0; my $ssid="";
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed); my $idlen=length($id);
$id .= " "; # pad message by spaces
for(my $i=0;$i<$idlen;$i+=3){
#encode $id[0],$id[1],$id[2] as 4 chars
my $v=rand(0x1000000);
$ssid .= _encode64(ord(substr($id,$i))^($v>>16),
ord(substr($id,$i+1))^($v>>8),
ord(substr($id,$i+2))^$v);
}
return $salt.$ssid;
}
sub _DecodeValue {
my($s)=@_;
use Digest::MD5;
my($salt,$ssid)=(substr($s,0,8),substr($s,8));
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0;
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed);
my $id="";
for(my $i=0;$i<length($ssid)-3;$i+=4){
#decode next four chars
my $v=rand(0x1000000)^_decode64(substr($ssid,$i));
$id .= chr($v>>16) . chr(0xff&($v>>8)) . chr(0xff&$v);
}
$id =~ s/ +$//; ## strip spaces at the end
# $salt and $chksum should be equal
$id="" if ($salt ne substr(Digest::MD5::md5_hex($id, _secret()),0,8));
return $id;
}
'''Remarks:'''
*The MIME64-like encoding uses letters (both lower and upper case), digits and the characters - (minus) and _ (underscore). These are safe to use in an URL.
*Both encoding and decoding uses MD5 as the building block. The first eight characters of the ciphertext (encoded string) is used for two purposes. First, it acts as a salt, namely it is added to the secret phrase to derive the seed of the random number generator; second it is used to check message integrity, namely it should match the MD5 hash of the message ''and'' the secret phrase.
*Messages to be encrypted (plaintext) should not end by a space (spaces are used to pad the plaintext to have length divisible by three)
*The encryption is deterministic. Such a scheme is insecure in general. In our case, however, the plaintext contains a timestamp, thus - supposedly - the same message is never encrypted twice.
*Weak points of the scheme: only 32 bit MAC (and seed) value, and relying on perl's pseudorandom function.

==Patching Apache::Login==

[[Category:Howto]]

Secure login

2009-07-27T19:00:07Z

Laci@degas.ceu.hu: /* Secure login script */

When logging into eprints, both username and password travel openly. Usually it is not a problem as eprints has its own authenticating mechanism, and stealing an eprints password gives the intruder very limited power. However when using centralized authentication (e.g., by [[LDAP]]) then protecting the password is more important. To prevent sniffing login pages usually use secure connection. Here we discuss an easy way to set up eprints to use encoded password traffic.

__TOC__

==The idea==

Change the destination of the eprints login page to a secure host. On the secure host a script receives the data: login name and password (and maybe others), encodes it, and forwards the request with the encrypted data as payload to an unencrypted eprints page. The eprints page decrypts the data and uses it for authentication.

===Requirements===
You need a ''secure http server'' on the same main domain as your your eprints server. For example, if eprints can be reached on the web address ''<nowiki>http://eprints.umb.edu</nowiki>'', then the secure server must have domain name ending with ''umb.edu'', for example ''<nowiki>https://secure.umb.edu</nowiki>.

You should set up a cgi executable directory on the secure host. The apache config extract below does exactly this so that ''<nowiki>https://secure.umb.edu/eprints/whatever</nowiki>'' requests the script ''/opt/cgi-bin/eprints/whatever'' to be executed:
<VirtualHost *:443>
DocumentRoot "/opt/secure"
SSLEngine on
ScriptAlias /eprints/ /opt/cgi-bin/eprints/
<Directory "/opt/cgi-bin/eprints">
AllowOverride None
Options +ExecCGI -MultiView +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Copy the [[#Secure login script|Secure login script]] below into the ''/opt/cgi-bin/eprints/'' directory (or whatever directory you've set up above); copy the [[#Receive data script|receive data script]] into eprints' ''/cgi/'' directory.

Finally [[#Patching Apache::Login |patch the Apache::Login module]] of eprints so that everything works smoothly.

===Caveats===
The login process now works as follows.
# when a page requires authentication, it creates a "login page" with destination at the secure web site
# the "login page" is sent encrypted to the secure site
# the secure site encrypts the payload, and redirects the browser to an unencrypted eprints page ''receive_data''
# ''receive_data'' decrypts the payload, checks credentials, logs in the user if everything checks, and then redirects the browser to the originating page.

What is lost in this process of two redirects is the error message when authentication fails. ''Receive_data'' cannot display the error message as its URL should not be displayed on the user's screen. The final page - which is the original one as well - cannot distinguish between an unsuccessful login and a reload, thus cannot display the error message as well. ''C'est la vie''.

The encrypted data the ''receive_data'' page receives can be a replay of a sniffed older communication. Thus this data should contain a timestamp and checked to be recent.

The secure site can also check the credentials, and relay the result only. Interestingly, the result should be sent encrypted, as otherwise the secure site could be used as an oracle to tell whether the password is correct or not (ideal for a [http://en.wikipedia.org/wiki/Dictionary_attack dictionary attack]).

==Secure login script==
This script receives the login page over a secure connection. It encrypts the username, password, and other arguments, and relocates the page to eprints' ''receive_data'' page.

Using the secure site configuration above, this script should be copied to ''/opt/cgi-bin/eprints/login'' after changing the address to your own eprint server. And, of course, the script must be executable by the apache process.

##!/usr/bin/perl -w
## secure login script for eprints
## encrypt and automatically forward to /eprints
## Author: Laszlo Csirmaz, 2009
## You are free to use this script
use strict;
sub _RelocateTo {
my $arg=shift;
"<nowiki>http://eprints.umb.edu/cgi/receive_data?Q=$arg</nowiki>";
}
<nowiki><-- COPY THE CRYPTO ROUTINES HERE --></nowiki>
sub _html2ascii {
my $v=shift;
$v="" if(! defined $v);
$v=~ tr/+/ /;
$v=~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
return $v;
}
my $P={};
my $ct=$ENV{'CONTENT_TYPE');
if($ct && $ct =~ /multipart/i ){
use CGI qw( :cgi :form );
my $req=new CGI; # read all data in
my @pm=$req->param;
foreach my $key (@pm) {
$P->{$key} = _html2ascii($req->param($ley));
}
} elsif ( $ENV{'REQUEST_METHOD'} !~ /^get/i ) {
my $pm=""; while(<>){ $pm .= $_; }
my @pms=split(/&/,$pm);
foreach my $elem(@pms) {
my($t,$v)=split(/=/,$elem);
next if(! defined($t) );
$P->{_html2ascii($t)} = _html2ascii($v);
}
}
## we return the following arguments:
## target, loginparams, username, pw, timestamp
my $arg="";
for my $item ($P->{target},$P->{loginparams},
$P->{login_username}, $P->{login_password} ){
$item="" if(! $item)[
# replace '%' by '%a' and replace ':' by '%c'
$item =~ s/%/%a/g; $item =~ s/:/%c/g;
$arg .= "$item:";
}
my $addr = _RelocateTo( _EncodeValue( $arg . int(time/60) ) );
print "Content-Type: text/html; charset=utf-8\n",
"Location: $addr\n",
"\n",
"<html><head><title>Redirected</title></head>\n",
"<body>\n",
"This page should automatically relocated. If not,\n",
"please <a href=\"$addr\">click here</a>.\n",
"</body>\n",
"</html>\n",
"\n";
exit 0;

==Receive data script==
This script receives the encrypted data from the secure server, decrypts it and logs in the user. A 1 second delay is inserted if there is a problem with the credentials.

This script should be copied to the ''eprints/cgi/receive_data''. It calls the ''check_user_password'' configuration procedure if it is defined.
######################################################
# receive_data
# Part of EPrints 3.1
# Author: Laszlo Csirmaz
# You are free to use/modify this script
######################################################
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );
my $redirect_to="/cgi/users/home";
my $loginparams="";
my $OK=1;
my $arg = $session->param('Q');
if( $arg && length($arg) > 10 ){ #sanity check
$arg = _DecodeValue($arg);
## it is target:loginparams:uname:pw:timenow
$arg = "/cgi/users/home::::" if(!$arg);
my @list = split(/:/,$arg);
for my $i(0..4){
$list[$i]="" if(!$list[$i]);
$list[$i] =~ s/%c/:/g; $list[$i] =~ s/%a/%/g;
}
$OK=0 if( $list[4] !~ /^\d$/ );
if($OK){
my $timediff = int(time/60) - $list[4];
#allow a 2 minute window
$OK=0 if( $timediff<-1 || $timediff > 2 );
}
$redirect_to = $list[0] if($list[0] =~ m#/# );
$loginparams = $list[1];
if($OK){
if( $session->valid_login($list[2],$list[3] ) ){
my $user = EPrints::DataObj::User::user_with_username(
$session,$list[2]);
$session->login($user);
$OK=2;
}
}
}
sleep 1 if( $OK != 2 ); # some problem, don't hurry
my $host = $session->{repository}->get_conf( "host" );
my $port = $session->{repository}->get_conf( "port" );
$redirect_to = "<nowiki>http://$host</nowiki>".($port!=80 :":$port":""). $redirect_to;
$redirect_to .= "?$loginparams" if($loginparams);
$session->redirect( $redirect_to );
$session->terminate;
exit 0;
<nowiki></nowiki>
While we made a lot of effort to protect the integrity and secrecy of the username and the data, nothing prevents a bad guy to submit bogus data to our secure script! Thus we relocate to the eprints repository addresses only, and accept the "relocate" argument only if it starts with a slash.

==Crypto routines==
These routines perform encryption and decryption. It is a lightweight version of more sophisticated ones, but (at least I hope) it is sufficient for this application. After the source there are some remarks for those interested.

<div style="padding:4px; background-color: #ffe0e0;border:1px solid #a06060;">'''Warning!''' The secret phrase in the second line should be changed to some secret value. And it should be the same in both copies.</div>
sub _secret {
"Whatever is your secret phrase, give anything here";
}
sub _intto64 { #a MIME64 type encoding
my $c=shift;
$c &=0x3F;
if($c<10){ return chr(48+$c); }
if($c<10+26){ return chr($c-10+65); }
if($c<10+26+26){ return chr($c-10-26+97); }
if($c==62){ return '_'; }
return '-';
}
sub _encode64 { #encoding three bytes to four chars
my($a,$b,$c)=@_;
$a &= 0xFF; $b &= 0xFF; $c &= 0xFF;
return _intto64($a>>2)._intto64(($a<<4)|($b>>4)).
_intto64(($b<<2)|($c>>6))._intto64($c);
}
sub _from64 { #decoding of the above
my $c=ord(shift||"0");
if($c==95){ return 62;}
if($c==45){ return 63;}
if($c<48+10){ return $c-48; }
if($c<65+26){ return $c-65+10; }
return $c-97+10+26;
}
sub _decode64 { # decoding four chars to three bytes
my($s)=shift;
my ($r1,$r2,$r3,$r4)=(
_from64($s),_from64(substr($s,1)),
_from64(substr($s,2)),_from64(substr($s,3)));
return ($r1<<18)|($r2<<12)|($r3<<6)|$r4;
}
sub _EncodeValue { ## encoded value should not end in a space
my($id) = @_;
use Digest::MD5;
my $salt=substr(Digest::MD5::md5_hex($id, _secret()),0,8);
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0; my $ssid="";
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed); my $idlen=length($id);
$id .= " "; # pad message by spaces
for(my $i=0;$i<$idlen;$i+=3){
#encode $id[0],$id[1],$id[2] as 4 chars
my $v=rand(0x1000000);
$ssid .= _encode64(ord(substr($id,$i))^($v>>16),
ord(substr($id,$i+1))^($v>>8),
ord(substr($id,$i+2))^$v);
}
return $salt.$ssid;
}
sub _DecodeValue {
my($s)=@_;
use Digest::MD5;
my($salt,$ssid)=(substr($s,0,8),substr($s,8));
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0;
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed);
my $id="";
for(my $i=0;$i<length($ssid)-3;$i+=4){
#decode next four chars
my $v=rand(0x1000000)^_decode64(substr($ssid,$i));
$id .= chr($v>>16) . chr(0xff&($v>>8)) . chr(0xff&$v);
}
$id =~ s/ +$//; ## strip spaces at the end
# $salt and $chksum should be equal
$id="" if ($salt ne substr(Digest::MD5::md5_hex($id, _secret()),0,8));
return $id;
}
'''Remarks:'''
*The MIME64-like encoding uses letters (both lower and upper case), digits and the characters - (minus) and _ (underscore). These are safe to use in an URL.
*Both encoding and decoding uses MD5 as the building block. The first eight characters of the ciphertext (encoded string) is used for two purposes. First, it acts as a salt, namely it is added to the secret phrase to derive the seed of the random number generator; second it is used to check message integrity, namely it should match the MD5 hash of the message ''and'' the secret phrase.
*Messages to be encrypted (plaintext) should not end by a space (spaces are used to pad the plaintext to have length divisible by three)
*The encryption is deterministic. Such a scheme is insecure in general. In our case, however, the plaintext contains a timestamp, thus - supposedly - the same message is never encrypted twice.
*Weak points of the scheme: only 32 bit MAC (and seed) value, and relying on perl's pseudorandom function.

==Patching Apache::Login==

[[Category:Howto]]

Category:Howto

2009-07-27T18:57:48Z

Laci@degas.ceu.hu: /* User Accounts */

== User Accounts ==

* [[LDAP]]
** slightly more complex [[LDAP user login.pl]] example with account auto-creation
* [[Removing User Registration]]
* [[CAS|How to use a CAS server to authenticate users in eprints]]
* [[Secure login|Light weight secure login]]

== Eprints config (global) ==

* [[setting up email]]

== Eprints archive config ==

* [[How to Create Cover Images in EPrints 3]]
* [[HOW TO: Add a New Field|How to add a New Field]]
* [[Add a parallel authentication routine]]. This is a real-world example, which alters the user table, over-rides the default methods for fields, and makes changes to the way a user is authenticated
* [[Adding a Field to a Live Repository]]
* [[How to add the structure of an organisation]]

== Migration and Importing ==

* [[Importing from Endnote]]
* [[How to import users from another archive and keep their passwords]]

== Development Environment ==

* [[EclipseEpicPerlDebug|How to set up EPrints in Eclipse using EPIC and the Perl Debugger]]

== User Interface ==

* [[Web Interface Style and Images]]
* [[GUI Submission with no Documents]]
* [[Browse By Person]]
* [[Adding a link to the Front Page]]
* [[Contact and Information Pages]]

Secure login

2009-07-27T16:40:13Z

Laci@degas.ceu.hu: /* Crypto routines */

When logging into eprints, both username and password travel openly. Usually it is not a problem as eprints has its own authenticating mechanism, and stealing an eprints password gives the intruder very limited power. However when using centralized authentication (e.g., by [[LDAP]]) then protecting the password is more important. To prevent sniffing login pages usually use secure connection. Here we discuss an easy way to set up eprints to use encoded password traffic.

__TOC__

==The idea==

Change the destination of the eprints login page to a secure host. On the secure host a script receives the data: login name and password (and maybe others), encodes it, and forwards the request with the encrypted data as payload to an unencrypted eprints page. The eprints page decrypts the data and uses it for authentication.

===Requirements===
You need a ''secure http server'' on the same main domain as your your eprints server. For example, if eprints can be reached on the web address ''<nowiki>http://eprints.umb.edu</nowiki>'', then the secure server must have domain name ending with ''umb.edu'', for example ''<nowiki>https://secure.umb.edu</nowiki>.

You should set up a cgi executable directory on the secure host. The apache config extract below does exactly this so that ''<nowiki>https://secure.umb.edu/eprints/whatever</nowiki>'' requests the script ''/opt/cgi-bin/eprints/whatever'' to be executed:
<VirtualHost *:443>
DocumentRoot "/opt/secure"
SSLEngine on
ScriptAlias /eprints/ /opt/cgi-bin/eprints/
<Directory "/opt/cgi-bin/eprints">
AllowOverride None
Options +ExecCGI -MultiView +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Copy the [[#Secure login script|Secure login script]] below into the ''/opt/cgi-bin/eprints/'' directory (or whatever directory you've set up above); copy the [[#Receive data script|receive data script]] into eprints' ''/cgi/'' directory.

Finally [[#Patching Apache::Login |patch the Apache::Login module]] of eprints so that everything works smoothly.

===Caveats===
The login process now works as follows.
# when a page requires authentication, it creates a "login page" with destination at the secure web site
# the "login page" is sent encrypted to the secure site
# the secure site encrypts the payload, and redirects the browser to an unencrypted eprints page ''receive_data''
# ''receive_data'' decrypts the payload, checks credentials, logs in the user if everything checks, and then redirects the browser to the originating page.

What is lost in this process of two redirects is the error message when authentication fails. ''Receive_data'' cannot display the error message as its URL should not be displayed on the user's screen. The final page - which is the original one as well - cannot distinguish between an unsuccessful login and a reload, thus cannot display the error message as well. ''C'est la vie''.

The encrypted data the ''receive_data'' page receives can be a replay of a sniffed older communication. Thus this data should contain a timestamp and checked to be recent.

The secure site can also check the credentials, and relay the result only. Interestingly, the result should be sent encrypted, as otherwise the secure site could be used as an oracle to tell whether the password is correct or not (ideal for a [http://en.wikipedia.org/wiki/Dictionary_attack dictionary attack]).

==Secure login script==
This script receives the login page over a secure connection. It encrypts the username, password, and other arguments, and relocates the page to eprints' ''receive_data'' page.

Using the secure site configuration above, this script should be copied to ''/opt/cgi-bin/eprints/login'' after changing the address to your own eprint server.

##!/usr/bin/perl -w
## secure login script for eprints
## encrypt and automatically forward to /eprints
## Author: Laszlo Csirmaz, 2009
## You are free to use this script
use strict;
sub _RelocateTo {
my $arg=shift;
"<nowiki>http://eprints.umb.edu/cgi/receive_data?Q=$arg</nowiki>";
}
<nowiki><-- COPY THE CRYPTO ROUTINES HERE --></nowiki>
sub _html2ascii {
my $v=shift;
$v="" if(! defined $v);
$v=~ tr/+/ /;
$v=~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
return $v;
}
my $P={};
my $ct=$ENV{'CONTENT_TYPE');
if($ct && $ct =~ /multipart/i ){
use CGI qw( :cgi :form );
my $req=new CGI; # read all data in
my @pm=$req->param;
foreach my $key (@pm) {
$P->{$key} = _html2ascii($req->param($ley));
}
} elsif ( $ENV{'REQUEST_METHOD'} !~ /^get/i ) {
my $pm=""; while(<>){ $pm .= $_; }
my @pms=split(/&/,$pm);
foreach my $elem(@pms) {
my($t,$v)=split(/=/,$elem);
next if(! defined($t) );
$P->{_html2ascii($t)} = _html2ascii($v);
}
}
## we return the following arguments:
## target, loginparams, username, pw, timestamp
my $arg="";
for my $item ($P->{target},$P->{loginparams},
$P->{login_username}, $P->{login_password} ){
$item="" if(! $item)[
# replace '%' by '%a' and replace ':' by '%c'
$item =~ s/%/%a/g; $item =~ s/:/%c/g;
$arg .= "$item:";
}
my $addr = _RelocateTo( _EncodeValue( $arg . int(time/60) ) );
print "Content-Type: text/html; charset=utf-8\n",
"Location: $addr\n",
"\n",
"<html><head><title>Redirected</title></head>\n",
"<body>\n",
"This page should automatically relocated. If not,\n",
"please <a href=\"$addr\">click here</a>.\n",
"</body>\n",
"</html>\n",
"\n";
exit 0;

==Receive data script==
This script receives the encrypted data from the secure server, decrypts it and logs in the user. A 1 second delay is inserted if there is a problem with the credentials.

This script should be copied to the ''eprints/cgi/receive_data''. It calls the ''check_user_password'' configuration procedure if it is defined.
######################################################
# receive_data
# Part of EPrints 3.1
# Author: Laszlo Csirmaz
# You are free to use/modify this script
######################################################
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );
my $redirect_to="/cgi/users/home";
my $loginparams="";
my $OK=1;
my $arg = $session->param('Q');
if( $arg && length($arg) > 10 ){ #sanity check
$arg = _DecodeValue($arg);
## it is target:loginparams:uname:pw:timenow
$arg = "/cgi/users/home::::" if(!$arg);
my @list = split(/:/,$arg);
for my $i(0..4){
$list[$i]="" if(!$list[$i]);
$list[$i] =~ s/%c/:/g; $list[$i] =~ s/%a/%/g;
}
$OK=0 if( $list[4] !~ /^\d$/ );
if($OK){
my $timediff = int(time/60) - $list[4];
#allow a 2 minute window
$OK=0 if( $timediff<-1 || $timediff > 2 );
}
$redirect_to = $list[0] if($list[0] =~ m#/# );
$loginparams = $list[1];
if($OK){
if( $session->valid_login($list[2],$list[3] ) ){
my $user = EPrints::DataObj::User::user_with_username(
$session,$list[2]);
$session->login($user);
$OK=2;
}
}
}
sleep 1 if( $OK != 2 ); # some problem, don't hurry
my $host = $session->{repository}->get_conf( "host" );
my $port = $session->{repository}->get_conf( "port" );
$redirect_to = "<nowiki>http://$host</nowiki>".($port!=80 :":$port":""). $redirect_to;
$redirect_to .= "?$loginparams" if($loginparams);
$session->redirect( $redirect_to );
$session->terminate;
exit 0;
<nowiki></nowiki>
While we made a lot of effort to protect the integrity and secrecy of the username and the data, nothing prevents a bad guy to submit bogus data to our secure script! Thus we relocate to the eprints repository addresses only, and accept the "relocate" argument only if it starts with a slash.

==Crypto routines==
These routines perform encryption and decryption. It is a lightweight version of more sophisticated ones, but (at least I hope) it is sufficient for this application. After the source there are some remarks for those interested.

<div style="padding:4px; background-color: #ffe0e0;border:1px solid #a06060;">'''Warning!''' The secret phrase in the second line should be changed to some secret value. And it should be the same in both copies.</div>
sub _secret {
"Whatever is your secret phrase, give anything here";
}
sub _intto64 { #a MIME64 type encoding
my $c=shift;
$c &=0x3F;
if($c<10){ return chr(48+$c); }
if($c<10+26){ return chr($c-10+65); }
if($c<10+26+26){ return chr($c-10-26+97); }
if($c==62){ return '_'; }
return '-';
}
sub _encode64 { #encoding three bytes to four chars
my($a,$b,$c)=@_;
$a &= 0xFF; $b &= 0xFF; $c &= 0xFF;
return _intto64($a>>2)._intto64(($a<<4)|($b>>4)).
_intto64(($b<<2)|($c>>6))._intto64($c);
}
sub _from64 { #decoding of the above
my $c=ord(shift||"0");
if($c==95){ return 62;}
if($c==45){ return 63;}
if($c<48+10){ return $c-48; }
if($c<65+26){ return $c-65+10; }
return $c-97+10+26;
}
sub _decode64 { # decoding four chars to three bytes
my($s)=shift;
my ($r1,$r2,$r3,$r4)=(
_from64($s),_from64(substr($s,1)),
_from64(substr($s,2)),_from64(substr($s,3)));
return ($r1<<18)|($r2<<12)|($r3<<6)|$r4;
}
sub _EncodeValue { ## encoded value should not end in a space
my($id) = @_;
use Digest::MD5;
my $salt=substr(Digest::MD5::md5_hex($id, _secret()),0,8);
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0; my $ssid="";
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed); my $idlen=length($id);
$id .= " "; # pad message by spaces
for(my $i=0;$i<$idlen;$i+=3){
#encode $id[0],$id[1],$id[2] as 4 chars
my $v=rand(0x1000000);
$ssid .= _encode64(ord(substr($id,$i))^($v>>16),
ord(substr($id,$i+1))^($v>>8),
ord(substr($id,$i+2))^$v);
}
return $salt.$ssid;
}
sub _DecodeValue {
my($s)=@_;
use Digest::MD5;
my($salt,$ssid)=(substr($s,0,8),substr($s,8));
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0;
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed);
my $id="";
for(my $i=0;$i<length($ssid)-3;$i+=4){
#decode next four chars
my $v=rand(0x1000000)^_decode64(substr($ssid,$i));
$id .= chr($v>>16) . chr(0xff&($v>>8)) . chr(0xff&$v);
}
$id =~ s/ +$//; ## strip spaces at the end
# $salt and $chksum should be equal
$id="" if ($salt ne substr(Digest::MD5::md5_hex($id, _secret()),0,8));
return $id;
}
'''Remarks:'''
*The MIME64-like encoding uses letters (both lower and upper case), digits and the characters - (minus) and _ (underscore). These are safe to use in an URL.
*Both encoding and decoding uses MD5 as the building block. The first eight characters of the ciphertext (encoded string) is used for two purposes. First, it acts as a salt, namely it is added to the secret phrase to derive the seed of the random number generator; second it is used to check message integrity, namely it should match the MD5 hash of the message ''and'' the secret phrase.
*Messages to be encrypted (plaintext) should not end by a space (spaces are used to pad the plaintext to have length divisible by three)
*The encryption is deterministic. Such a scheme is insecure in general. In our case, however, the plaintext contains a timestamp, thus - supposedly - the same message is never encrypted twice.
*Weak points of the scheme: only 32 bit MAC (and seed) value, and relying on perl's pseudorandom function.

==Patching Apache::Login==

[[Category:Howto]]

Secure login

2009-07-27T16:39:29Z

Laci@degas.ceu.hu: /* Crypto routines */

When logging into eprints, both username and password travel openly. Usually it is not a problem as eprints has its own authenticating mechanism, and stealing an eprints password gives the intruder very limited power. However when using centralized authentication (e.g., by [[LDAP]]) then protecting the password is more important. To prevent sniffing login pages usually use secure connection. Here we discuss an easy way to set up eprints to use encoded password traffic.

__TOC__

==The idea==

Change the destination of the eprints login page to a secure host. On the secure host a script receives the data: login name and password (and maybe others), encodes it, and forwards the request with the encrypted data as payload to an unencrypted eprints page. The eprints page decrypts the data and uses it for authentication.

===Requirements===
You need a ''secure http server'' on the same main domain as your your eprints server. For example, if eprints can be reached on the web address ''<nowiki>http://eprints.umb.edu</nowiki>'', then the secure server must have domain name ending with ''umb.edu'', for example ''<nowiki>https://secure.umb.edu</nowiki>.

You should set up a cgi executable directory on the secure host. The apache config extract below does exactly this so that ''<nowiki>https://secure.umb.edu/eprints/whatever</nowiki>'' requests the script ''/opt/cgi-bin/eprints/whatever'' to be executed:
<VirtualHost *:443>
DocumentRoot "/opt/secure"
SSLEngine on
ScriptAlias /eprints/ /opt/cgi-bin/eprints/
<Directory "/opt/cgi-bin/eprints">
AllowOverride None
Options +ExecCGI -MultiView +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Copy the [[#Secure login script|Secure login script]] below into the ''/opt/cgi-bin/eprints/'' directory (or whatever directory you've set up above); copy the [[#Receive data script|receive data script]] into eprints' ''/cgi/'' directory.

Finally [[#Patching Apache::Login |patch the Apache::Login module]] of eprints so that everything works smoothly.

===Caveats===
The login process now works as follows.
# when a page requires authentication, it creates a "login page" with destination at the secure web site
# the "login page" is sent encrypted to the secure site
# the secure site encrypts the payload, and redirects the browser to an unencrypted eprints page ''receive_data''
# ''receive_data'' decrypts the payload, checks credentials, logs in the user if everything checks, and then redirects the browser to the originating page.

What is lost in this process of two redirects is the error message when authentication fails. ''Receive_data'' cannot display the error message as its URL should not be displayed on the user's screen. The final page - which is the original one as well - cannot distinguish between an unsuccessful login and a reload, thus cannot display the error message as well. ''C'est la vie''.

The encrypted data the ''receive_data'' page receives can be a replay of a sniffed older communication. Thus this data should contain a timestamp and checked to be recent.

The secure site can also check the credentials, and relay the result only. Interestingly, the result should be sent encrypted, as otherwise the secure site could be used as an oracle to tell whether the password is correct or not (ideal for a [http://en.wikipedia.org/wiki/Dictionary_attack dictionary attack]).

==Secure login script==
This script receives the login page over a secure connection. It encrypts the username, password, and other arguments, and relocates the page to eprints' ''receive_data'' page.

Using the secure site configuration above, this script should be copied to ''/opt/cgi-bin/eprints/login'' after changing the address to your own eprint server.

##!/usr/bin/perl -w
## secure login script for eprints
## encrypt and automatically forward to /eprints
## Author: Laszlo Csirmaz, 2009
## You are free to use this script
use strict;
sub _RelocateTo {
my $arg=shift;
"<nowiki>http://eprints.umb.edu/cgi/receive_data?Q=$arg</nowiki>";
}
<nowiki><-- COPY THE CRYPTO ROUTINES HERE --></nowiki>
sub _html2ascii {
my $v=shift;
$v="" if(! defined $v);
$v=~ tr/+/ /;
$v=~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
return $v;
}
my $P={};
my $ct=$ENV{'CONTENT_TYPE');
if($ct && $ct =~ /multipart/i ){
use CGI qw( :cgi :form );
my $req=new CGI; # read all data in
my @pm=$req->param;
foreach my $key (@pm) {
$P->{$key} = _html2ascii($req->param($ley));
}
} elsif ( $ENV{'REQUEST_METHOD'} !~ /^get/i ) {
my $pm=""; while(<>){ $pm .= $_; }
my @pms=split(/&/,$pm);
foreach my $elem(@pms) {
my($t,$v)=split(/=/,$elem);
next if(! defined($t) );
$P->{_html2ascii($t)} = _html2ascii($v);
}
}
## we return the following arguments:
## target, loginparams, username, pw, timestamp
my $arg="";
for my $item ($P->{target},$P->{loginparams},
$P->{login_username}, $P->{login_password} ){
$item="" if(! $item)[
# replace '%' by '%a' and replace ':' by '%c'
$item =~ s/%/%a/g; $item =~ s/:/%c/g;
$arg .= "$item:";
}
my $addr = _RelocateTo( _EncodeValue( $arg . int(time/60) ) );
print "Content-Type: text/html; charset=utf-8\n",
"Location: $addr\n",
"\n",
"<html><head><title>Redirected</title></head>\n",
"<body>\n",
"This page should automatically relocated. If not,\n",
"please <a href=\"$addr\">click here</a>.\n",
"</body>\n",
"</html>\n",
"\n";
exit 0;

==Receive data script==
This script receives the encrypted data from the secure server, decrypts it and logs in the user. A 1 second delay is inserted if there is a problem with the credentials.

This script should be copied to the ''eprints/cgi/receive_data''. It calls the ''check_user_password'' configuration procedure if it is defined.
######################################################
# receive_data
# Part of EPrints 3.1
# Author: Laszlo Csirmaz
# You are free to use/modify this script
######################################################
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );
my $redirect_to="/cgi/users/home";
my $loginparams="";
my $OK=1;
my $arg = $session->param('Q');
if( $arg && length($arg) > 10 ){ #sanity check
$arg = _DecodeValue($arg);
## it is target:loginparams:uname:pw:timenow
$arg = "/cgi/users/home::::" if(!$arg);
my @list = split(/:/,$arg);
for my $i(0..4){
$list[$i]="" if(!$list[$i]);
$list[$i] =~ s/%c/:/g; $list[$i] =~ s/%a/%/g;
}
$OK=0 if( $list[4] !~ /^\d$/ );
if($OK){
my $timediff = int(time/60) - $list[4];
#allow a 2 minute window
$OK=0 if( $timediff<-1 || $timediff > 2 );
}
$redirect_to = $list[0] if($list[0] =~ m#/# );
$loginparams = $list[1];
if($OK){
if( $session->valid_login($list[2],$list[3] ) ){
my $user = EPrints::DataObj::User::user_with_username(
$session,$list[2]);
$session->login($user);
$OK=2;
}
}
}
sleep 1 if( $OK != 2 ); # some problem, don't hurry
my $host = $session->{repository}->get_conf( "host" );
my $port = $session->{repository}->get_conf( "port" );
$redirect_to = "<nowiki>http://$host</nowiki>".($port!=80 :":$port":""). $redirect_to;
$redirect_to .= "?$loginparams" if($loginparams);
$session->redirect( $redirect_to );
$session->terminate;
exit 0;
<nowiki></nowiki>
While we made a lot of effort to protect the integrity and secrecy of the username and the data, nothing prevents a bad guy to submit bogus data to our secure script! Thus we relocate to the eprints repository addresses only, and accept the "relocate" argument only if it starts with a slash.

==Crypto routines==
These routines perform encryption and decryption. It is a lightweight version of more sophisticated ones, but (at least I hope) it is sufficient for this application. After the source there are some remarks for those interested.

<div style="padding:4px; background-color: #ffe0e0;border:1px solid #a06060;">'''Warning!''' The secret phrase in the second line should be changed to some secret value.</div>
sub _secret {
"Whatever is your secret phrase, give anything here";
}
sub _intto64 { #a MIME64 type encoding
my $c=shift;
$c &=0x3F;
if($c<10){ return chr(48+$c); }
if($c<10+26){ return chr($c-10+65); }
if($c<10+26+26){ return chr($c-10-26+97); }
if($c==62){ return '_'; }
return '-';
}
sub _encode64 { #encoding three bytes to four chars
my($a,$b,$c)=@_;
$a &= 0xFF; $b &= 0xFF; $c &= 0xFF;
return _intto64($a>>2)._intto64(($a<<4)|($b>>4)).
_intto64(($b<<2)|($c>>6))._intto64($c);
}
sub _from64 { #decoding of the above
my $c=ord(shift||"0");
if($c==95){ return 62;}
if($c==45){ return 63;}
if($c<48+10){ return $c-48; }
if($c<65+26){ return $c-65+10; }
return $c-97+10+26;
}
sub _decode64 { # decoding four chars to three bytes
my($s)=shift;
my ($r1,$r2,$r3,$r4)=(
_from64($s),_from64(substr($s,1)),
_from64(substr($s,2)),_from64(substr($s,3)));
return ($r1<<18)|($r2<<12)|($r3<<6)|$r4;
}
sub _EncodeValue { ## encoded value should not end in a space
my($id) = @_;
use Digest::MD5;
my $salt=substr(Digest::MD5::md5_hex($id, _secret()),0,8);
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0; my $ssid="";
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed); my $idlen=length($id);
$id .= " "; # pad message by spaces
for(my $i=0;$i<$idlen;$i+=3){
#encode $id[0],$id[1],$id[2] as 4 chars
my $v=rand(0x1000000);
$ssid .= _encode64(ord(substr($id,$i))^($v>>16),
ord(substr($id,$i+1))^($v>>8),
ord(substr($id,$i+2))^$v);
}
return $salt.$ssid;
}
sub _DecodeValue {
my($s)=@_;
use Digest::MD5;
my($salt,$ssid)=(substr($s,0,8),substr($s,8));
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0;
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed);
my $id="";
for(my $i=0;$i<length($ssid)-3;$i+=4){
#decode next four chars
my $v=rand(0x1000000)^_decode64(substr($ssid,$i));
$id .= chr($v>>16) . chr(0xff&($v>>8)) . chr(0xff&$v);
}
$id =~ s/ +$//; ## strip spaces at the end
# $salt and $chksum should be equal
$id="" if ($salt ne substr(Digest::MD5::md5_hex($id, _secret()),0,8));
return $id;
}
'''Remarks:'''
*The MIME64-like encoding uses letters (both lower and upper case), digits and the characters - (minus) and _ (underscore). These are safe to use in an URL.
*Both encoding and decoding uses MD5 as the building block. The first eight characters of the ciphertext (encoded string) is used for two purposes. First, it acts as a salt, namely it is added to the secret phrase to derive the seed of the random number generator; second it is used to check message integrity, namely it should match the MD5 hash of the message ''and'' the secret phrase.
*Messages to be encrypted (plaintext) should not end by a space (spaces are used to pad the plaintext to have length divisible by three)
*The encryption is deterministic. Such a scheme is insecure in general. In our case, however, the plaintext contains a timestamp, thus - supposedly - the same message is never encrypted twice.
*Weak points of the scheme: only 32 bit MAC (and seed) value, and relying on perl's pseudorandom function.

==Patching Apache::Login==

[[Category:Howto]]

Secure login

2009-07-27T16:37:30Z

Laci@degas.ceu.hu: /* Receive data script */

When logging into eprints, both username and password travel openly. Usually it is not a problem as eprints has its own authenticating mechanism, and stealing an eprints password gives the intruder very limited power. However when using centralized authentication (e.g., by [[LDAP]]) then protecting the password is more important. To prevent sniffing login pages usually use secure connection. Here we discuss an easy way to set up eprints to use encoded password traffic.

__TOC__

==The idea==

Change the destination of the eprints login page to a secure host. On the secure host a script receives the data: login name and password (and maybe others), encodes it, and forwards the request with the encrypted data as payload to an unencrypted eprints page. The eprints page decrypts the data and uses it for authentication.

===Requirements===
You need a ''secure http server'' on the same main domain as your your eprints server. For example, if eprints can be reached on the web address ''<nowiki>http://eprints.umb.edu</nowiki>'', then the secure server must have domain name ending with ''umb.edu'', for example ''<nowiki>https://secure.umb.edu</nowiki>.

You should set up a cgi executable directory on the secure host. The apache config extract below does exactly this so that ''<nowiki>https://secure.umb.edu/eprints/whatever</nowiki>'' requests the script ''/opt/cgi-bin/eprints/whatever'' to be executed:
<VirtualHost *:443>
DocumentRoot "/opt/secure"
SSLEngine on
ScriptAlias /eprints/ /opt/cgi-bin/eprints/
<Directory "/opt/cgi-bin/eprints">
AllowOverride None
Options +ExecCGI -MultiView +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Copy the [[#Secure login script|Secure login script]] below into the ''/opt/cgi-bin/eprints/'' directory (or whatever directory you've set up above); copy the [[#Receive data script|receive data script]] into eprints' ''/cgi/'' directory.

Finally [[#Patching Apache::Login |patch the Apache::Login module]] of eprints so that everything works smoothly.

===Caveats===
The login process now works as follows.
# when a page requires authentication, it creates a "login page" with destination at the secure web site
# the "login page" is sent encrypted to the secure site
# the secure site encrypts the payload, and redirects the browser to an unencrypted eprints page ''receive_data''
# ''receive_data'' decrypts the payload, checks credentials, logs in the user if everything checks, and then redirects the browser to the originating page.

What is lost in this process of two redirects is the error message when authentication fails. ''Receive_data'' cannot display the error message as its URL should not be displayed on the user's screen. The final page - which is the original one as well - cannot distinguish between an unsuccessful login and a reload, thus cannot display the error message as well. ''C'est la vie''.

The encrypted data the ''receive_data'' page receives can be a replay of a sniffed older communication. Thus this data should contain a timestamp and checked to be recent.

The secure site can also check the credentials, and relay the result only. Interestingly, the result should be sent encrypted, as otherwise the secure site could be used as an oracle to tell whether the password is correct or not (ideal for a [http://en.wikipedia.org/wiki/Dictionary_attack dictionary attack]).

==Secure login script==
This script receives the login page over a secure connection. It encrypts the username, password, and other arguments, and relocates the page to eprints' ''receive_data'' page.

Using the secure site configuration above, this script should be copied to ''/opt/cgi-bin/eprints/login'' after changing the address to your own eprint server.

##!/usr/bin/perl -w
## secure login script for eprints
## encrypt and automatically forward to /eprints
## Author: Laszlo Csirmaz, 2009
## You are free to use this script
use strict;
sub _RelocateTo {
my $arg=shift;
"<nowiki>http://eprints.umb.edu/cgi/receive_data?Q=$arg</nowiki>";
}
<nowiki><-- COPY THE CRYPTO ROUTINES HERE --></nowiki>
sub _html2ascii {
my $v=shift;
$v="" if(! defined $v);
$v=~ tr/+/ /;
$v=~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
return $v;
}
my $P={};
my $ct=$ENV{'CONTENT_TYPE');
if($ct && $ct =~ /multipart/i ){
use CGI qw( :cgi :form );
my $req=new CGI; # read all data in
my @pm=$req->param;
foreach my $key (@pm) {
$P->{$key} = _html2ascii($req->param($ley));
}
} elsif ( $ENV{'REQUEST_METHOD'} !~ /^get/i ) {
my $pm=""; while(<>){ $pm .= $_; }
my @pms=split(/&/,$pm);
foreach my $elem(@pms) {
my($t,$v)=split(/=/,$elem);
next if(! defined($t) );
$P->{_html2ascii($t)} = _html2ascii($v);
}
}
## we return the following arguments:
## target, loginparams, username, pw, timestamp
my $arg="";
for my $item ($P->{target},$P->{loginparams},
$P->{login_username}, $P->{login_password} ){
$item="" if(! $item)[
# replace '%' by '%a' and replace ':' by '%c'
$item =~ s/%/%a/g; $item =~ s/:/%c/g;
$arg .= "$item:";
}
my $addr = _RelocateTo( _EncodeValue( $arg . int(time/60) ) );
print "Content-Type: text/html; charset=utf-8\n",
"Location: $addr\n",
"\n",
"<html><head><title>Redirected</title></head>\n",
"<body>\n",
"This page should automatically relocated. If not,\n",
"please <a href=\"$addr\">click here</a>.\n",
"</body>\n",
"</html>\n",
"\n";
exit 0;

==Receive data script==
This script receives the encrypted data from the secure server, decrypts it and logs in the user. A 1 second delay is inserted if there is a problem with the credentials.

This script should be copied to the ''eprints/cgi/receive_data''. It calls the ''check_user_password'' configuration procedure if it is defined.
######################################################
# receive_data
# Part of EPrints 3.1
# Author: Laszlo Csirmaz
# You are free to use/modify this script
######################################################
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );
my $redirect_to="/cgi/users/home";
my $loginparams="";
my $OK=1;
my $arg = $session->param('Q');
if( $arg && length($arg) > 10 ){ #sanity check
$arg = _DecodeValue($arg);
## it is target:loginparams:uname:pw:timenow
$arg = "/cgi/users/home::::" if(!$arg);
my @list = split(/:/,$arg);
for my $i(0..4){
$list[$i]="" if(!$list[$i]);
$list[$i] =~ s/%c/:/g; $list[$i] =~ s/%a/%/g;
}
$OK=0 if( $list[4] !~ /^\d$/ );
if($OK){
my $timediff = int(time/60) - $list[4];
#allow a 2 minute window
$OK=0 if( $timediff<-1 || $timediff > 2 );
}
$redirect_to = $list[0] if($list[0] =~ m#/# );
$loginparams = $list[1];
if($OK){
if( $session->valid_login($list[2],$list[3] ) ){
my $user = EPrints::DataObj::User::user_with_username(
$session,$list[2]);
$session->login($user);
$OK=2;
}
}
}
sleep 1 if( $OK != 2 ); # some problem, don't hurry
my $host = $session->{repository}->get_conf( "host" );
my $port = $session->{repository}->get_conf( "port" );
$redirect_to = "<nowiki>http://$host</nowiki>".($port!=80 :":$port":""). $redirect_to;
$redirect_to .= "?$loginparams" if($loginparams);
$session->redirect( $redirect_to );
$session->terminate;
exit 0;
<nowiki></nowiki>
While we made a lot of effort to protect the integrity and secrecy of the username and the data, nothing prevents a bad guy to submit bogus data to our secure script! Thus we relocate to the eprints repository addresses only, and accept the "relocate" argument only if it starts with a slash.

==Crypto routines==
These routines perform encryption and decryption. It is a lightweight version of more sophisticated ones, but (at least I hope) it is sufficient for this application. After the source there are some remarks for those interested.

<div style="padding:4px; background-color: #ffe0e0;border:1px solid #a06060;">'''Warning!''' The secret phrase in the second line should be changed to some secret value.</div>
sub _secret {
"Whatever is your secret phrase, give anything here";
}
sub _intto64 { #a MIME64 type encoding
my $c=shift;
$c &=0x3F;
if($c<10){ return chr(48+$c); }
if($c<10+26){ return chr($c-10+65); }
if($c<10+26+26){ return chr($c-10-26+97); }
if($c==62){ return '_'; }
return '-';
}
sub _encode64 { #encoding three bytes to four chars
my($a,$b,$c)=@_;
$a &= 0xFF; $b &= 0xFF; $c &= 0xFF;
return _intto64($a>>2)._intto64(($a<<4)|($b>>4)).
_intto64(($b<<2)|($c>>6))._intto64($c);
}
sub _from64 { #decoding of the above
my $c=ord(shift||"0");
if($c==95){ return 62;}
if($c==45){ return 63;}
if($c<48+10){ return $c-48; }
if($c<65+26){ return $c-65+10; }
return $c-97+10+26;
}
sub _decode64 { # decoding four chars to three bytes
my($s)=shift;
my ($r1,$r2,$r3,$r4)=(
_from64($s),_from64(substr($s,1)),
_from64(substr($s,2)),_from64(substr($s,3)));
return ($r1<<18)|($r2<<12)|($r3<<6)|$r4;
}
sub _EncodeValue { ## encoded value should not end in a space
my($id) = @_;
use Digest::MD5;
my $salt=substr(Digest::MD5::md5_hex($id, _secret()),0,8);
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0; my $ssid="";
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed); my $idlen=length($id);
$id .= " "; # pad message by spaces
for(my $i=0;$i<$idlen;$i+=3){
#encode $id[0],$id[1],$id[2] as 4 chars
my $v=rand(0x1000000);
$ssid .= _encode64(ord(substr($id,$i))^($v>>16),
ord(substr($id,$i+1))^($v>>8),
ord(substr($id,$i+2))^$v);
}
return $salt.$ssid;
}
sub _DecodeValue {
my($s)=@_;
use Digest::MD5;
my($salt,$ssid)=(substr($s,0,8),substr($s,8));
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0;
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed);
my $id="";
for(my $i=0;$i<length($ssid)-3;$i+=4){
#decode next four chars
my $v=rand(0x1000000)^_decode64(substr($ssid,$i));
$id .= chr($v>>16) . chr(0xff&($v>>8)) . chr(0xff&$v);
}
$id =~ s/ +$//; ## strip spaces at the end
# $salt and $chksum should be equal
$id="" if ($salt ne substr(Digest::MD5::md5_hex($id, _secret()),0,8));
return $id;
}
'''Remarks:'''
*The MIME64-like encoding uses letters (both lower and upper case), digits and the characters - (minus) and _ (underscore). These are safe to use in an URL.
*Both encoding and decoding uses MD5 as the building block. The first eight characters of the ciphertext (encoded string) is used for two purposes. First, it acts as a salt, namely it is added to the secret phrase to derive the seed of the random number generator; second it is used to check message integrity, namely it should match the MD5 hash of the message ''and'' the secret phrase.
*Messages to be encrypted (plaintext) should not end by a space (spaces are used to pad the plaintext to have length divisible by three)
*The encryption is deterministic. Such a scheme is insecure in general. In our case, however, the plaintext contains a timestamp, thus - supposedly - the same message is not encrypted twice.
*Weak points of the scheme: only 32 bit MAC (and seed) value, and relying on perl's pseudorandom function.

==Patching Apache::Login==

[[Category:Howto]]

Secure login

2009-07-27T16:28:52Z

Laci@degas.ceu.hu: /* Secure login script */

When logging into eprints, both username and password travel openly. Usually it is not a problem as eprints has its own authenticating mechanism, and stealing an eprints password gives the intruder very limited power. However when using centralized authentication (e.g., by [[LDAP]]) then protecting the password is more important. To prevent sniffing login pages usually use secure connection. Here we discuss an easy way to set up eprints to use encoded password traffic.

__TOC__

==The idea==

Change the destination of the eprints login page to a secure host. On the secure host a script receives the data: login name and password (and maybe others), encodes it, and forwards the request with the encrypted data as payload to an unencrypted eprints page. The eprints page decrypts the data and uses it for authentication.

===Requirements===
You need a ''secure http server'' on the same main domain as your your eprints server. For example, if eprints can be reached on the web address ''<nowiki>http://eprints.umb.edu</nowiki>'', then the secure server must have domain name ending with ''umb.edu'', for example ''<nowiki>https://secure.umb.edu</nowiki>.

You should set up a cgi executable directory on the secure host. The apache config extract below does exactly this so that ''<nowiki>https://secure.umb.edu/eprints/whatever</nowiki>'' requests the script ''/opt/cgi-bin/eprints/whatever'' to be executed:
<VirtualHost *:443>
DocumentRoot "/opt/secure"
SSLEngine on
ScriptAlias /eprints/ /opt/cgi-bin/eprints/
<Directory "/opt/cgi-bin/eprints">
AllowOverride None
Options +ExecCGI -MultiView +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Copy the [[#Secure login script|Secure login script]] below into the ''/opt/cgi-bin/eprints/'' directory (or whatever directory you've set up above); copy the [[#Receive data script|receive data script]] into eprints' ''/cgi/'' directory.

Finally [[#Patching Apache::Login |patch the Apache::Login module]] of eprints so that everything works smoothly.

===Caveats===
The login process now works as follows.
# when a page requires authentication, it creates a "login page" with destination at the secure web site
# the "login page" is sent encrypted to the secure site
# the secure site encrypts the payload, and redirects the browser to an unencrypted eprints page ''receive_data''
# ''receive_data'' decrypts the payload, checks credentials, logs in the user if everything checks, and then redirects the browser to the originating page.

What is lost in this process of two redirects is the error message when authentication fails. ''Receive_data'' cannot display the error message as its URL should not be displayed on the user's screen. The final page - which is the original one as well - cannot distinguish between an unsuccessful login and a reload, thus cannot display the error message as well. ''C'est la vie''.

The encrypted data the ''receive_data'' page receives can be a replay of a sniffed older communication. Thus this data should contain a timestamp and checked to be recent.

The secure site can also check the credentials, and relay the result only. Interestingly, the result should be sent encrypted, as otherwise the secure site could be used as an oracle to tell whether the password is correct or not (ideal for a [http://en.wikipedia.org/wiki/Dictionary_attack dictionary attack]).

==Secure login script==
This script receives the login page over a secure connection. It encrypts the username, password, and other arguments, and relocates the page to eprints' ''receive_data'' page.

Using the secure site configuration above, this script should be copied to ''/opt/cgi-bin/eprints/login'' after changing the address to your own eprint server.

##!/usr/bin/perl -w
## secure login script for eprints
## encrypt and automatically forward to /eprints
## Author: Laszlo Csirmaz, 2009
## You are free to use this script
use strict;
sub _RelocateTo {
my $arg=shift;
"<nowiki>http://eprints.umb.edu/cgi/receive_data?Q=$arg</nowiki>";
}
<nowiki><-- COPY THE CRYPTO ROUTINES HERE --></nowiki>
sub _html2ascii {
my $v=shift;
$v="" if(! defined $v);
$v=~ tr/+/ /;
$v=~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
return $v;
}
my $P={};
my $ct=$ENV{'CONTENT_TYPE');
if($ct && $ct =~ /multipart/i ){
use CGI qw( :cgi :form );
my $req=new CGI; # read all data in
my @pm=$req->param;
foreach my $key (@pm) {
$P->{$key} = _html2ascii($req->param($ley));
}
} elsif ( $ENV{'REQUEST_METHOD'} !~ /^get/i ) {
my $pm=""; while(<>){ $pm .= $_; }
my @pms=split(/&/,$pm);
foreach my $elem(@pms) {
my($t,$v)=split(/=/,$elem);
next if(! defined($t) );
$P->{_html2ascii($t)} = _html2ascii($v);
}
}
## we return the following arguments:
## target, loginparams, username, pw, timestamp
my $arg="";
for my $item ($P->{target},$P->{loginparams},
$P->{login_username}, $P->{login_password} ){
$item="" if(! $item)[
# replace '%' by '%a' and replace ':' by '%c'
$item =~ s/%/%a/g; $item =~ s/:/%c/g;
$arg .= "$item:";
}
my $addr = _RelocateTo( _EncodeValue( $arg . int(time/60) ) );
print "Content-Type: text/html; charset=utf-8\n",
"Location: $addr\n",
"\n",
"<html><head><title>Redirected</title></head>\n",
"<body>\n",
"This page should automatically relocated. If not,\n",
"please <a href=\"$addr\">click here</a>.\n",
"</body>\n",
"</html>\n",
"\n";
exit 0;

==Receive data script==
This script receives the encrypted data from the secure server, decrypts it and logs in the user. A 1 second delay is inserted if there is a problem with the credentials.

This script should be copied to the ''eprints/cgi/receive_data''. It calls the ''check_user_password'' configuration procedure if it is defined.
######################################################
# receive_data
# Part of EPrints 3.1
# Author: Laszlo Csirmaz
# You are free to use/modify this script
######################################################
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );
my $redirect_to="/cgi/users/home";
my $loginparams="";
my $OK=1;
my $arg = $session->param('Q');
if( $arg && length($arg) > 10 ){ #sanity check
$arg = _DecodeValue($arg);
## it is target:loginparams:uname:pw:timenow
$arg = "/cgi/users/home::::" if(!$arg);
my @list = split(/:/,$arg);
for my $i(0..4){
$list[$i]="" if(!$list[$i]);
$list[$i] =~ s/%c/:/g; $list[$i] =~ s/%a/%/g;
}
$OK=0 if( $list[4] !~ /^\d$/ );
if($OK){
my $timediff = int(time/60) - $list[4];
#allow a 2 minute window
$OK=0 if( $timediff<-1 || $timediff > 2 );
}
$redirect_to = $list[0] if($list[0] =~ m#/# );
$loginparams = $list[1];
if($OK){
if( $session->valid_login($list[2],$list[3] ) ){
my $user = EPrints::DataObj::User::user_with_username(
$session,$list[2]);
$session->login($user);
$OK=2;
}
}
}
sleep 1 if( $OK != 2 ); # some problem, don't hurry
my $host = $session->{repository}->get_conf( "host" );
my $port = $session->{repository}->get_conf( "port" );
$redirect_to = "<nowiki>http://$host</nowiki>".($port!=80 :":$port":""). $redirect_to;
$redirect_to .= "?$loginparams" if($loginparams);
$session->redirect( $redirect_to );
$session->terminate;
exit 0;
<nowiki></nowiki>

==Crypto routines==
These routines perform encryption and decryption. It is a lightweight version of more sophisticated ones, but (at least I hope) it is sufficient for this application. After the source there are some remarks for those interested.

<div style="padding:4px; background-color: #ffe0e0;border:1px solid #a06060;">'''Warning!''' The secret phrase in the second line should be changed to some secret value.</div>
sub _secret {
"Whatever is your secret phrase, give anything here";
}
sub _intto64 { #a MIME64 type encoding
my $c=shift;
$c &=0x3F;
if($c<10){ return chr(48+$c); }
if($c<10+26){ return chr($c-10+65); }
if($c<10+26+26){ return chr($c-10-26+97); }
if($c==62){ return '_'; }
return '-';
}
sub _encode64 { #encoding three bytes to four chars
my($a,$b,$c)=@_;
$a &= 0xFF; $b &= 0xFF; $c &= 0xFF;
return _intto64($a>>2)._intto64(($a<<4)|($b>>4)).
_intto64(($b<<2)|($c>>6))._intto64($c);
}
sub _from64 { #decoding of the above
my $c=ord(shift||"0");
if($c==95){ return 62;}
if($c==45){ return 63;}
if($c<48+10){ return $c-48; }
if($c<65+26){ return $c-65+10; }
return $c-97+10+26;
}
sub _decode64 { # decoding four chars to three bytes
my($s)=shift;
my ($r1,$r2,$r3,$r4)=(
_from64($s),_from64(substr($s,1)),
_from64(substr($s,2)),_from64(substr($s,3)));
return ($r1<<18)|($r2<<12)|($r3<<6)|$r4;
}
sub _EncodeValue { ## encoded value should not end in a space
my($id) = @_;
use Digest::MD5;
my $salt=substr(Digest::MD5::md5_hex($id, _secret()),0,8);
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0; my $ssid="";
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed); my $idlen=length($id);
$id .= " "; # pad message by spaces
for(my $i=0;$i<$idlen;$i+=3){
#encode $id[0],$id[1],$id[2] as 4 chars
my $v=rand(0x1000000);
$ssid .= _encode64(ord(substr($id,$i))^($v>>16),
ord(substr($id,$i+1))^($v>>8),
ord(substr($id,$i+2))^$v);
}
return $salt.$ssid;
}
sub _DecodeValue {
my($s)=@_;
use Digest::MD5;
my($salt,$ssid)=(substr($s,0,8),substr($s,8));
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0;
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed);
my $id="";
for(my $i=0;$i<length($ssid)-3;$i+=4){
#decode next four chars
my $v=rand(0x1000000)^_decode64(substr($ssid,$i));
$id .= chr($v>>16) . chr(0xff&($v>>8)) . chr(0xff&$v);
}
$id =~ s/ +$//; ## strip spaces at the end
# $salt and $chksum should be equal
$id="" if ($salt ne substr(Digest::MD5::md5_hex($id, _secret()),0,8));
return $id;
}
'''Remarks:'''
*The MIME64-like encoding uses letters (both lower and upper case), digits and the characters - (minus) and _ (underscore). These are safe to use in an URL.
*Both encoding and decoding uses MD5 as the building block. The first eight characters of the ciphertext (encoded string) is used for two purposes. First, it acts as a salt, namely it is added to the secret phrase to derive the seed of the random number generator; second it is used to check message integrity, namely it should match the MD5 hash of the message ''and'' the secret phrase.
*Messages to be encrypted (plaintext) should not end by a space (spaces are used to pad the plaintext to have length divisible by three)
*The encryption is deterministic. Such a scheme is insecure in general. In our case, however, the plaintext contains a timestamp, thus - supposedly - the same message is not encrypted twice.
*Weak points of the scheme: only 32 bit MAC (and seed) value, and relying on perl's pseudorandom function.

==Patching Apache::Login==

[[Category:Howto]]

Secure login

2009-07-27T16:28:17Z

Laci@degas.ceu.hu: /* Receive data script */

When logging into eprints, both username and password travel openly. Usually it is not a problem as eprints has its own authenticating mechanism, and stealing an eprints password gives the intruder very limited power. However when using centralized authentication (e.g., by [[LDAP]]) then protecting the password is more important. To prevent sniffing login pages usually use secure connection. Here we discuss an easy way to set up eprints to use encoded password traffic.

__TOC__

==The idea==

Change the destination of the eprints login page to a secure host. On the secure host a script receives the data: login name and password (and maybe others), encodes it, and forwards the request with the encrypted data as payload to an unencrypted eprints page. The eprints page decrypts the data and uses it for authentication.

===Requirements===
You need a ''secure http server'' on the same main domain as your your eprints server. For example, if eprints can be reached on the web address ''<nowiki>http://eprints.umb.edu</nowiki>'', then the secure server must have domain name ending with ''umb.edu'', for example ''<nowiki>https://secure.umb.edu</nowiki>.

You should set up a cgi executable directory on the secure host. The apache config extract below does exactly this so that ''<nowiki>https://secure.umb.edu/eprints/whatever</nowiki>'' requests the script ''/opt/cgi-bin/eprints/whatever'' to be executed:
<VirtualHost *:443>
DocumentRoot "/opt/secure"
SSLEngine on
ScriptAlias /eprints/ /opt/cgi-bin/eprints/
<Directory "/opt/cgi-bin/eprints">
AllowOverride None
Options +ExecCGI -MultiView +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Copy the [[#Secure login script|Secure login script]] below into the ''/opt/cgi-bin/eprints/'' directory (or whatever directory you've set up above); copy the [[#Receive data script|receive data script]] into eprints' ''/cgi/'' directory.

Finally [[#Patching Apache::Login |patch the Apache::Login module]] of eprints so that everything works smoothly.

===Caveats===
The login process now works as follows.
# when a page requires authentication, it creates a "login page" with destination at the secure web site
# the "login page" is sent encrypted to the secure site
# the secure site encrypts the payload, and redirects the browser to an unencrypted eprints page ''receive_data''
# ''receive_data'' decrypts the payload, checks credentials, logs in the user if everything checks, and then redirects the browser to the originating page.

What is lost in this process of two redirects is the error message when authentication fails. ''Receive_data'' cannot display the error message as its URL should not be displayed on the user's screen. The final page - which is the original one as well - cannot distinguish between an unsuccessful login and a reload, thus cannot display the error message as well. ''C'est la vie''.

The encrypted data the ''receive_data'' page receives can be a replay of a sniffed older communication. Thus this data should contain a timestamp and checked to be recent.

The secure site can also check the credentials, and relay the result only. Interestingly, the result should be sent encrypted, as otherwise the secure site could be used as an oracle to tell whether the password is correct or not (ideal for a [http://en.wikipedia.org/wiki/Dictionary_attack dictionary attack]).

==Secure login script==
This script receives the login page over a secure connection. It encrypts the username, password, and other arguments, and relocates the page to eprints' ''receive_data'' page.

Using the secure site configuration above, this script should be copied to ''/opt/cgi-bin/eprints/login'' after changing the address to your own eprint server.

##!/usr/bin/perl -w
## secure login script for eprints
## encrypt and automatically forward to /eprints
## Author: Laszlo Csirmaz, 2009
## You are free to use this script
use strict;
sub _RelocateTo {
my $arg=shift;
"<nowiki>http://eprints.umb.edu/cgi/receive_data?Q=$arg</nowiki>";
}
<-- COPY THE CRYPTO ROUTINES HERE -->
sub _html2ascii {
my $v=shift;
$v="" if(! defined $v);
$v=~ tr/+/ /;
$v=~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
return $v;
}
my $P={};
my $ct=$ENV{'CONTENT_TYPE');
if($ct && $ct =~ /multipart/i ){
use CGI qw( :cgi :form );
my $req=new CGI; # read all data in
my @pm=$req->param;
foreach my $key (@pm) {
$P->{$key} = _html2ascii($req->param($ley));
}
} elsif ( $ENV{'REQUEST_METHOD'} !~ /^get/i ) {
my $pm=""; while(<>){ $pm .= $_; }
my @pms=split(/&/,$pm);
foreach my $elem(@pms) {
my($t,$v)=split(/=/,$elem);
next if(! defined($t) );
$P->{_html2ascii($t)} = _html2ascii($v);
}
}
## we return the following arguments:
## target, loginparams, username, pw, timestamp
my $arg="";
for my $item ($P->{target},$P->{loginparams},
$P->{login_username}, $P->{login_password} ){
$item="" if(! $item)[
# replace '%' by '%a' and replace ':' by '%c'
$item =~ s/%/%a/g; $item =~ s/:/%c/g;
$arg .= "$item:";
}
my $addr = _RelocateTo( _EncodeValue( $arg . int(time/60) ) );
print "Content-Type: text/html; charset=utf-8\n",
"Location: $addr\n",
"\n",
"<html><head><title>Redirected</title></head>\n",
"<body>\n",
"This page should automatically relocated. If not,\n",
"please <a href=\"$addr\">click here</a>.\n",
"</body>\n",
"</html>\n",
"\n";
exit 0;

==Receive data script==
This script receives the encrypted data from the secure server, decrypts it and logs in the user. A 1 second delay is inserted if there is a problem with the credentials.

This script should be copied to the ''eprints/cgi/receive_data''. It calls the ''check_user_password'' configuration procedure if it is defined.
######################################################
# receive_data
# Part of EPrints 3.1
# Author: Laszlo Csirmaz
# You are free to use/modify this script
######################################################
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );
my $redirect_to="/cgi/users/home";
my $loginparams="";
my $OK=1;
my $arg = $session->param('Q');
if( $arg && length($arg) > 10 ){ #sanity check
$arg = _DecodeValue($arg);
## it is target:loginparams:uname:pw:timenow
$arg = "/cgi/users/home::::" if(!$arg);
my @list = split(/:/,$arg);
for my $i(0..4){
$list[$i]="" if(!$list[$i]);
$list[$i] =~ s/%c/:/g; $list[$i] =~ s/%a/%/g;
}
$OK=0 if( $list[4] !~ /^\d$/ );
if($OK){
my $timediff = int(time/60) - $list[4];
#allow a 2 minute window
$OK=0 if( $timediff<-1 || $timediff > 2 );
}
$redirect_to = $list[0] if($list[0] =~ m#/# );
$loginparams = $list[1];
if($OK){
if( $session->valid_login($list[2],$list[3] ) ){
my $user = EPrints::DataObj::User::user_with_username(
$session,$list[2]);
$session->login($user);
$OK=2;
}
}
}
sleep 1 if( $OK != 2 ); # some problem, don't hurry
my $host = $session->{repository}->get_conf( "host" );
my $port = $session->{repository}->get_conf( "port" );
$redirect_to = "<nowiki>http://$host</nowiki>".($port!=80 :":$port":""). $redirect_to;
$redirect_to .= "?$loginparams" if($loginparams);
$session->redirect( $redirect_to );
$session->terminate;
exit 0;
<nowiki></nowiki>

==Crypto routines==
These routines perform encryption and decryption. It is a lightweight version of more sophisticated ones, but (at least I hope) it is sufficient for this application. After the source there are some remarks for those interested.

<div style="padding:4px; background-color: #ffe0e0;border:1px solid #a06060;">'''Warning!''' The secret phrase in the second line should be changed to some secret value.</div>
sub _secret {
"Whatever is your secret phrase, give anything here";
}
sub _intto64 { #a MIME64 type encoding
my $c=shift;
$c &=0x3F;
if($c<10){ return chr(48+$c); }
if($c<10+26){ return chr($c-10+65); }
if($c<10+26+26){ return chr($c-10-26+97); }
if($c==62){ return '_'; }
return '-';
}
sub _encode64 { #encoding three bytes to four chars
my($a,$b,$c)=@_;
$a &= 0xFF; $b &= 0xFF; $c &= 0xFF;
return _intto64($a>>2)._intto64(($a<<4)|($b>>4)).
_intto64(($b<<2)|($c>>6))._intto64($c);
}
sub _from64 { #decoding of the above
my $c=ord(shift||"0");
if($c==95){ return 62;}
if($c==45){ return 63;}
if($c<48+10){ return $c-48; }
if($c<65+26){ return $c-65+10; }
return $c-97+10+26;
}
sub _decode64 { # decoding four chars to three bytes
my($s)=shift;
my ($r1,$r2,$r3,$r4)=(
_from64($s),_from64(substr($s,1)),
_from64(substr($s,2)),_from64(substr($s,3)));
return ($r1<<18)|($r2<<12)|($r3<<6)|$r4;
}
sub _EncodeValue { ## encoded value should not end in a space
my($id) = @_;
use Digest::MD5;
my $salt=substr(Digest::MD5::md5_hex($id, _secret()),0,8);
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0; my $ssid="";
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed); my $idlen=length($id);
$id .= " "; # pad message by spaces
for(my $i=0;$i<$idlen;$i+=3){
#encode $id[0],$id[1],$id[2] as 4 chars
my $v=rand(0x1000000);
$ssid .= _encode64(ord(substr($id,$i))^($v>>16),
ord(substr($id,$i+1))^($v>>8),
ord(substr($id,$i+2))^$v);
}
return $salt.$ssid;
}
sub _DecodeValue {
my($s)=@_;
use Digest::MD5;
my($salt,$ssid)=(substr($s,0,8),substr($s,8));
my $sstr=Digest::MD5::md5($salt, _secret());
my $seed=0;
for(my $i=0;$i<8;$i++){$seed=($seed<<8)+ord(substr($sstr,$i));}
srand($seed);
my $id="";
for(my $i=0;$i<length($ssid)-3;$i+=4){
#decode next four chars
my $v=rand(0x1000000)^_decode64(substr($ssid,$i));
$id .= chr($v>>16) . chr(0xff&($v>>8)) . chr(0xff&$v);
}
$id =~ s/ +$//; ## strip spaces at the end
# $salt and $chksum should be equal
$id="" if ($salt ne substr(Digest::MD5::md5_hex($id, _secret()),0,8));
return $id;
}
'''Remarks:'''
*The MIME64-like encoding uses letters (both lower and upper case), digits and the characters - (minus) and _ (underscore). These are safe to use in an URL.
*Both encoding and decoding uses MD5 as the building block. The first eight characters of the ciphertext (encoded string) is used for two purposes. First, it acts as a salt, namely it is added to the secret phrase to derive the seed of the random number generator; second it is used to check message integrity, namely it should match the MD5 hash of the message ''and'' the secret phrase.
*Messages to be encrypted (plaintext) should not end by a space (spaces are used to pad the plaintext to have length divisible by three)
*The encryption is deterministic. Such a scheme is insecure in general. In our case, however, the plaintext contains a timestamp, thus - supposedly - the same message is not encrypted twice.
*Weak points of the scheme: only 32 bit MAC (and seed) value, and relying on perl's pseudorandom function.

==Patching Apache::Login==

[[Category:Howto]]

Secure login

2009-07-27T16:00:48Z

Laci@degas.ceu.hu: /* Secure login script */

Secure login

2009-07-27T15:26:46Z

Laci@degas.ceu.hu: /* Crypto routines */

Secure login

2009-07-27T14:54:18Z

Laci@degas.ceu.hu:

Secure login

2009-07-27T14:53:31Z

Laci@degas.ceu.hu:

A simple secure login

When logging into eprints, both username and password travel openly. Usually it is not a problem as eprints has its own authenticating mechanism, and stealing an eprints password gives the intruder very limited power. However when using centralized authentication (e.g., by [[LDAP]]) then protecting the password is more important. To prevent sniffing login pages usually use secure connection. Here we discuss an easy way to set up eprints to use encoded password traffic.

__TOC__

==The idea==

Change the destination of the eprints login page to a secure host. On the secure host a script receives the data: login name and password (and maybe others), encodes it, and forwards the request with the encrypted data as payload to an unencrypted eprints page. The eprints page decrypts the data and uses it for authentication.

===Requirements===
You need a ''secure http server'' on the same main domain as your your eprints server. For example, if eprints can be reached on the web address ''<nowiki>http://eprints.umb.edu</nowiki>'', then the secure server must have domain name ending with ''umb.edu'', for example ''<nowiki>https://secure.umb.edu</nowiki>.

You should set up a cgi executable directory on the secure host. The apache config extract below does exactly this so that ''<nowiki>https://secure.umb.edu/eprints/whatever</nowiki>'' requests the script ''/opt/cgi-bin/eprints/whatever'' to be executed:
<VirtualHost *:443>
DocumentRoot "/opt/secure"
SSLEngine on
ScriptAlias /eprints/ /opt/cgi-bin/eprints/
<Directory "/opt/cgi-bin/eprints">
AllowOverride None
Options +ExecCGI -MultiView +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Copy the [[#Secure login script|Secure login script]] below into the ''/opt/cgi-bin/eprints/'' directory (or whatever directory you've set up above); copy the [[#Receive data script|receive data script]] into eprints' ''/cgi/'' directory.

Finally [[#Patching Apache::Login |patch the Apache::Login module]] of eprints so that everything works smoothly.

===Caveats===
The login process now works as follows.
# when a page requires authentication, it creates a "login page" with destination at the secure web site
# the "login page" is sent encrypted to the secure site
# the secure site encrypts the payload, and redirects the browser to an unencrypted eprints page ''receive_data''
# ''receive_data'' decrypts the payload, checks credentials, logs in the user if everything checks, and then redirects the browser to the originating page.

What is lost in this process of two redirects is the error message when authentication fails. ''Receive_data'' cannot display the error message as its URL should not be displayed on the user's screen. The final page - which is the original one as well - cannot distinguish between an unsuccessful login and a reload, thus cannot display the error message as well. ''C'est la vie''.

The encrypted data the ''receive_data'' page receives can be a replay of a sniffed older communication. Thus this data should contain a timestamp and checked to be recent.

The secure site can also check the credentials, and relay the result only. Interestingly, the result should be sent encrypted, as otherwise the secure site could be used as an oracle to tell whether the password is correct or not (ideal for a [http://en.wikipedia.org/wiki/Dictionary_attack dictionary attack]).

==Secure login script==

==Receive data script==

==Crypto routines==

==Patching Apache::Login==

[[Category:Howto]]

Category:Manual

2009-07-26T21:12:12Z

Laci@degas.ceu.hu: New page: ===Main articles in this category=== * Getting Started * Installation * EPrints configuration * Branding/Logos

===Main articles in this category===

* [[Getting Started]]
* [[Installation]]
* [[EPrints configuration]]
* [[Branding/Logos]]

Secure login

2009-07-26T21:02:26Z

Laci@degas.ceu.hu: New page: Lightweight secure login Category:Howto

Lightweight secure login

[[Category:Howto]]

Views.pl

2009-07-24T12:59:57Z

Laci@degas.ceu.hu: /* Options available for the views config */

== 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 <sup style="font-weight:bold; font-size:10px">(V)</sup> are ''view'' attributes and are in the view definition; attributes marked by <sup style="font-weight:bold; font-size:10px">(M)</sup> 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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
| (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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|(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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
allow_null <sup style="font-weight:bold; font-size:10px;">(V)</sup>
new_column_at <sup style="font-weight:bold; font-size:10px;">(V)</sup>
render_menu <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
| 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.
|}

===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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|A costum function which sorts the group identifiers. The only available function
*"EPrints::Update::Views::default_sort"
sorts alphabetically.
|-valign="top"
|group_range_function <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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_eprints_<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_eprints_<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_eprints_<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_eprints_divisions">Divisions</epp:phrase>
<epp:phrase id="viewtitle_eprints_divisions_menu_1">
Browse by Division and Year</epp:phrase>
<epp:phrase id="viewtitle_eprints_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
| ?
|}

Views.pl

2009-07-24T12:59:21Z

Laci@degas.ceu.hu: /* Views */

== 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 <sup style="font-weight:bold; font-size:10px">(V)</sup> are ''view'' attributes and are in the view definition; attributes marked by <sup style="font-weight:bold; font-size:10px">(M)</sup> are ''menu'' attributes and should be use 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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
| (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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|(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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
allow_null <sup style="font-weight:bold; font-size:10px;">(V)</sup>
new_column_at <sup style="font-weight:bold; font-size:10px;">(V)</sup>
render_menu <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
| 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.
|}

===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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|A costum function which sorts the group identifiers. The only available function
*"EPrints::Update::Views::default_sort"
sorts alphabetically.
|-valign="top"
|group_range_function <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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_eprints_<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_eprints_<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_eprints_<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_eprints_divisions">Divisions</epp:phrase>
<epp:phrase id="viewtitle_eprints_divisions_menu_1">
Browse by Division and Year</epp:phrase>
<epp:phrase id="viewtitle_eprints_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
| ?
|}

Views.pl

2009-07-23T11:57:06Z

Laci@degas.ceu.hu: /* Views */

== Views ==
Conceptually a ''view'' is a browsable list of eprints split into ''menus'' and a ''list''.

{| cellpadding="0" cellspacing="0" border="0"
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">Menu1</div>
|  
|  
|  
|  
|-
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item1_1 ------</div>
|<span style="font-size:10px">---></span>
| <div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">Menu2</div>
|  
|  
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; font-size:10px">   Item1_2 </div>
|  
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item2_1 -----</div>
|<span style="font-size:10px">---></span>
|<div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">     LIST     </div>
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px">   ....</div>
|  
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item2_2 </div>
| 
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px">   ....</div>
|-
|  
|  
| <div width="100%" 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 <sup style="font-weight:bold; font-size:10px">(V)</sup> are ''view'' attributes and are in the view definition; attributes marked by <sup style="font-weight:bold; font-size:10px">(M)</sup> are ''menu'' attributes and should be use 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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
| (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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|(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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
allow_null <sup style="font-weight:bold; font-size:10px;">(V)</sup>
new_column_at <sup style="font-weight:bold; font-size:10px;">(V)</sup>
render_menu <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
| 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.
|}

===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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|A costum function which sorts the group identifiers. The only available function
*"EPrints::Update::Views::default_sort"
sorts alphabetically.
|-valign="top"
|group_range_function <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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_eprints_<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_eprints_<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_eprints_<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_eprints_divisions">Divisions</epp:phrase>
<epp:phrase id="viewtitle_eprints_divisions_menu_1">
Browse by Division and Year</epp:phrase>
<epp:phrase id="viewtitle_eprints_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
| ?
|}

Views.pl

2009-07-23T11:55:37Z

Laci@degas.ceu.hu: /* Options available for the views config */

== Views ==
Conceptually a ''view'' is a browsable list of eprints split into ''menus'' and a ''list''.

{| cellpadding="0" cellspacing="0" border="0"
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">Menu1</div>
|  
|  
|  
|  
|-
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item1_1 ------</div>
| -->
| <div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">Menu2</div>
|  
|  
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; font-size:10px">   Item1_2 </div>
|  
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item2_1 -----</div>
| -->
|<div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">     LIST     </div>
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px">   ....</div>
|  
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item2_2 </div>
| 
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px">   ....</div>
|-
|  
|  
| <div width="100%" 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 <sup style="font-weight:bold; font-size:10px">(V)</sup> are ''view'' attributes and are in the view definition; attributes marked by <sup style="font-weight:bold; font-size:10px">(M)</sup> are ''menu'' attributes and should be use 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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
| (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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|(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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
allow_null <sup style="font-weight:bold; font-size:10px;">(V)</sup>
new_column_at <sup style="font-weight:bold; font-size:10px;">(V)</sup>
render_menu <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
| 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.
|}

===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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|A costum function which sorts the group identifiers. The only available function
*"EPrints::Update::Views::default_sort"
sorts alphabetically.
|-valign="top"
|group_range_function <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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_eprints_<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_eprints_<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_eprints_<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_eprints_divisions">Divisions</epp:phrase>
<epp:phrase id="viewtitle_eprints_divisions_menu_1">
Browse by Division and Year</epp:phrase>
<epp:phrase id="viewtitle_eprints_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
| ?
|}

Views.pl

2009-07-23T09:00:35Z

Laci@degas.ceu.hu: /* Options available for the views config */

== Views ==
Conceptually a ''view'' is a browsable list of eprints split into ''menus'' and a ''list''.

{| cellpadding="0" cellspacing="0" border="0"
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">Menu1</div>
|  
|  
|  
|  
|-
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item1_1 ------</div>
| -->
| <div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">Menu2</div>
|  
|  
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; font-size:10px">   Item1_2 </div>
|  
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item2_1 -----</div>
| -->
|<div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">     LIST     </div>
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px">   ....</div>
|  
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item2_2 </div>
| 
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px">   ....</div>
|-
|  
|  
| <div width="100%" 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

Attributes marked by <sup style="font-weight:bold; font-size:10px">(V)</sup> are ''view'' attributes and are in the browse definition; attributes marked by <sup style="font-weight:bold; font-size:10px">(M)</sup> are ''menu'' attributes and should be the [[#Menu options|menu definitions]].

==Basic options==

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

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id <sup style="font-weight:bold; font-size:10px;">(V)</sup>
| (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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|(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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
allow_null <sup style="font-weight:bold; font-size:10px;">(V)</sup>
new_column_at <sup style="font-weight:bold; font-size:10px;">(V)</sup>
render_menu <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
| 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.
|}

===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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|A costum function which sorts the group identifiers. The only available function
*"EPrints::Update::Views::default_sort"
sorts alphabetically.
|-valign="top"
|group_range_function <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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_eprints_<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_eprints_<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_eprints_<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_eprints_divisions">Divisions</epp:phrase>
<epp:phrase id="viewtitle_eprints_divisions_menu_1">
Browse by Division and Year</epp:phrase>
<epp:phrase id="viewtitle_eprints_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
| ?
|}

Views.pl

2009-07-23T08:59:10Z

Laci@degas.ceu.hu: /* Basic options */

== Views ==
Conceptually a ''view'' is a browsable list of eprints split into ''menus'' and a ''list''.

{| cellpadding="0" cellspacing="0" border="0"
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">Menu1</div>
|  
|  
|  
|  
|-
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item1_1 ------</div>
| -->
| <div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">Menu2</div>
|  
|  
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; font-size:10px">   Item1_2 </div>
|  
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item2_1 -----</div>
| -->
|<div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">     LIST     </div>
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px">   ....</div>
|  
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item2_2 </div>
| 
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px">   ....</div>
|-
|  
|  
| <div width="100%" 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

Attributes marked by <sup style="font-weight:bold; font-size:10px">(V)</sup> are ''view'' attributes and are in the view definition; attributes marked by <sup style="font-weight:bold; font-size:10px">(M)</sup> are ''menu'' attributes and should be the [[#Menu options|menu definitions]].

==Basic options==

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

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id <sup style="font-weight:bold; font-size:10px;">(V)</sup>
| (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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|(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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
allow_null <sup style="font-weight:bold; font-size:10px;">(V)</sup>
new_column_at <sup style="font-weight:bold; font-size:10px;">(V)</sup>
render_menu <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
| 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.
|}

===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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|A costum function which sorts the group identifiers. The only available function
*"EPrints::Update::Views::default_sort"
sorts alphabetically.
|-valign="top"
|group_range_function <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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 <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|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_eprints_<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_eprints_<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_eprints_<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_eprints_divisions">Divisions</epp:phrase>
<epp:phrase id="viewtitle_eprints_divisions_menu_1">
Browse by Division and Year</epp:phrase>
<epp:phrase id="viewtitle_eprints_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
| ?
|}

Views.pl

2009-07-23T08:43:32Z

Laci@degas.ceu.hu: /* Options available for the views config */

== Views ==
Conceptually a ''view'' is a browsable list of eprints split into ''menus'' and a ''list''.

{| cellpadding="0" cellspacing="0" border="0"
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">Menu1</div>
|  
|  
|  
|  
|-
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item1_1 ------</div>
| -->
| <div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">Menu2</div>
|  
|  
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; font-size:10px">   Item1_2 </div>
|  
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item2_1 -----</div>
| -->
|<div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">     LIST     </div>
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px">   ....</div>
|  
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item2_2 </div>
| 
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px">   ....</div>
|-
|  
|  
| <div width="100%" 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

Attributes marked by <sup style="font-weight:bold; font-size:10px">(V)</sup> are ''view'' attributes and are in the view definition; attributes marked by <sup style="font-weight:bold; font-size:10px">(M)</sup> are ''menu'' attributes and should be the [[#Menu options|menu definitions]].

==Basic options==

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id
| (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
|(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
allow_null
new_column_at
render_menu
|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
|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
|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
|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
| 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.
|}

===View list options===
There are options which determine how the last page in the menu chain should look like.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order
|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
|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
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations
|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
|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
|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
|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:

{| 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===

{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields
|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
|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
|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
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode
|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
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu
|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
|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.
{|border="1" cellpadding="4" cellspacing="0"
|-valign="top"
|grouping_function
|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
|A costum function which sorts the group identifiers. The only available function
*"EPrints::Update::Views::default_sort"
sorts alphabetically.
|-valign="top"
|group_range_function
|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
|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_eprints_<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_eprints_<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_eprints_<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_eprints_divisions">Divisions</epp:phrase>
<epp:phrase id="viewtitle_eprints_divisions_menu_1">
Browse by Division and Year</epp:phrase>
<epp:phrase id="viewtitle_eprints_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
| ?
|}

Views.pl

2009-07-23T08:42:58Z

Laci@degas.ceu.hu: /* Options available for the views config */

== Views ==
Conceptually a ''view'' is a browsable list of eprints split into ''menus'' and a ''list''.

{| cellpadding="0" cellspacing="0" border="0"
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">Menu1</div>
|  
|  
|  
|  
|-
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item1_1 ------</div>
| -->
| <div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">Menu2</div>
|  
|  
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; font-size:10px">   Item1_2 </div>
|  
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item2_1 -----</div>
| -->
|<div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">     LIST     </div>
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px">   ....</div>
|  
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item2_2 </div>
| 
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px">   ....</div>
|-
|  
|  
| <div width="100%" 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

Attributes marked by <sup style="font-weight:bold; font-size:10px">(V)</sup> are ''view'' attributes and are in the view definition; attributes marked by <sup style="font-weight:bold; font-size:10px">(M)</sup> are ''menu'' attributes and should be the [[#menu|menu definitions]].

==Basic options==

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id
| (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
|(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
allow_null
new_column_at
render_menu
|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
|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
|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
|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
| 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.
|}

===View list options===
There are options which determine how the last page in the menu chain should look like.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order
|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
|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
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations
|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
|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
|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
|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:

{| 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===

{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields
|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
|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
|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
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode
|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
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu
|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
|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.
{|border="1" cellpadding="4" cellspacing="0"
|-valign="top"
|grouping_function
|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
|A costum function which sorts the group identifiers. The only available function
*"EPrints::Update::Views::default_sort"
sorts alphabetically.
|-valign="top"
|group_range_function
|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
|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_eprints_<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_eprints_<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_eprints_<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_eprints_divisions">Divisions</epp:phrase>
<epp:phrase id="viewtitle_eprints_divisions_menu_1">
Browse by Division and Year</epp:phrase>
<epp:phrase id="viewtitle_eprints_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
| ?
|}

Views.pl

2009-07-23T08:38:45Z

Laci@degas.ceu.hu: /* Options avaible for the views config */

== Views ==
Conceptually a ''view'' is a browsable list of eprints split into ''menus'' and a ''list''.

{| cellpadding="0" cellspacing="0" border="0"
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">Menu1</div>
|  
|  
|  
|  
|-
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item1_1 ------</div>
| -->
| <div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">Menu2</div>
|  
|  
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; font-size:10px">   Item1_2 </div>
|  
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item2_1 -----</div>
| -->
|<div width="100%" style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px">     LIST     </div>
|-
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px">   ....</div>
|  
|<div width="100%" style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px">   Item2_2 </div>
| 
| <div width="100%" style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px">   ....</div>
|-
|  
|  
| <div width="100%" 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

==Basic options==

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id
| (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
|(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
allow_null
new_column_at
render_menu
|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
|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
|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
|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
| 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.
|}

===View list options===
There are options which determine how the last page in the menu chain should look like.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order
|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
|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
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations
|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
|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
|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
|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:

{| 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===

{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields
|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
|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
|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
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode
|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
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu
|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
|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.
{|border="1" cellpadding="4" cellspacing="0"
|-valign="top"
|grouping_function
|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
|A costum function which sorts the group identifiers. The only available function
*"EPrints::Update::Views::default_sort"
sorts alphabetically.
|-valign="top"
|group_range_function
|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
|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_eprints_<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_eprints_<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_eprints_<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_eprints_divisions">Divisions</epp:phrase>
<epp:phrase id="viewtitle_eprints_divisions_menu_1">
Browse by Division and Year</epp:phrase>
<epp:phrase id="viewtitle_eprints_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
| ?
|}

Views.pl

2009-07-21T10:10:53Z

Laci@degas.ceu.hu: /* Variations */

== Options avaible 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

==Basic options==

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id
| (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
|(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
allow_null
new_column_at
render_menu
|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
|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
|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
|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
| 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.
|}

===View list options===
There are options which determine how the last page in the menu chain should look like.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order
|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
|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
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations
|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
|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
|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
|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:

{| 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===

{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields
|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
|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
|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
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode
|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
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu
|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
|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.
{|border="1" cellpadding="4" cellspacing="0"
|-valign="top"
|grouping_function
|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
|A costum function which sorts the group identifiers. The only available function
*"EPrints::Update::Views::default_sort"
sorts alphabetically.
|-valign="top"
|group_range_function
|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
|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_eprints_<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_eprints_<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_eprints_<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_eprints_divisions">Divisions</epp:phrase>
<epp:phrase id="viewtitle_eprints_divisions_menu_1">
Browse by Division and Year</epp:phrase>
<epp:phrase id="viewtitle_eprints_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
| ?
|}

Views.pl

2009-07-21T10:10:05Z

Laci@degas.ceu.hu: /* Variations */

== Options avaible 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

==Basic options==

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id
| (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
|(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
allow_null
new_column_at
render_menu
|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
|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
|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
|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
| 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.
|}

===View list options===
There are options which determine how the last page in the menu chain should look like.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order
|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
|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
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations
|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
|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
|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
|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, determines how the final list is rendered. Variation is an array of strings, such as

[ "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:

{| 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===

{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields
|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
|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
|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
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode
|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
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu
|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
|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.
{|border="1" cellpadding="4" cellspacing="0"
|-valign="top"
|grouping_function
|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
|A costum function which sorts the group identifiers. The only available function
*"EPrints::Update::Views::default_sort"
sorts alphabetically.
|-valign="top"
|group_range_function
|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
|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_eprints_<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_eprints_<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_eprints_<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_eprints_divisions">Divisions</epp:phrase>
<epp:phrase id="viewtitle_eprints_divisions_menu_1">
Browse by Division and Year</epp:phrase>
<epp:phrase id="viewtitle_eprints_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
| ?
|}

Views.pl

2009-07-21T10:06:16Z

Laci@degas.ceu.hu: /* View list options */

== Options avaible 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

==Basic options==

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id
| (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
|(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
allow_null
new_column_at
render_menu
|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
|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
|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
|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
| 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.
|}

===View list options===
There are options which determine how the last page in the menu chain should look like.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order
|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
|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
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations
|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
|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
|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
|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, determines how the final list is rendered. Variations is an array of strings, such as

[ "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'' 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:

{| 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===

{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields
|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
|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
|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
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode
|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
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu
|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
|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.
{|border="1" cellpadding="4" cellspacing="0"
|-valign="top"
|grouping_function
|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
|A costum function which sorts the group identifiers. The only available function
*"EPrints::Update::Views::default_sort"
sorts alphabetically.
|-valign="top"
|group_range_function
|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
|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_eprints_<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_eprints_<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_eprints_<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_eprints_divisions">Divisions</epp:phrase>
<epp:phrase id="viewtitle_eprints_divisions_menu_1">
Browse by Division and Year</epp:phrase>
<epp:phrase id="viewtitle_eprints_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
| ?
|}

Views.pl

2009-07-16T14:26:58Z

Laci@degas.ceu.hu: /* Phrases */

== Options avaible 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

==Basic options==

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id
| (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
|(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
allow_null
new_column_at
render_menu
|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
|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
|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
|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
| 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.
|}

===View list options===
There are options which determine how the last page in the view chain should look like.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order
|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
|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
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations
|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
|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
|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
|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, determines how the final list is rendered. Variations is an array of strings, such as

[ "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'' 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:

{| 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===

{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields
|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
|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
|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
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode
|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
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu
|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
|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.
{|border="1" cellpadding="4" cellspacing="0"
|-valign="top"
|grouping_function
|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
|A costum function which sorts the group identifiers. The only available function
*"EPrints::Update::Views::default_sort"
sorts alphabetically.
|-valign="top"
|group_range_function
|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
|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_eprints_<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_eprints_<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_eprints_<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_eprints_divisions">Divisions</epp:phrase>
<epp:phrase id="viewtitle_eprints_divisions_menu_1">
Browse by Division and Year</epp:phrase>
<epp:phrase id="viewtitle_eprints_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
| ?
|}

Views.pl

2009-07-16T14:26:34Z

Laci@degas.ceu.hu: /* Phrases */

== Options avaible 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

==Basic options==

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id
| (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
|(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
allow_null
new_column_at
render_menu
|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
|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
|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
|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
| 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.
|}

===View list options===
There are options which determine how the last page in the view chain should look like.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order
|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
|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
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations
|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
|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
|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
|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, determines how the final list is rendered. Variations is an array of strings, such as

[ "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'' 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:

{| 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===

{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields
|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
|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
|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
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode
|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
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu
|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
|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.
{|border="1" cellpadding="4" cellspacing="0"
|-valign="top"
|grouping_function
|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
|A costum function which sorts the group identifiers. The only available function
*"EPrints::Update::Views::default_sort"
sorts alphabetically.
|-valign="top"
|group_range_function
|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
|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_eprints_<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_eprints_<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_eprints_<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_eprints_divisions">Divisions</epp:phrase>
<epp:phrase id="viewtitle_eprints_divisions_menu_1">
Browse by Division and Year</epp:phrase>
<epp:phrase id="viewtitle_eprints_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
| ?
|}

Views.pl

2009-07-16T14:24:16Z

Laci@degas.ceu.hu:

== Options avaible 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

==Basic options==

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id
| (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
|(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
allow_null
new_column_at
render_menu
|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
|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
|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
|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
| 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.
|}

===View list options===
There are options which determine how the last page in the view chain should look like.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order
|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
|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
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations
|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
|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
|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
|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, determines how the final list is rendered. Variations is an array of strings, such as

[ "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'' 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:

{| 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===

{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields
|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
|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
|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
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode
|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
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu
|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
|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.
{|border="1" cellpadding="4" cellspacing="0"
|-valign="top"
|grouping_function
|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
|A costum function which sorts the group identifiers. The only available function
*"EPrints::Update::Views::default_sort"
sorts alphabetically.
|-valign="top"
|group_range_function
|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
|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_eprints_<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_eprints_<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_eprints_<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_eprints_divisions">Divisions</epp:phrase>
<epp:phrase id="viewtitle_eprints_divisions_menu_1">
Browse by Division and Year</epp:phrase>
<epp:phrase id="viewtitle_eprints_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
| ?
|}

Views.pl

2009-07-16T12:33:41Z

Laci@degas.ceu.hu: /* nocount */

== Options avaible 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

==Basic options==

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id
| (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://yourrepo/view/</nowiki>. This is the value of the ''browse_link'' attribute in [[eprint_fields.pl]]. Example:

id => 'divisions',
|- valign="top"
|fields
|(deprecated) This attribute describes the field(s) by which the view is built. It has been replaced by the more general [[#Options in menus|menus]] attribute.
|- valign="top"
|hideempty
allow_null
new_column_at
render_menu
|These define the default values of the same attributes in all [[#Options in menus|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
|An array of ''[[#Options in menus|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
|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
|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
| 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.
|}

===View list options===
There are options which determine how the last page in the view chain should look like.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order
|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
|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
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations
|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
|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
|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
|Defaults to 86400 (one day in seconds). If the lists in this view were generated more than than many seconds ago, it is regenerated.
|}

===Options in menus===
{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields
|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
|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
|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
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode
|Possible values: ''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 below.
|- valign="top"
|hideup
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu
|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
|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.
|}

===Variations===

Variations is an array of string, such as

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

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 consists of a field name, followed by zero, one or more ''options'' separated by commas. An option is either a single attribute, or an attribute, an equal sign, and the value of the attribute. Thus
"creators_name;truncate=4,hideup"
sets the attribute value "truncate" to 4, and "hideup" to 1 (or true).

The following options are available:

{| 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 of 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
|}

==Phrases==

===Standard===

====heading_level====

====include====

====subheadings====

===Extra feature===

====nohtml====

====noindex====

Views.pl

2009-07-16T12:32:48Z

Laci@degas.ceu.hu: /* Variations */

== Options avaible 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

==Basic options==

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id
| (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://yourrepo/view/</nowiki>. This is the value of the ''browse_link'' attribute in [[eprint_fields.pl]]. Example:

id => 'divisions',
|- valign="top"
|fields
|(deprecated) This attribute describes the field(s) by which the view is built. It has been replaced by the more general [[#Options in menus|menus]] attribute.
|- valign="top"
|hideempty
allow_null
new_column_at
render_menu
|These define the default values of the same attributes in all [[#Options in menus|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
|An array of ''[[#Options in menus|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
|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
|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
| 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.
|}

===View list options===
There are options which determine how the last page in the view chain should look like.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order
|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
|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
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations
|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
|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
|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
|Defaults to 86400 (one day in seconds). If the lists in this view were generated more than than many seconds ago, it is regenerated.
|}

===Options in menus===
{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields
|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
|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
|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
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode
|Possible values: ''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 below.
|- valign="top"
|hideup
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu
|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
|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.
|}

===Variations===

Variations is an array of string, such as

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

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 consists of a field name, followed by zero, one or more ''options'' separated by commas. An option is either a single attribute, or an attribute, an equal sign, and the value of the attribute. Thus
"creators_name;truncate=4,hideup"
sets the attribute value "truncate" to 4, and "hideup" to 1 (or true).

The following options are available:

{| 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 of 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
|}

==Phrases==

===Standard===

====heading_level====

====include====

====subheadings====

===Extra feature===

====nocount====

====nohtml====

====noindex====

Views.pl

2009-07-16T12:18:37Z

Laci@degas.ceu.hu: /* Options in menus */

== Options avaible 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

==Basic options==

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id
| (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://yourrepo/view/</nowiki>. This is the value of the ''browse_link'' attribute in [[eprint_fields.pl]]. Example:

id => 'divisions',
|- valign="top"
|fields
|(deprecated) This attribute describes the field(s) by which the view is built. It has been replaced by the more general [[#Options in menus|menus]] attribute.
|- valign="top"
|hideempty
allow_null
new_column_at
render_menu
|These define the default values of the same attributes in all [[#Options in menus|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
|An array of ''[[#Options in menus|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
|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
|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
| 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.
|}

===View list options===
There are options which determine how the last page in the view chain should look like.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order
|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
|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
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations
|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
|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
|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
|Defaults to 86400 (one day in seconds). If the lists in this view were generated more than than many seconds ago, it is regenerated.
|}

===Options in menus===
{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields
|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
|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
|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
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode
|Possible values: ''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 below.
|- valign="top"
|hideup
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu
|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
|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.
|}

===Variations===

Variations is an array of string, such as

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

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 consists of a field name, followed by zero, one or more ''options'' separated by commas. An option is either a single attribute, or an attribute, an equal sign, and the value of the attribute. Thus
"creators_name;truncate=4,hideup"
sets the attribute value "truncate" to 4, and "hideup" to 1 (or true).

The following options are available:

{| 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
|
jump=plain

Turns of the 'jump to' text before the list of subheading navigation links.
|- 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
|}

==Phrases==

===Standard===

====heading_level====

====include====

====subheadings====

===Extra feature===

====nocount====

====nohtml====

====noindex====

Views.pl

2009-07-16T12:18:11Z

Laci@degas.ceu.hu: /* View list options */

== Options avaible 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

==Basic options==

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id
| (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://yourrepo/view/</nowiki>. This is the value of the ''browse_link'' attribute in [[eprint_fields.pl]]. Example:

id => 'divisions',
|- valign="top"
|fields
|(deprecated) This attribute describes the field(s) by which the view is built. It has been replaced by the more general [[#Options in menus|menus]] attribute.
|- valign="top"
|hideempty
allow_null
new_column_at
render_menu
|These define the default values of the same attributes in all [[#Options in menus|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
|An array of ''[[#Options in menus|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
|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
|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
| 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.
|}

===View list options===
There are options which determine how the last page in the view chain should look like.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order
|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
|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
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations
|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
|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
|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
|Defaults to 86400 (one day in seconds). If the lists in this view were generated more than than many seconds ago, it is regenerated.
|}

==Options in menus==
{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields
|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
|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
|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
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode
|Possible values: ''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 below.
|- valign="top"
|hideup
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu
|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
|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.
|}

===Variations===

Variations is an array of string, such as

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

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 consists of a field name, followed by zero, one or more ''options'' separated by commas. An option is either a single attribute, or an attribute, an equal sign, and the value of the attribute. Thus
"creators_name;truncate=4,hideup"
sets the attribute value "truncate" to 4, and "hideup" to 1 (or true).

The following options are available:

{| 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
|
jump=plain

Turns of the 'jump to' text before the list of subheading navigation links.
|- 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
|}

==Phrases==

===Standard===

====heading_level====

====include====

====subheadings====

===Extra feature===

====nocount====

====nohtml====

====noindex====

Views.pl

2009-07-16T12:17:47Z

Laci@degas.ceu.hu: /* Phrases */

== Options avaible 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

==Basic options==

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id
| (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://yourrepo/view/</nowiki>. This is the value of the ''browse_link'' attribute in [[eprint_fields.pl]]. Example:

id => 'divisions',
|- valign="top"
|fields
|(deprecated) This attribute describes the field(s) by which the view is built. It has been replaced by the more general [[#Options in menus|menus]] attribute.
|- valign="top"
|hideempty
allow_null
new_column_at
render_menu
|These define the default values of the same attributes in all [[#Options in menus|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
|An array of ''[[#Options in menus|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
|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
|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
| 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.
|}

==View list options==
There are options which determine how the last page in the view chain should look like.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order
|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
|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
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations
|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
|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
|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
|Defaults to 86400 (one day in seconds). If the lists in this view were generated more than than many seconds ago, it is regenerated.
|}

==Options in menus==
{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields
|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
|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
|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
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode
|Possible values: ''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 below.
|- valign="top"
|hideup
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu
|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
|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.
|}

===Variations===

Variations is an array of string, such as

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

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 consists of a field name, followed by zero, one or more ''options'' separated by commas. An option is either a single attribute, or an attribute, an equal sign, and the value of the attribute. Thus
"creators_name;truncate=4,hideup"
sets the attribute value "truncate" to 4, and "hideup" to 1 (or true).

The following options are available:

{| 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
|
jump=plain

Turns of the 'jump to' text before the list of subheading navigation links.
|- 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
|}

==Phrases==

===Standard===

====heading_level====

====include====

====subheadings====

===Extra feature===

====nocount====

====nohtml====

====noindex====

Views.pl

2009-07-16T12:17:07Z

Laci@degas.ceu.hu: /* Options in menus */

== Options avaible 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

==Basic options==

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id
| (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://yourrepo/view/</nowiki>. This is the value of the ''browse_link'' attribute in [[eprint_fields.pl]]. Example:

id => 'divisions',
|- valign="top"
|fields
|(deprecated) This attribute describes the field(s) by which the view is built. It has been replaced by the more general [[#Options in menus|menus]] attribute.
|- valign="top"
|hideempty
allow_null
new_column_at
render_menu
|These define the default values of the same attributes in all [[#Options in menus|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
|An array of ''[[#Options in menus|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
|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
|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
| 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.
|}

==View list options==
There are options which determine how the last page in the view chain should look like.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order
|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
|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
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations
|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
|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
|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
|Defaults to 86400 (one day in seconds). If the lists in this view were generated more than than many seconds ago, it is regenerated.
|}

==Options in menus==
{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields
|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
|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
|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
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode
|Possible values: ''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 below.
|- valign="top"
|hideup
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu
|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
|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.
|}

===Variations===

Variations is an array of string, such as

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

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 consists of a field name, followed by zero, one or more ''options'' separated by commas. An option is either a single attribute, or an attribute, an equal sign, and the value of the attribute. Thus
"creators_name;truncate=4,hideup"
sets the attribute value "truncate" to 4, and "hideup" to 1 (or true).

The following options are available:

{| 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
|
jump=plain

Turns of the 'jump to' text before the list of subheading navigation links.
|- 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
|}

===Phrases===

===Standard===

====heading_level====

====include====

====subheadings====

===Extra feature===

====nocount====

====nohtml====

====noindex====

Views.pl

2009-07-16T12:16:45Z

Laci@degas.ceu.hu: /* Options in ''menus'' */

== Options avaible 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

==Basic options==

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id
| (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://yourrepo/view/</nowiki>. This is the value of the ''browse_link'' attribute in [[eprint_fields.pl]]. Example:

id => 'divisions',
|- valign="top"
|fields
|(deprecated) This attribute describes the field(s) by which the view is built. It has been replaced by the more general [[#Options in menus|menus]] attribute.
|- valign="top"
|hideempty
allow_null
new_column_at
render_menu
|These define the default values of the same attributes in all [[#Options in menus|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
|An array of ''[[#Options in menus|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
|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
|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
| 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.
|}

==View list options==
There are options which determine how the last page in the view chain should look like.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order
|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
|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
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations
|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
|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
|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
|Defaults to 86400 (one day in seconds). If the lists in this view were generated more than than many seconds ago, it is regenerated.
|}

===Options in menus===
{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields
|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
|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
|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
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode
|Possible values: ''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 below.
|- valign="top"
|hideup
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu
|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
|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.
|}

===Variations===

Variations is an array of string, such as

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

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 consists of a field name, followed by zero, one or more ''options'' separated by commas. An option is either a single attribute, or an attribute, an equal sign, and the value of the attribute. Thus
"creators_name;truncate=4,hideup"
sets the attribute value "truncate" to 4, and "hideup" to 1 (or true).

The following options are available:

{| 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
|
jump=plain

Turns of the 'jump to' text before the list of subheading navigation links.
|- 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
|}

===Phrases===

===Standard===

====heading_level====

====include====

====subheadings====

===Extra feature===

====nocount====

====nohtml====

====noindex====

Views.pl

2009-07-16T12:15:43Z

Laci@degas.ceu.hu: /* View list options */

== Options avaible 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

==Basic options==

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id
| (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://yourrepo/view/</nowiki>. This is the value of the ''browse_link'' attribute in [[eprint_fields.pl]]. Example:

id => 'divisions',
|- valign="top"
|fields
|(deprecated) This attribute describes the field(s) by which the view is built. It has been replaced by the more general [[#Options in menus|menus]] attribute.
|- valign="top"
|hideempty
allow_null
new_column_at
render_menu
|These define the default values of the same attributes in all [[#Options in menus|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
|An array of ''[[#Options in menus|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
|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
|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
| 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.
|}

==View list options==
There are options which determine how the last page in the view chain should look like.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order
|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
|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
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations
|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
|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
|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
|Defaults to 86400 (one day in seconds). If the lists in this view were generated more than than many seconds ago, it is regenerated.
|}

===Options in ''menus''===
{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields
|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
|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
|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
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode
|Possible values: ''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 below.
|- valign="top"
|hideup
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu
|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
|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.
|}

===Variations===

Variations is an array of string, such as

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

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 consists of a field name, followed by zero, one or more ''options'' separated by commas. An option is either a single attribute, or an attribute, an equal sign, and the value of the attribute. Thus
"creators_name;truncate=4,hideup"
sets the attribute value "truncate" to 4, and "hideup" to 1 (or true).

The following options are available:

{| 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
|
jump=plain

Turns of the 'jump to' text before the list of subheading navigation links.
|- 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
|}

===Phrases===

===Standard===

====heading_level====

====include====

====subheadings====

===Extra feature===

====nocount====

====nohtml====

====noindex====

Views.pl

2009-07-16T12:15:08Z

Laci@degas.ceu.hu: /* Basic */

== Options avaible 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

==Basic options==

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id
| (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://yourrepo/view/</nowiki>. This is the value of the ''browse_link'' attribute in [[eprint_fields.pl]]. Example:

id => 'divisions',
|- valign="top"
|fields
|(deprecated) This attribute describes the field(s) by which the view is built. It has been replaced by the more general [[#Options in menus|menus]] attribute.
|- valign="top"
|hideempty
allow_null
new_column_at
render_menu
|These define the default values of the same attributes in all [[#Options in menus|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
|An array of ''[[#Options in menus|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
|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
|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
| 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.
|}

==View list options==
There are options which determine how the last page in the view chain should look like.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order
|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
|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
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations
|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
|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
|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
|Defaults to 86400 (one day in seconds). If the lists in this view were generated more than than many seconds ago, it is regenerated.
|}

===Options in ''menus''===
{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields
|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
|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
|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
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode
|Possible values: ''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 below.
|- valign="top"
|hideup
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu
|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
|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.
|}

===Variations===

Variations is an array of string, such as

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

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 consists of a field name, followed by zero, one or more ''options'' separated by commas. An option is either a single attribute, or an attribute, an equal sign, and the value of the attribute. Thus
"creators_name;truncate=4,hideup"
sets the attribute value "truncate" to 4, and "hideup" to 1 (or true).

The following options are available:

{| 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
|
jump=plain

Turns of the 'jump to' text before the list of subheading navigation links.
|- 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
|}

===Phrases===

===Standard===

====heading_level====

====include====

====subheadings====

===Extra feature===

====nocount====

====nohtml====

====noindex====

Views.pl

2009-07-16T12:14:50Z

Laci@degas.ceu.hu: /* Basic attributes */

== Options avaible 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 browse definition> },
{ <second browse definition> },
...
{ <last browse definition> },
];

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

Each browse definition is a collection of attributes, given as

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

(again, the ''value'' should end by a comma). The ''value'' can be
*''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 into curly brackets.
Thus the browse views definition is an array of hashes.

==Basic==

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id
| (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://yourrepo/view/</nowiki>. This is the value of the ''browse_link'' attribute in [[eprint_fields.pl]]. Example:

id => 'divisions',
|- valign="top"
|fields
|(deprecated) This attribute describes the field(s) by which the view is built. It has been replaced by the more general [[#Options in menus|menus]] attribute.
|- valign="top"
|hideempty
allow_null
new_column_at
render_menu
|These define the default values of the same attributes in all [[#Options in menus|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
|An array of ''[[#Options in menus|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
|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
|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
| 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.
|}

==View list options==
There are options which determine how the last page in the view chain should look like.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order
|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
|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
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations
|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
|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
|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
|Defaults to 86400 (one day in seconds). If the lists in this view were generated more than than many seconds ago, it is regenerated.
|}

===Options in ''menus''===
{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields
|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
|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
|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
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode
|Possible values: ''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 below.
|- valign="top"
|hideup
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu
|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
|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.
|}

===Variations===

Variations is an array of string, such as

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

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 consists of a field name, followed by zero, one or more ''options'' separated by commas. An option is either a single attribute, or an attribute, an equal sign, and the value of the attribute. Thus
"creators_name;truncate=4,hideup"
sets the attribute value "truncate" to 4, and "hideup" to 1 (or true).

The following options are available:

{| 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
|
jump=plain

Turns of the 'jump to' text before the list of subheading navigation links.
|- 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
|}

===Phrases===

===Standard===

====heading_level====

====include====

====subheadings====

===Extra feature===

====nocount====

====nohtml====

====noindex====