The Javascript
Regular download
You can either download the javascript code and put it into your own site or you can leave it to Autocompeter to host it on its CDN (backed by AWS CloudFront). To download, go to:
https://raw.githubusercontent.com/peterbe/autocompeter/master/public/dist/autocompeter.min.js
This is the optimized version. If you want to, you can download the non-minified file instead which is easier to debug or hack on.
Bower
You can use Bower to download the code too.
This will only install the files in a local directory called
bower_components
. This is how you download and install with Bower:
bower install autocompeter
ls bower_components/autocompeter/public/dist/
It's up to you if you leave it there or if you copy those files where you prefer them to be.
Hosted
To use our CDN the URL is:
http://cdn.jsdelivr.net/autocompeter/1/autocompeter.min.js (or https version)
But it's recommended that when you insert this URL into your site, instead
of prefixing it with http://
or https://
prefix it with just //
. E.g.
like this:
<script src="//cdn.jsdelivr.net/autocompeter/1/autocompeter.min.js"></script>
If you want to use a more specific version on the jsdelivr.net CDN with more aggressive cache headers then go to http://www.jsdelivr.com/#!autocompeter and pick up the latest version.
Configure the Javascript
Basics
So, for the widget to work you need to have an <input type="text">
field
somewhere. You can put an attributes you like on it like name="something"
or class="mysearch"
for example. But you need to be able to retrieve it as
a HTML DOM node because when you activate Autocompeter
the first and only
required argument is the input DOM node. For example:
<script>
Autocompeter(document.getElementByClass('mysearch')[0]);
</script>
or...
<script>
Autocompeter(document.querySelector('input.mysearch'));
</script>
Custom domain
By default it uses the domain that is currently being used. It retrieves this
by simply using window.location.host
. If you for example, have a dev or
staging version of your site but you want to use the production domain, you
can manually set the domain like this:
<script>
Autocompeter(document.querySelector('input.mysearch'), {
domain: 'example.com'
});
</script>
Number of results to display
There are a couple of other options you can override. For example the maximum number of items to be returned. The default is 10.:
<script>
Autocompeter(document.querySelector('input.mysearch'), {
domain: 'example.com',
number: 20
});
</script>
Limiting results by 'groups'
Another thing you might want to set is the groups
parameter. Note that
this can be an array or a comma separated string. Suppose that this information
is set by the server-side rendering, you can use it like this for example,
assuming here some server-side template rendering code like Django or Jinja
for example:
<script>
var groups = [];
{% if user.is_logged_in %}
groups.push('private');
{% if user.is_admin %}
groups.push('admins');
{% endif %}
{% endif %}
Autocompeter(document.querySelector('input.mysearch'), {
domain: 'example.com',
number: 20,
groups: groups
});
</script>
So, suppose you set groups: "private,admins"
it will still search on titles
that were defined with no group. Doing it like this will just return
potentially more titles.
Send a 'ping' first
For the web performance freaks.
Oftentimes the slowest part of a web service is DNS. The best way to avoid
that is to "warm up" the connection between users of your site and
autocompeter.com
. This includes a first DNS lookup, the SSL certificate
negotiation and just making a TCP connection.
As soon as your user puts focus in the search widget you have
configured a ping is sent to https://autocompeter.com/v1/ping
and basically
does nothing but it does prepare the connection for that first typing in
of the first character which starts the first autocomplete search.
This feature is enabled by default, to undo it set it to false like this:
<script>
Autocompeter(document.querySelector('input.mysearch'), {
ping: false
});
</script>