Difference between revisions of "HOW TO: Add a New Field"

From EPrints Documentation
Jump to: navigation, search
 
(Removed mention of needing to do SQL hacking. Referred to the need to run epadmin update if the repository is live.)
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
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.
+
This covers adding a new field to a new system. When adding to a live system, you may wish to follow up with an epadmin update command, as documented in [[Adding a Field to a Live Repository]].
  
 
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.
 
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.
Line 91: Line 90:
  
 
You may prefer to use this method even if you are only using a single language.
 
You may prefer to use this method even if you are only using a single language.
 +
 +
[[Category:Metadata Fields]] [[Category:Customisation]]

Latest revision as of 17:17, 17 July 2023

This covers adding a new field to a new system. When adding to a live system, you may wish to follow up with an epadmin update command, as documented in Adding a Field to a Live Repository.

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

This item was <pin ref="status" />.

</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.