Setting up a client

(The first example, ac_example1.html)

Step 1. The autocompletion component is built on the of the YAHOO! User Interface Library. Include the source files for this component into your page header:

<script type="text/javascript" src="http://yui.yahooapis.com/2.3.1/build/yahoo-dom-event/yahoo-dom-event.js"></script>
<script type="text/javascript" src="http://yui.yahooapis.com/2.3.1/build/connection/connection-min.js"></script>
<script type="text/javascript" src="http://yui.yahooapis.com/2.3.1/build/container/container-min.js"></script>
<script type="text/javascript" src="http://yui.yahooapis.com/2.3.1/build/animation/animation-min.js"></script>
<script type="text/javascript" src="http://yui.yahooapis.com/2.3.1/build/autocomplete/autocomplete-min.js"></script>

Step 2. In addition include the source files for the extension (they are hosted on the E-Culture server):

<script type="text/javascript" src="http://e-culture.multimedian.nl/api/0.1/autocomplete.js"></script>
<link type="text/css" rel="stylesheet" href="http://e-culture.multimedian.nl/api/0.1/skins/mazzle/autocomplete.css">

Step 3. In your page add the following markup for the component:

<div id="elAutocomplete" />
    <input id="elInput" type="text" />
    <div id="elOutput" />
</div>

Step 4. Instantiate the component (by creating a javascript object):

<script type="text/javascript">
var Autocomplete = new Autocomplete(
    "elInput",
    ["elOutput"],
    "http://e-culture.multimedian.nl/beta/autocomplete", 
    {   filter: "type('http://e-culture.multimedian.nl/ns/getty/tgn#Place')",
        sort:   ["exact","label"]
    }, 
    {   // YUI autocomplete config see:
        // http://developer.yahoo.com/yui/autocomplete/ 
    } 
)
</script>

The elInput and elOutput refer to the IDs of the XHTML input and output container elements used in the XHTML markup. To support hierarchical sub-menus, the second argument is a list of output containers, and not a single ID as is the case in the original YUI component.

The location of the autocompletion Web service is given by an URI. Here we are using the service provided by the E-Culture server. However, the XMLHTTPRequest does not allow us to fetch data from a different domain. There are several workarounds. Here we explain two methods that use a proxy:

  1. Apache rewrite rule: copy the file htaccess.txt to the same directory as the page with your autocompletion component and rename it to .htaccess. (Make sure your apache web server allows rewrite rules.) replace, in the Autocomplete Object, http://e-culture.multimedian.nl/beta/api/autocomplete with api/autocomplete.
    (You can also at a ProxyPass to your global apache configuration.)
  2. PHP proxy: copy the file proxy.php.txt to the same directory as the page with your autocompletion component and rename it to proxy.php. Replace, in the Autocomplete Object, http://e-culture.multimedian.nl/beta/api/autocomplete with "proxy.php?yws_path=api/autocomplete".

Both methods provide a local path to the XMLHTTPRequest that is rewritten after the request is made. If you setup your own server to provide the autocompletion service these workarounds are not required. (how do I set up my own server with my own data?)

The fourth argument contains all the additional configuration parameters not part of the YUI component. The configuration options are described bellow. The fifth argument is for the YUI configuration. You can leave it empty as most of the variables are already set by the extension.

Configuring a component

The configuration in the previous examples was often not enough to sufficiently disambiguate the matching locations.