View source for HOW TO: Add a New Field

[[Category:Configuration]]
[[Category:Howto]]
Adding a new field to EPrints 3 essentially works like for EPrints 2.3. Just the files to edit and the syntax somewhat changed. For EPrints 2.3 see [http://www.eprints.org/documentation/tech/php/howto.php#how_to__add_a_new_field this page].

This covers adding a new field to a new system, not a live system. It is possible to add a new field to a live system but involves SQL hacking.

In this example we add a new "set" field called "local" which will have 3 options "yes","no" and "partial" - this will indicate if the item in question was produced in our organisation or not.

= Add the Field to archives/ARCHIVEID/cfg/cfg.d/eprint_fields.pl =

Add the field to the appropriate part of eprint_fields.pl  

 {
   'name' => 'local',
   'type' => 'set',
   'options' => [
         'yes',
         'no',
         'partial',
         ],
   'input_rows' => 1,
 },

input_rows being set to one will make it appear as a pull-down menu.

= Add the Field to Workflow =

If you want the user to be able to edit this field for any or all types of eprint/user then you need to add it to each appropriate type in archives/ARCHIVEID/cfg/workflows/eprint/default.xml (this can be changed on a live system without any serious consequencies). Add the following to an approriate place in the core section:

 <component><field ref="local" required="yes" /></component>

= Add the Field Information to the Archive Phrase File(s) =

Normally we just need to add fieldname and fieldhelp, but this is an option field so we need to add names for each option. If we run the archive in more than one language then we add this to each phrase file (but in the appropriate language). Phrases for eprint fields are found in archives/ARCHIVEID/cfg/lang/en/phrases/eprint_fields.xml.

     <epp:phrase id="eprint_fieldname_local">Produced Locally</epp:phrase>
     <epp:phrase id="eprint_fieldhelp_local">Please indicate if this item was 
          produces in the foo organisation, or not.</epp:phrase>
     <epp:phrase id="eprint_fieldopt_local_yes">produced locally</epp:phrase>
     <epp:phrase id="eprint_fieldopt_local_no">not produced locally</epp:phrase>
     <epp:phrase id="eprint_fieldopt_local_partial">only partially produced 
          locally</epp:phrase>

== Other things you may wish to change after adding a new field ==

= Add it to the citations file =

This is optional, only do this if you want it to appear in the citated forms. 

In our example case we only want this to appear when citing technical reports, so we add the following to  archives/ARCHIVEID/cfg/lang/en/phrases/eprint_fields.xml:

 <if test="type = 'techreport'">     
   <print expr="local"/>
 </if>

The <print> element is not inside <if test="local"></if> as it is a required field and will (should) always be set.

= Add it to the the Abstract (or View-User) page =

This is also optional. If you want it to appear on the web page for this item then edit either archives/ARCHIVEID/cfg/cfg.d/eprint_render.pl or archives/ARCHIVEID/cfg/cfg.d/user_render.pl. 

In our example we only want to mention items if an item was not produced locally. We'll add it below the documents and above the abstract...

Single language example:

     if( $eprint->get_value( "local" ) ne "yes" )
     {
          # don't need to "my $p" as it's done earlier.
          $p = $session->make_element( "p" );
          $p->appendChild( $session->make_text( "This item was " ) );
          $p->appendChild( $eprint->render_value( "local" ) );
          $p->appendChild( $session->make_text( "." ) );

          # Append our new paragraph to the page.
          $page->appendChild( $p );
     }

Multiple-language example:

If you want to make it handle more than language then we'll need to use the archive phrase file - we would add something like this to each languages file:

     <epp:phrase id="page:itemnotlocal"><p>This item was <pin ref="status" />.</p></epp:phrase>

And to the archives/ARCHIVEID/cfg/cfg.d/eprint_render.pl file:

     if( $eprint->get_value( "local" ) ne "yes" )
     {
          my $localmsg = $session->html_phrase(
                 "page:itemnotlocal",
                 status=>$eprint->render_value( "local" ) );
          $page->appendChild( $localmsg );
     }

You may prefer to use this method even if you are only using a single language.