Editing Using Internal IDs for Staff Browse Views (section)

== Procedure ==
'''N.B.''' The following instructions assume EPrints has been installed in the directory '''/opt/eprints3/''' some EPrints install will appear under '''/usr/share/eprints3/''' or other locations.  Make sure you amend these as appropriate for your instaltion

=== Add Internal ID field to User ===
1. In your archive's '''cfg/cfg.d/user_fields.pl''' file ad the following snippet of code at the end:

 push @{$c->{fields}->{user}},
 {
   name => 'internalid',
   type => 'id',
 };

2. Run EPrints database update command to add this new field:

 /opt/eprints3/bin/epadmin update ARCHIVENAME

3. Assuming the above has been successful add the phrases required for this new field to '''cfg/lang/en/phrases/local.xml'''

 <epp:phrase id="user_fieldname_internalid">Internal ID</epp:phrase>
 <epp:phrase id="user_fieldhelp_internalid">Unique ID used to identify a user, used by <epc:phrase ref="archive_name" /></epp:phrase>

4. Test that EPrints is happy with these changes and if so reload Apache:
 /opt/eprints3/bin/epadmin test ARCHIVENAME
 apachectl graceful


=== Add Internal ID to creators/editors/contributors fields for an EPrint ===
1. Add the following code the a file at '''/opt/eprints3/lib/plugins/EPrints/MetaField/Internalidname.pm''':

 package EPrints::MetaField::Internalidname;
 
 use strict;
 use warnings;
 
 use EPrints::MetaField::Text;
 
 BEGIN
 {
   our( @ISA );
   @ISA = qw( EPrints::MetaField::Text );
 }
 
 sub _get_name
 {
   my( $self, $session, $internalid ) = @_;
 
   my $format = $session->config( 'internalid_to_name', 'format' );
 
   return unless defined $format;
 
   if( $session->can_call( 'internalid_to_name', 'parser' ) )
   {
     my $name = $session->call( [ 'internalid_to_name', 'parser' ], $session, $internalid );
     return $session->render_name( $name, $format ) if defined $name;
   }
 
   return;
 }
 
 sub get_value_label
 {
   my( $self, $session, $value ) = @_;
 
   my $name = $self->_get_name( $session, $value );
   return $name if defined $name;
 
   return $session->make_text( $value );
 }
 
 sub ordervalue_basic
 {
   my( $self, $value, $session, $langid ) = @_;
 
   my $name = $self->_get_name( $session, $value );
   return EPrints::Utils::tree_to_utf8( $name ) if defined $name;
  
   return $value;
 }
 
 sub render_single_value
 {
   my( $self, $session, $value ) = @_;
   return $self->get_value_label( $session, $value );
 }
 
 1;

2. Edit your archive's '''cfg/cfg.d/eprint_fields.pl'''.  Under the field named '''creators''', you will see a block labelled '''fields'''.  Copy and paste the block that has the '''sub_name''' '''id''' and copy and paste it just before the end '''fields''' block, ensuring to add a comma a comma prior to this.  Then modify the '''sub_name''  from '''id''' to ''internalid'''.  The creators block should then look something like below:

 {
   name => 'creators',
   type => 'compound',
   multiple => 1,
   fields => [
     {
       sub_name => 'name',
       type => 'name',
       hide_honourific => 1,
       hide_lineage => 1,
       family_first => 1,
     },
     {
       sub_name => 'id',
       type => 'text',
       input_cols => 20,
       allow_null => 1,
     },
     {
       sub_name => 'internalid',
       type => 'internalidname',
       input_cols => 10,
       allow_null => 1,
       render_single_value => 'render_internalid',
     },
   ],
 },

3. Repeat this change with the '''contributors''' and '''editors'' fields.


4. Create a file called '''internalid_to_name.pl''' in '''cfg/cfg.d/''' of your archive, with the following contents:

 $c->{internalid_to_name}->{parser} = sub
 {
   my( $session, $internalid ) = @_;
   return unless EPrints::Utils::is_set( $internalid );
 
   my $user_ds = $session->get_repository->get_dataset( "user" );
   my $user_search = new EPrints::Search( session => $session, dataset => $user_ds );
   $user_search->add_field( $user_ds->get_field( "internalid" ), $internalid );
   my $users = $user_search->perform_search;
   return unless $users->count() > 0;
 
   return $users->item( 0 )->get_value("name");
 };
 
 $c->{internalid_to_name}->{format} = 0; # family, given
 
 $c->{render_internalid} = sub
 {
   my( $session, $field, $value, $obj ) = @_;
 
   my $fragment = $session->make_doc_fragment;
   $fragment->appendChild($session->xml->create_text_node($value));
   return $fragment;
 }

5. Run EPrints database update command to add these new sub-fields:

 /opt/eprints3/bin/epadmin update ARCHIVENAME 

6. Assuming the above has been successful add the phrases required for this new field to '''cfg/lang/en/phrases/local.xml'''

 <epp:phrase id="eprint_fieldname_creators_internalid">Internal ID</epp:phrase>
 <epp:phrase id="eprint_fieldhelp_creators_internalid">Unique ID used to identify a user, used by <epc:phrase ref="archive_name" /></epp:phrase>
 <epp:phrase id="eprint_fieldname_contributors_internalid">Internal ID</epp:phrase>
 <epp:phrase id="eprint_fieldhelp_contributors_internalid">Unique ID used to identify a user, used by <epc:phrase ref="archive_name" /></epp:phrase>
 <epp:phrase id="eprint_fieldname_editors_internalid">Internal ID</epp:phrase>
 <epp:phrase id="eprint_fieldhelp_editors_internalid">Unique ID used to identify a user, used by <epc:phrase ref="archive_name" /></epp:phrase>

7. Test that EPrints is happy with these changes and if so reload Apache:
 /opt/eprints3/bin/epadmin test ARCHIVENAME
 apachectl graceful


=== Add Autocompletion for creators/editors/contributors fields ===
1. Create a new file in your archive under '''cgi/users/lookup/staffinternal''' and edit:

 use EPrints;
 use strict;
 
 my $session = EPrints::Session->new();
 
 my $content = "text/xml";
 $session->send_http_header( content_type=>$content );
 my $family = $session->param( "_name_family" );
 my $given = $session->param( "_name_given" );
 my $id = $session->param( "_id" );
 my $internalid = $session->param( "_internalid" );
 
 my $database = $session->get_database;
 my $dataset = $session->get_repository->get_dataset( "user" );
 my $name_field = $dataset->get_field( "name" );
 my $email_field = $dataset->get_field( "email" );
 my $internalid_field = $dataset->get_field( "internalid" );
 
 # the field to use as the creator ID
 my $id_fieldname = "email";
 my $id_field = $dataset->get_field( $id_fieldname );
 
 my @fields = ($name_field->get_sql_names, $id_field->get_sql_names, $email_field->get_sql_names, $internalid_field->get_sql_names);
 
 my $Q_table = $database->quote_identifier($dataset->get_sql_table_name);
 my $Q_usertype = $database->quote_identifier( "usertype" );
 my $Q_id = $database->quote_identifier( $id_fieldname );
  
 my $sql = "SELECT " . join(",", map { $database->quote_identifier($_) } @fields ) .
   " FROM $Q_table " .
   " WHERE $Q_usertype != ".$database->quote_value( "minuser" ) .
   " AND $Q_id IS NOT NULL ";
 
 if( EPrints::Utils::is_set( $family ) )
 {
   $sql .= " AND ".$database->quote_identifier("name_family").$database->sql_LIKE().$database->quote_value(EPrints::Database::prep_like_value($family).'%');
 }
 if( EPrints::Utils::is_set( $given ) )
 {
   $sql .= " AND ".$database->quote_identifier("name_given").$database->sql_LIKE().$database->quote_value(EPrints::Database::prep_like_value($given).'%');
 }
 if( EPrints::Utils::is_set( $id ) )
 {
   $sql .= " AND ".$database->quote_identifier($id_field->get_name).$database->sql_LIKE().$database->quote_value(EPrints::Database::prep_like_value($id).'%');
 }
 if( EPrints::Utils::is_set( $internalid ) )
 {
   $sql .= " AND ".$database->quote_identifier($internalid_field->get_name).$database->sql_LIKE().$database->quote_value(EPrints::Database::prep_like_value($internalid).'%'); 
 }
 
 $sql .= " ORDER BY " .
   $database->quote_identifier("name_family").",".
   $database->quote_identifier("name_given");
 
 my @rows;
 
 my $sth = $session->get_database->prepare_select( $sql, 'limit' => 40 );
 $session->get_database->execute( $sth , $sql );
 while( my @row = $sth->fetchrow_array )
 {
   my $name = $name_field->value_from_sql_row( $session, \@row );
   my $email = $email_field->value_from_sql_row( $session, \@row );
   my $id = $id_field->value_from_sql_row( $session, \@row );
   my $internalid = $internalid_field->value_from_sql_row( $session, \@row );
 
   my $item = {};
   push @rows, $item;
 
   my $frag = $session->make_doc_fragment;
   $frag->appendChild( $name_field->render_single_value( $session, $name ) );
   if ( EPrints::Utils::is_set( $internalid ) ) 
   {
     $frag->appendChild( $session->make_text( " [" ) );
     $frag->appendChild( $email_field->render_single_value( $session, $internalid ) );
     $frag->appendChild( $session->make_text( "]" ) );
   }
   if ( EPrints::Utils::is_set( $email ) ) 
   {
     $frag->appendChild( $session->make_text( " (" ) );
     $frag->appendChild( $email_field->render_single_value( $session, $email ) );
     $frag->appendChild( $session->make_text( ")" ) );
   }
   
   $item->{xhtml} = $frag;
   $item->{values} = [
     "for:value:relative:_name_family" => $name->{family},
     "for:value:relative:_name_given" => $name->{given},
     "for:value:relative:_name_honourific" => $name->{honourific},
     "for:value:relative:_name_lineage" => $name->{lineage},
     "for:value:relative:_internalid" => $internalid,
     "for:value:relative:_id" => $id,
   ];
 }
 
 $sth->finish();
 my $ul = EPrints::Extras::render_lookup_list( $session, \@rows );
 $session->send_http_header( content_type => "text/xml; charset=UTF-8" );
 binmode(STDOUT,":utf8");
 print <<END;
 <?xml version="1.0" encoding="UTF-8" ?>
 
 END
 print EPrints::XML::to_string( $ul, "utf-8", 1 );
 EPrints::XML::dispose( $ul );
 $session->terminate;


2. Edit your archive's '''cfg/workflows/eprint/default.xml''' and replace '''/users/lookup/name''' with '''/users/lookup/staffinternal''' where it appears as the '''input_lookup_url''' for '''creators''', '''editors''', and '''contributors'''.  N.B. each of these fields may appear more than once in this file due to the use of conditional statements.

3. Now test the configuration and although it should not be necessary ,it is worth gracefully reloading Apache to make sure the latest configuration is loaded.
 /opt/eprints3/bin/epadmin test ARCHIVENAME
 apachectl graceful

=== Create Browse View based on Internal IDs ===
1. Edit your archives '''cfg/cfg.d/views.pl''' and add the following code snippet at the end of the file:

 push @{ $c->{browse_views} }, (
 {
   id => "creators_internalid",
   allow_null => 0,
   hideempty => 1,
   menus => [
     {
       fields => [ "creators_internalid", "contributors_internalid", "editors_internalid"  ],
       new_column_at => [1, 1],
       mode => "sections",
       open_first_section => 1,
       group_range_function => "EPrints::Update::Views::cluster_ranges_30",
       grouping_function => "EPrints::Update::Views::group_by_a_to_z",
     },
   ],
   order => "-date/title",
   variations => [
     "type",
     "date;truncate=4,reverse",
     "DEFAULT",
   ],
 });

2. Add the following phrase to your archives's '''cfg/lang/en/phrases/local.xml''':

 <epp:phrase id="viewname_eprint_creators_internalid">Internal Creators</epp:phrase>

3. Test that EPrints is happy with these changes and if so reload Apache:
 /opt/eprints3/bin/epadmin test ARCHIVENAME
 apachectl graceful

4. Request the path '''/views/creators_internalid''' under your repository's hostname in a web browser (e.g. http://example.eprints.org/views/creators_internalid).