Autocompletion

From EPrints Documentation
Revision as of 19:13, 5 February 2007 by WikiSysop (talk | contribs) (Making a custom script)
Jump to: navigation, search

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects

(link to how to?)

Autocompletion in EPrints 3 consists of serveral stages.

  • A field in the workflow is configured to say what autocompletion URL to use, plus any additional parameters to pass to the script. This URL must be on the same server (eg. foo.eprints.org) but does not have to be part of the EPrints system.
  • The autocomplete script takes the text typed so far (and maybe the additional parameters) and returns a chunk of XML describing possible autocomplete options. This XML consists of a number of rows (how many is up to the script).
  • Each row contains some HTML to show the person viewing plus a magic <ul> block which is hidden from display, but is used by the autocomplete javascript to autocomplete the page.

Autocomplete Scripts

EPrints autocomplete scripts live in /opt/eprints3/cgi/users/lookup/ you can add your own here, or maybe elsewhere if, for example, you needed to use PHP.

There are several kinds of autocomplete scripts:

  • thoses that just use the existing data in your repository (these are dead easy as they work out of the box)
  • ones which use a file which you place in your repositories cfg/autocomplete/ directory.
  • more clever ones.

You may be able to find new autocomplete scripts and authority files on http://files.eprints.org/

Scripts are in (rough) order of complexity to use...

journal_by_name

Can only be used on the "publication" field. Looks up the publication in the existing publications in the repository and autocompletes the publication. If ISSN and/or publisher exist in the same input component as the journal field they will also be completed if data is available.

journal_by_issn

As above, but attached to the ISSN field.

event_by_name =

Similar to journal_by_name. Is attached to the event_title field and autocompletes from existing repository data. If they are in the same (multi) input component it will also try and autocomplete event_location, event_dates and event_type.

name

Attached to a multiple compound name/id field (eg. creators) looks up the name in the existing list in the repository. Can match on any id or given or family. Populates all parts of the current row it can.

simple_file

File needs an additional parameter to be passed to it. This is configured in the workflow. This parameter is the name of a file in the cfg/autocompete directory. This file contains a list of values which are searched (case insensitively) and matches returned. A second parameter of "mode=prefix" can be set to only match values which start with the text being typed, rather than contain it.

romeo

(not included in 3.0, expected in 3.1) This script uses the EPrints/Romeo data to provide journal autocomplete data. Should be attached to the publication field. This is almost identical to file, but inserts the required Powered by Sherpa note.

==


Making a custom script

The only parameter you need to look at is "q" which contains the text being autocompleted. For simple fields (eg. text), that is ones which only have one input-box per value. Not names, compound or pagerange etc.. the response should be of the format:

 <ul>
  <li>Human Friendly Text <ul><li id='for:value:relative:'>text-to-insert</li></ul><li>
  <li>Human Friendly Text <ul><li id='for:value:relative:'>text-to-insert</li></ul><li>
  <li>Human Friendly Text <ul><li id='for:value:relative:'>text-to-insert</li></ul><li>
  <li>Human Friendly Text <ul><li id='for:value:relative:'>text-to-insert</li></ul><li>
  etc.
 </ul>