Difference between revisions of "Adding an Auto-Completer to a non-workflow page"

From EPrints Documentation
Jump to: navigation, search
(Input with return locations and javascript call)
Line 78: Line 78:
 
# <code>"&amp;field=name"</code> is ''extra_params'' - a way of passing extra cgi parameters to the script
 
# <code>"&amp;field=name"</code> is ''extra_params'' - a way of passing extra cgi parameters to the script
  
----
+
=====The Script=====
 +
The final part of this loop is the back-end script, the bit that does the work of looking up ''things'' and returning ''stuff'' to the page.
  
==Recap: Auto-completion within a workflow==
+
With the EPrints Auto-Completer, the format for this return is fairly simple:
In a workflow, adding an auto-completer is relatively sinple:
+
<pre>
+
  <field ref="publication"
+
          input_lookup_url="{$config{perl_url}}/get_journals"/>
+
</pre>
+
.... 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:
+
  
 
<pre>
 
<pre>
   <ul class="journals">
+
   <ul>
     <li class="">Some informative text<br />
+
     <li>Some informative text<br />
 
       (with something else on a new line
 
       (with something else on a new line
 
     <ul>
 
     <ul>
       <li id="for:value:component:_publication">Fandangle</li>
+
       <li id="for:value:component:_oname">Fandangle</li>
 
       <li id="for:value:component:_diddle">Fruit Loops</li>
 
       <li id="for:value:component:_diddle">Fruit Loops</li>
 
       <li id="for:value:component:_a1">Another One</li>
 
       <li id="for:value:component:_a1">Another One</li>
Line 102: Line 94:
 
     </ul>
 
     </ul>
 
     </li>
 
     </li>
     <li class="">
+
     <li>
 
       .....
 
       .....
 
     </li>
 
     </li>
 
   </ul>
 
   </ul>
 
</pre>
 
</pre>
 +
 +
To break this down, we're looking at a list of returns, each of which has a list of "fill-in" items
 +
 +
Lets break the list down into parts:
 +
<pre>
 +
  <ul>
 +
    <li>Some informative text<br />
 +
      (with something else on a new line</li>
 +
    <li>
 +
      Another entry
 +
    </li>
 +
    <li>
 +
      The Third Way
 +
    </li>
 +
    <li>
 +
      Option Four
 +
    </li>
 +
  </ul>
 +
</pre>
 +
 +
This is the list of items to display to the user - in this case, 4 items.
 +
What we don't have here is the data to be filled in, once a selection has been made. That looks like this:
 +
<pre>
 +
    <li>Some informative text<br />
 +
      (with something else on a new line
 +
    <ul>
 +
      <li id="for:value:component:_oname">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>
 +
</pre>
 +
Each item has a sub-list, where each item has a ''magic incantation'' for it's id: <code>for:value:component:</code> is the bit that the EPrints Auto-Completer code looks for, and <code>_''xxx''</code> names the sub_element that the data does into.
 +
 +
Given the <code>ep_autocompeter</code> call above, we have defined a ''component'' of <code>oarj</code>. Thus:
 +
* <code><li id="for:value:component:_oname">Fandangle</li></code> puts "Fandangle" in the element <code>id="oarj_oname"</code>
 +
* <code><li id="for:value:component:_diddle">Fruit Loops</li></code> puts "Fruit Loops" in the element <code>id="oarj_diddle"</code>
 +
* <code><li id="for:value:component:_a1">Another One</li></code> puts "Another One" in the element <code>id="oarj_a1"</code>
 +
* <code><li id="for:value:component:_b2">Befuddled Too</li></code> puts "Befuddled Too" in the element <code>id="oarj_b2"</code>
 +
'''Note''': If the element does not exist, then the value is ignored... sensibly.
 +
 +
----
 +
 +
==Recap: Auto-completion within a workflow==
 +
In a workflow, adding an auto-completer is relatively sinple:
 +
<pre>
 +
  <field ref="publication"
 +
          input_lookup_url="{$config{perl_url}}/get_journals"/>
 +
</pre>
 +
.... 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:
 +
 +
  
 
.... where the <code>_''xxx''</code> bit is the name of the input field to be filled in when the entry is selected.
 
.... where the <code>_''xxx''</code> bit is the name of the input field to be filled in when the entry is selected.

Revision as of 10:57, 12 April 2010

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 incantation - 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 incantation - 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
The Script

The final part of this loop is the back-end script, the bit that does the work of looking up things and returning stuff to the page.

With the EPrints Auto-Completer, the format for this return is fairly simple:

   <ul>
    <li>Some informative text<br />
      (with something else on a new line
     <ul>
      <li id="for:value:component:_oname">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>
      .....
    </li>
   </ul>

To break this down, we're looking at a list of returns, each of which has a list of "fill-in" items

Lets break the list down into parts:

   <ul>
    <li>Some informative text<br />
      (with something else on a new line</li>
    <li>
      Another entry
    </li>
    <li>
      The Third Way
    </li>
     <li>
      Option Four
    </li>
  </ul>

This is the list of items to display to the user - in this case, 4 items. What we don't have here is the data to be filled in, once a selection has been made. That looks like this:

    <li>Some informative text<br />
      (with something else on a new line
     <ul>
      <li id="for:value:component:_oname">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>
 

Each item has a sub-list, where each item has a magic incantation for it's id: for:value:component: is the bit that the EPrints Auto-Completer code looks for, and _xxx names the sub_element that the data does into.

Given the ep_autocompeter call above, we have defined a component of oarj. Thus:

  • Fandangle
  • puts "Fandangle" in the element id="oarj_oname"
  • Fruit Loops
  • puts "Fruit Loops" in the element id="oarj_diddle"
  • Another One
  • puts "Another One" in the element id="oarj_a1"
  • Befuddled Too
  • puts "Befuddled Too" in the element id="oarj_b2"

Note: If the element does not exist, then the value is ignored... sensibly.


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:


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