source: MILK/trunk/milk_server/milk_server/controllers/vocabsearch/README.txt @ 5201

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/MILK/trunk/milk_server/milk_server/controllers/vocabsearch/README.txt@5201
Revision 5201, 3.1 KB checked in by cbyrom, 11 years ago (diff)

Add functionality to allow vocab term searches to be done via an
ajax enabled, autocomplete text input. Add new controller and template
packages for this as well as javascript and style sheets. Also update
routing and add (commented out) example of usage in layout + add
documentation on how to use.

Line 
1Using the vocab server autocomplete search box
2------------------------
3To set up a text field to use as an autocomplete search box, complete the following:
4
5i) In the (genshi) template which is to use the box, add the following:
6
7<xi:include href="vocabsearch/vocabsearch.html" />
8
9ii) Now, when the box is needed in the template, insert:
10
11<div py:replace="vocabSearchAutoComplete()" />
12
13This will insert a table with two columns:
14
15Vocab Term: <input text box>
16
17Now, as long as the MILK stack has the vocabsearch codebase intact (see below), you
18should have a working autocomplete search box. 
19
20Notes on use
21---------------
22
23Codebase
24============
25The functionality requires the following files to work:
26
27milk_server/controllers/vocabsearch/vocabsearch.py
28
29- the server controller with a single method, doVocabSearch.  This accepts input
30search data from the autocomplete control and looks it up on the vocab server.  NB,
31to improve efficiency of the control, search inputs and their results are cached
32on the server.
33
34milk_server/templates/vocabsearch/vocabsearch.html
35
36- the template representing the autocomplete control.  At present this uses a mixture of
37js files from the MILK codebase and from the yahoo website - this probably should change
38to standardise on one or the other at some point.  NB, there doesn't seem to be much
39overhead in loading all files from the website, although this then makes it
40difficult for use to guarantee versioning of the scripts.
41
42milk_server/public/js/autocomplete.js
43
44- the javascript that defines the autocomplete control.  Note, there are several
45configuration options set on this - e.g.
46    oAC.minQueryLength = 2;
47   
48- see, http://developer.yahoo.com/yui/docs/YAHOO.widget.AutoComplete.html, for
49full details of the available configuration options.
50
51milk_server/public/layout/style/autocomplete.css
52- a simple stylesheet that is required to avoid the control stretching to the
53full page width
54
55Troubleshooting
56=================
57i) The initial use of the control can be a little slow - usually because there
58are lots of potential results to retrieve.  This could be avoided by forcing the
59minimum number of letters to be typed before a lookup is done to be more than 2.
60The server caching of results, however, means that as long as the server isn't
61being constantly restarted, it'll start to build up a cache of results and the
62control will perform much faster.
63ii) If the control doesn't behave properly, there is probably an issue with the
64stylesheets; it is worth playing around with the style (i.e. class or id settings)
65of the parent elements.  Funny behaviour I've seen due to style clashes include:
66
67- box being stretched to page width
68- box input text ('type in some text here to search for vocab terms' set in vocabsearch.html)
69being displayed.  This is just used to set the width of the text box and shouldn't be seen
70- drop down list of results appearing as a bullet point list in page
71
72iii) The element names of 'myInput' and 'myContainer', used in the vocabsearch template are
73referenced directly by the autocomplete.js file - so if they change, they must be changed in
74both places.
Note: See TracBrowser for help on using the repository browser.