Editing How to (section)

===Add a new Field===
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 ArchiveMetafieldConfig.pm : Add the field to the appropriate part of ArchiveMetafieldConfig.pm (the "eprint" section in our example)
 { 
   name => "local", 
   type => "set", 
   input_rows => 1, 
   options => [ 
     "yes", 
     "no", 
     "partial" 
   ] 
 }
input_rows being set to one will make it appear as a pull-down menu.

; Add the Field to metadata-types.xml : 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 metadata-types.xml (this can be changed on a live system without any serious consequences).
 &lt;field name="local" required="yes" /&gt;

; 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).
 &lt;ep:phrase ref="eprint_fieldname_local"&gt;Produced Locally&lt;/ep:phrase&gt;
 &lt;ep:phrase ref="eprint_fieldhelp_local"&gt;Please indicate if this item was produced in the foo organisation, or not.&lt;/ep:phrase&gt;
 &lt;ep:phrase ref="eprint_fieldopt_local_yes"&gt;produced locally&lt;/ep:phrase&gt;
 &lt;ep:phrase ref="eprint_fieldopt_local_no"&gt;not produced locally&lt;/ep:phrase&gt;
 &lt;ep:phrase ref="eprint_fieldopt_local_partial"&gt;only partially produced locally&lt;/ep:phrase&gt;

====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 change that entry to:
 <ep:citation type="eprint_techreport">
   <ep:linkhere>
     <span class="citation">&authors; <ep:ifset name="year">(&year;) </ep:ifset> &title;. Technical Report<ep:ifset name="reportno"> &reportno;</ep:ifset><ep:ifset name="department">, &department;</ep:ifset><ep:ifset name="institution">, &institution;</ep:ifset>. &local;.</span>
   </ep:linkhere>
 </ep:citation> 
All we've done is add <tt>&local;.</tt> to the end. It's not inside <tt> <ep:ifset name="local"> </tt> 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 ArchiveRenderConfig.pm and select the appropriate function, either eprint_render or user_render.
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:
 &lt;ep:phrase ref="page:itemnotlocal"&gt;
   &lt;p&gt;This item was &lt;pin ref="status" /&gt;.&lt;/p&gt;
 &lt;/ep:phrase&gt;
And to the ArchiveRenderConfig.pm 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.

; Add extra Validation Routines : If you need to validate this field in a special way, add code into ArchiveValidateConfig.pm
; Add it to the OAI metadata (eprints only) : If this field can be rendered into Dublin Core (or other metadata formats you are using) then add it to the appropriate place in the ArchiveOAIConfig.pm file.
; Add a browse view (eprints only) : If you want to be able to browse this values items. See elsewhere in the docs for how to do this.

If you add a field you will need to run erase_archive and create_tables before you will see a change. EPrints will fail to run if you change the fields and do rebuild the tables.