Editing Authority Lists

[[Category:Howto]]
EPrints can autocomplete on an authority file.  The file needs to be placed in [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/autocomplete|eprints3/archives/ARCHIVEID/cfg/autocomplete/]].  

Please also see the [[Autocompletion]] reference section.

== Creating Your Own Authority File (simple) ==

If you only require to autocomplete a single input box, you can create a file containing a list of possible values, one on each line.

Imagine you want to autocomplete on projects.  Create a file with the following content:

 The Visual Apple Project
 Project Thunderbolt
 The Farm Tool Enhancement Programme
 Top Secret Defence Research

Name it ''projects.autocomplete'' and put it in

 /opt/eprints3/archives/ARCHIVEID/cfg/autocomplete

Now edit

 /opt/eprints3/archives/ARCHIVEID/cfg/workflows/eprint/default.xml

Find the input for project

 <component><field ref="projects" /></component>

Modify the line to use the simple_file script:

 <component>
  <field ref="projects" input_lookup_url="{$config{perl_url}}/users/lookup/simple_file" 
    input_lookup_params="file=projects.autocomplete"/>
 </component>

Save the file and restart the webserver.

to add a second parameter to the input_lookup_params use:
<source lang="xml">
  <component>
    <field ref="projects" input_lookup_url="{$config{perl_url}}/users/lookup/simple_file"
      input_lookup_params="file=projects.autocomplete;mode=prefix"/>
  </component>
</source>

== Creating Your Own Authority File (complex) ==

If you wish to autocomplete several input boxes inside the same component, the complexity of the authority file increases.

[http://romeo.eprints.org EPrints Romeo] is a service which provides a list of journals and their open access status.  An EPrints 3 authority file is available from their website.

=== Understanding Complex Authority Files ===

* An authority file is a set of lines.
* Each single line represents one entry in the authority file.

An entry consists of:

* A lookup string (case insensitive)
* A tab
* A <nowiki><li>...</li></nowiki> chunk of XHTML

The 'file' cgi script will take the fragment that a user has entered and match it to the lookup string.  It will return the <nowiki><li></nowiki>.

A <nowiki><li></nowiki> contains:

* A piece of XHTML to display
* A magic list items to insert into the form, inside the XHTML to display.

Here is an example from the EPrints Romeo authority file.
<pre>
 African Journal of Agricultural Research        <li style='border-right: solid 50px #30FF30' >&quot;African Journal of Agricultural Research&quot; published by &quot;Academic Publishers&quot;<br /><small>(a Green publisher)</small>ISSN: 1991-637X<ul><li id="for:value:component:_publication">African Journal of Agricultural Research</li><li id="for:value:component:_publisher">Academic Publishers</li><li id="for:value:component:_issn">1991-637X</li></ul></li>
</pre>

The first two parts of this are simple.

<pre>
 * String to Match = African Journal of Agricultural Research
 * <li> to display = <li style='border-right: solid 50px #30FF30' >&quot;African Journal of Agricultural Research&quot; published by &quot;Academic Publishers&quot;<br /><small>(a Green publisher)</small>ISSN: 1991-637X</li>
</pre>

The list is a little more complex:

<pre>
<ul>
  <li id="for:value:component:_publication">African Journal of Agricultural Research</li>
  <li id="for:value:component:_publisher">Academic Publishers</li>
  <li id="for:value:component:_issn">1991-637X</li>
</ul>
</pre>

This contains the values which will be inserted into the 'publication', 'publisher' and 'issn' fields in this component.  Note that even though this <nowiki><ul></nowiki> is inside the <nowiki><li></nowiki> which will be displayed, it will not be seen by the user.  
On [[Understanding_IDs_in_Workflow_Forms|Understanding IDs in Workflow Forms]] a detailed explanation of the ID generation is given.

=== Using the EPrints Romeo Authority File ===

First get the authority file and put it in the right place:

 %cd /opt/eprints3/archives/ARCHIVEID/cfg/autocomplete
 %wget romeo.eprints.org/romeo_journals.autocomplete

Now the file needs to be linked into the workflow.  Edit the file

 /opt/eprints3/archives/ARCHIVEID/cfg/workflows/eprint/default.xml

Find the input for Publication Title

 <field ref="publication" required="yes" input_lookup_url="{$config{perl_url}}/users/lookup/journal_by_name" />

By default, this is set to use the 'journal_by_name' script, which searches records already in the repository.  However, now that we have a long list of journals that we've downloaded from Romeo, we'd like to use that instead.  Modify the line:

  <field ref="publication" required="yes" input_lookup_url="{$config{perl_url}}/users/lookup/file" input_lookup_params="file=romeo_journals.autocomplete"/>

The EPrints Romeo is derived from [http://www.sherpa.ac.uk/ Sherpa] data, and has some licensing requirements.  Edit the file

 /opt/eprints3/archives/ARCHIVEID/cfg/workflows/eprint/default.xml

Find the lines

 <component type="Field::Multi">
   <title>Publication Details</title>

And add the following before it to display the Sherpa logo and reference:

<pre>
 <epc:if test="type = 'article'">
   <component type="XHTML">
     <img src='http://www.sherpa.ac.uk/images/romeotiny.jpg' style="float: left; padding-right: 1em"/>
     Journal autocompletion information is derived from the <a href="http://www.sherpa.ac.uk/romeo.php">RoMEO</a>
     database which is compiled by <a href="http://www.sherpa.ac.uk">SHERPA</a> and has been modified for use here.
   </component>
 </epc:if>
</pre>

All that is left now is to restart the webserver.

== Autocompleting on a Database Table ==

There are two ways to autocomplete from a database table.  They are similar to the two above methods for autocomplete.

=== Simple SQL Autocompletion ===

In your repository database, create a table named 'ac_projects' containing one column named 'value'.

 mysql> CREATE TABLE ac_projects (
     -> value TEXT
     -> );

Insert some values into the table.

 mysql> INSERT INTO ac_projects VALUES ("The Visual Apple Project");
 mysql> INSERT INTO ac_projects VALUES ("Project Thunderbolt");
 mysql> INSERT INTO ac_projects VALUES ("The Farm Tool Enhancement Programme");
 mysql> INSERT INTO ac_projects VALUES ("Top Secrent Defence Research");

Now edit

 /opt/eprints3/archives/ARCHIVEID/cfg/workflows/eprint/default.xml

Find the input for project

 <component><field ref="projects" /></component>

Modify the line to use the simple_sql script:

 <component>
  <field ref="projects" input_lookup_url="{$config{perl_url}}/users/lookup/simple_sql" input_lookup_params="table=projects"/>
 </component>

Save the file and restart the webserver.

=== Complex SQL Autocompletion ===

Setting up complex SQL Autocompletion (to fill in multiple fields) is identical to setting up Simple SQL Autocompletion, but with the following changes:

* Complex SQL Autocompletion requires a table with two columns, one called 'value' (as above in Simple SQL) and one called 'xml'.  The 'xml' column contains data in the same format as would be found in the 'Complex Authority File' (described above) after the 'tab'.

* Instead of 'input_lookup_url="{$config{perl_url}}/users/lookup/simple_sql"', use 'input_lookup_url="{$config{perl_url}}/users/lookup/sql"'