Adding an Auto-Completer to a non-workflow page

NOTE: THIS IS INCOMPLETE - CAN SOMEONE FILL IN THE DETAILS??

Using the EPrints application framework, we can create auto-completion for any input, but we need to understand how the system works, and build the pages by the rules.

How Auto-Completion works, in general

Understanding AJAX Auto-Completion is a bit of a circular process, so bear with me.

You need three things

1. An Auto-Completer "engine" (a complex Javascript code-base)
2. A script to do the lookup work & return stuff
3. (x)html structure to accept the returned stuff

The process:

• When the user types into an input box, a javascript event is triggered which sends that input value to a script.
• The script returns an unordered list, which the Auto-Completer code displays for the user to select from
• The Javascript engine then fills in the identified inputs with the selected values.

An example

This is a very simple example.

Input

Here we have an input:

<input type="textfield" size="25" id="oarj_oname"
       name="organisation_name"
       onkeypress="return EPJS_block_enter( event )" />

There are two important factors here:

• id="oarj_oname" defines the identity of the element, which we need to read the "seed" value from, and fill in with the selected data. This element actually breaks down into two sub-parts:
  • "oarj" is the component
  • "oname" gives the part of the components
• onkeypress="return EPJS_block_enter( event )" is the EPrints application magic incantation" to trigger some javascript when the user types something into the input box.

Input with return locations

What we also need the (x)html to receive the output of the mysterious javascript call:

 <input type="textfield" onkeypress="return EPJS_block_enter( event )"
        size="25" id="oarj_oname" name="organisation name">
 <div style="display: none;" id="oarj_oname_drop" class="ep_drop_target"></div>
 <div style="display: none;" id="oarj_oname_drop_loading" class="ep_drop_loading">
  <img src="/style/images/loading.gif" alt="" style="border: 0pt none ;">
 </div>

Some of this is more magic incantation There are two divs - one to accept the return from the AJAX magic, and one to display the "I'm doing stuff" graphic.

Their ids are declared in the Javascript call, however they should be derived from the id of the input field:

• "oarj_oname_drop" is the named element to receive the output of the javascript
• "xxxx_loading" is the element that displays the "I'm busy" graphic. It's name is specific: it is the same as the drop element, with _loading appended.

Input with return locations and javascript call

Finally, we need to append the bit that makes the Auto-Completer call:

 <input type="textfield" onkeypress="return EPJS_block_enter( event )"
        size="25" id="oarj_oname" name="organisation name">
 <div style="display: none;" id="oarj_oname_drop" class="ep_drop_target"></div>
 <div style="display: none;" id="oarj_oname_drop_loading" class="ep_drop_loading">
  <img src="/style/images/loading.gif" alt="" style="border: 0pt none ;">
 </div>
 <script type="text/javascript">
 // <![CDATA[
 ep_autocompleter( "oarj_oname", "oarj_oname_drop", "/cgi/get_orgs",
                   {relative: "oarj_oname", component: "oarj"  },
                 [ $("oarj_oname")], [], "&field=name")
 // ]]></script>

The javascript has multiple fields:

1. "oarj_oname" is the id of the element that the Auto-Completer reads from
2. "oarj_oname_drop" is the id of the element the return data is put into
3. "/cgi/get_orgs" is the name of the script called to get the return data
4. {relative: "oarj_oname", component: "oarj" } is magic incalntation - referred to as basenames in the javascript code, I give it the id of the element and the component level name
5. [ $("oarj_oname")] more magic incalntation - width_of_these ??
6. [] would be the fields_to_send
7. "&field=name" is extra_params - a way of passing extra cgi parameters to the script

---

Recap: Auto-completion within a workflow

In a workflow, adding an auto-completer is relatively sinple:

   <field ref="publication"
          input_lookup_url="{$config{perl_url}}/get_journals"/>

.... and the EPrints application takes care of all the "stuff" on the main page.

The return format is fairly simple too: An unordered list of records to display, with each "fill-in" item part of a sub-list:

   <ul class="journals">
    <li class="">Some informative text<br />
      (with something else on a new line
     <ul>
      <li id="for:value:component:_publication">Fandangle</li>
      <li id="for:value:component:_diddle">Fruit Loops</li>
      <li id="for:value:component:_a1">Another One</li>
      <li id="for:value:component:_b2">Befuddled Too</li>
     </ul>
    </li>
    <li class="">
      .....
    </li>
   </ul>

.... where the _xxx bit is the name of the input field to be filled in when the entry is selected.