source: main/trunk/greenstone3/web/interfaces/oran/js/jquery-ui-1.8rc1/docs/autocomplete.html@ 24245

<p>
<ul class="UIAPIPlugin-toc">
<li><a href="#overview">Overview</a></li>
<li><a href="#options">Options</a></li>
<li><a href="#events">Events</a></li>
<li><a href="#methods">Methods</a></li>
<li><a href="#theming">Theming</a></li>
</ul>
<div class="UIAPIPlugin">
  <h1>jQuery UI Autocomplete</h1>
  <div id="overview">
    <h2 class="top-header">Overview</h2>
    <div id="overview-main">
        You've seen functionality like Autocomplete before.  Anytime you've done a search on Google for instance or typed in a url into your location bar of your browser.  You would start to type and as you typed a narrowing list of options would be presented to you.  This is the functionality that the Autocomplete plugin can provide you and your web site.
</p><p>Autocomplete, added to an input field, enables users to quickly find and select from a pre-populated list of values as they type, leveraging searching and filtering.
</p><p>By giving an Autocomplete field focus or entering something into it, the plugin starts searching for entries that match and displays a list of values to choose from. By entering more characters, the user can filter down the list to better matches.
</p><p>This can be used to enter previous selected values, for example you could use Autocomplete for entering tags, to complete an address, you could enter a city name and get the zip code, or maybe enter email addresses from an address book.
</p><p>You can pull data in from a local and/or a remote source: Local is good for small data sets (like an address book with 50 entries), remote is necessary for big data sets, like a database with hundreds or millions of entries to select from.
</p><p>To customize the widget to work with these varied cases, you implement the source option. There are three variations:
</p>
<ul><li> an Array with local data
</li><li> a String, specifying a URL
</li><li> a Callback
</li></ul>
<p>The local data can be a simple Array of Strings, or it contains Objects for each item in the array, with a label or value property or both. The label property is displayed in the suggestion menu, the value will be inserted into the input element after the user selected something from the menu. If just one is specified, it will be used for both, eg. if you provide only value-properties, they will also be used as the label.
</p><p>When a String is used, the Autocomplete plugin expects that string to point to a resource to return JSON data. It can be on the same host or on a different one (must provide JSONP). The data itself can be in the same format as the local data described above.
</p><p>The third variation, the callback, provides the most flexibility, and can be used to connect any datasource to the Autocomplete. The callback gets two arguments:
</p>
<ul><li> A request object, with a single property called "term", which refers to the value currently in the text input. For example, when the user entered "new yo" in a city autocomplete, term equals "new yo".
</li><li> A response callback, which expects a single argument to contain the data to suggest to the user. This data should be filtered based on the provided term, and can be in any of the formats described above for simple local data (String-Array or Object-Array with label/value/both properties).
</li></ul>
The demos all focus on different variations of the source-option - look for the one that matches your usecase, and take a look at the code.
    </div>
    <div id="overview-dependencies">
        <h3>Dependencies</h3>
        <ul>
<li>UI Core</li>
<li>UI Widget</li>
</ul>
    </div>
    <div id="overview-example">
        <h3>Example</h3>
        <div id="overview-example" class="example">
<ul><li><a href="#demo"><span>Demo</span></a></li><li><a href="#source"><span>View Source</span></a></li></ul>
<p><div id="demo" class="tabs-container" rel="300">
A simple jQuery UI Autocomplete.<br />
</p>
<pre>$(&quot;input#autocomplete&quot;).autocomplete({
    source: [&quot;c++&quot;, &quot;java&quot;, &quot;php&quot;, &quot;coldfusion&quot;, &quot;javascript&quot;, &quot;asp&quot;, &quot;ruby&quot;]
});
</pre>
<p></div><div id="source" class="tabs-container">
</p>
<pre>&lt;!DOCTYPE html&gt;
&lt;html&gt;
&lt;head&gt;
  &lt;link type=&quot;text/css&quot; href=&quot;http://jqueryui.com/latest/themes/base/ui.all.css&quot; rel=&quot;stylesheet&quot; /&gt;
  &lt;script type=&quot;text/javascript&quot; src=&quot;http://jqueryui.com/latest/jquery-1.3.2.js&quot;&gt;&lt;/script&gt;
  &lt;script type=&quot;text/javascript&quot; src=&quot;http://jqueryui.com/latest/ui/jquery.ui.core.js&quot;&gt;&lt;/script&gt;
  &lt;script type=&quot;text/javascript&quot; src=&quot;http://jqueryui.com/latest/ui/jquery.ui.widget.js&quot;&gt;&lt;/script&gt;
  &lt;script type=&quot;text/javascript&quot; src=&quot;http://jqueryui.com/latest/ui/jquery.ui.autocomplete.js&quot;&gt;&lt;/script&gt;
  &lt;script type="text/javascript"&gt;
  $(document).ready(function(){
    $(&quot;input#autocomplete&quot;).autocomplete({
    source: [&quot;c++&quot;, &quot;java&quot;, &quot;php&quot;, &quot;coldfusion&quot;, &quot;javascript&quot;, &quot;asp&quot;, &quot;ruby&quot;]
});
  });
  &lt;/script&gt;
&lt;/head&gt;
&lt;body style="font-size:62.5%;"&gt;
  
&lt;input id=&quot;autocomplete&quot; /&gt;

&lt;/body&gt;
&lt;/html&gt;
</pre>
<p></div>
</p><p></div>
    </div>
  </div>
  <div id="options">
    <h2 class="top-header">Options</h2>
    <ul class="options-list">
      
<li class="option" id="option-delay">
  <div class="option-header">
    <h3 class="option-name"><a href="#option-delay">delay</a></h3>
    <dl>
      <dt class="option-type-label">Type:</dt>
        <dd class="option-type">Integer</dd>
      
      <dt class="option-default-label">Default:</dt>
        <dd class="option-default">300</dd>
      
    </dl>
  </div>
  <div class="option-description">
    <p>The delay in milliseconds the autocomplete waits after a keystroke to activate itself. A zero-delay makes sense for local data (more responsive), but can produce a lot of load for remote data, while being less responsive.</p>
  </div>
  <div class="option-examples">
    <h4>Code examples</h4>
    <dl class="option-examples-list">
    
<dt>
  Initialize a autocomplete with the <code>delay</code> option specified.
</dt>
<dd>
<pre><code>$('.selector').autocomplete({ delay: 0 });</code></pre>
</dd>

    
<dt>
  Get or set the <code>delay</code> option, after init.
</dt>
<dd>
<pre><code>//getter
var delay = $('.selector').autocomplete('option', 'delay');
//setter
$('.selector').autocomplete('option', 'delay', 0);</code></pre>
</dd>

    </dl>
  </div>
</li>


<li class="option" id="option-minLength">
  <div class="option-header">
    <h3 class="option-name"><a href="#option-minLength">minLength</a></h3>
    <dl>
      <dt class="option-type-label">Type:</dt>
        <dd class="option-type">Integer</dd>
      
      <dt class="option-default-label">Default:</dt>
        <dd class="option-default">1</dd>
      
    </dl>
  </div>
  <div class="option-description">
    <p>The minimum number of characters a user has to type before the autocomplete activates. Zero is useful for local data with just a few items. Should be increased when there are a lot of items, where a single character would match a few thousand items.</p>
  </div>
  <div class="option-examples">
    <h4>Code examples</h4>
    <dl class="option-examples-list">
    
<dt>
  Initialize a autocomplete with the <code>minLength</code> option specified.
</dt>
<dd>
<pre><code>$('.selector').autocomplete({ minLength: 0 });</code></pre>
</dd>

    
<dt>
  Get or set the <code>minLength</code> option, after init.
</dt>
<dd>
<pre><code>//getter
var minLength = $('.selector').autocomplete('option', 'minLength');
//setter
$('.selector').autocomplete('option', 'minLength', 0);</code></pre>
</dd>

    </dl>
  </div>
</li>


<li class="option" id="option-source">
  <div class="option-header">
    <h3 class="option-name"><a href="#option-source">source</a></h3>
    <dl>
      <dt class="option-type-label">Type:</dt>
        <dd class="option-type">String, Array, Callback</dd>
      
      <dt class="option-default-label">Default:</dt>
        <dd class="option-default">none, must be specified</dd>
      
    </dl>
  </div>
  <div class="option-description">
    <p>Defines the data to use, must be specified. See Overview section for more details, and look at the various demos.
</p>
  </div>
  <div class="option-examples">
    <h4>Code examples</h4>
    <dl class="option-examples-list">
    
<dt>
  Initialize a autocomplete with the <code>source</code> option specified.
</dt>
<dd>
<pre><code>$('.selector').autocomplete({ source: [&quot;c++&quot;, &quot;java&quot;, &quot;php&quot;, &quot;coldfusion&quot;, &quot;javascript&quot;, &quot;asp&quot;, &quot;ruby&quot;] });</code></pre>
</dd>

    
<dt>
  Get or set the <code>source</code> option, after init.
</dt>
<dd>
<pre><code>//getter
var source = $('.selector').autocomplete('option', 'source');
//setter
$('.selector').autocomplete('option', 'source', [&quot;c++&quot;, &quot;java&quot;, &quot;php&quot;, &quot;coldfusion&quot;, &quot;javascript&quot;, &quot;asp&quot;, &quot;ruby&quot;]);</code></pre>
</dd>

    </dl>
  </div>
</li>

    </ul>
  </div>
  <div id="events">
    <h2 class="top-header">Events</h2>
    <ul class="events-list">
      
<li class="event" id="event-search">
  <div class="event-header">
    <h3 class="event-name"><a href="#event-search">search</a></h3>
    <dl>
      <dt class="event-type-label">Type:</dt>
        <dd class="event-type">autocompletesearch</dd>
    </dl>
  </div>
  <div class="event-description">
    <p>Before a request (source-option) is started, after minLength and delay are met. Can be cancelled (return false), then no request will be started and no items suggested.</p>
  </div>
  <div class="event-examples">
    <h4>Code examples</h4>
    <dl class="event-examples-list">
    
<dt>
  Supply a callback function to handle the <code>search</code> event as an init option.
</dt>
<dd>
<pre><code>$('.selector').autocomplete({
   search: function(event, ui) { ... }
});</code></pre>
</dd>

    
<dt>
  Bind to the <code>search</code> event by type: <code>autocompletesearch</code>.
</dt>
<dd>
<pre><code>$('.selector').bind('autocompletesearch', function(event, ui) {
  ...
});</code></pre>
</dd>

    </dl>
  </div>
</li>


<li class="event" id="event-open">
  <div class="event-header">
    <h3 class="event-name"><a href="#event-open">open</a></h3>
    <dl>
      <dt class="event-type-label">Type:</dt>
        <dd class="event-type">autocompleteopen</dd>
    </dl>
  </div>
  <div class="event-description">
    <p>After a request with the data ready, before it is actually displayed; also indicates the suggestion menu will be opened.</p>
  </div>
  <div class="event-examples">
    <h4>Code examples</h4>
    <dl class="event-examples-list">
    
<dt>
  Supply a callback function to handle the <code>open</code> event as an init option.
</dt>
<dd>
<pre><code>$('.selector').autocomplete({
   open: function(event, ui) { ... }
});</code></pre>
</dd>

    
<dt>
  Bind to the <code>open</code> event by type: <code>autocompleteopen</code>.
</dt>
<dd>
<pre><code>$('.selector').bind('autocompleteopen', function(event, ui) {
  ...
});</code></pre>
</dd>

    </dl>
  </div>
</li>


<li class="event" id="event-focus">
  <div class="event-header">
    <h3 class="event-name"><a href="#event-focus">focus</a></h3>
    <dl>
      <dt class="event-type-label">Type:</dt>
        <dd class="event-type">autocompletefocus</dd>
    </dl>
  </div>
  <div class="event-description">
    <p>Before focus is moved to an item (not selecting), ui.item refers to the focused item. The default action of focus is to replace the text field's value with the value of the focused item. Cancelling this event prevents the value from being updated, but does not prevent the menu item from being focused.</p>
  </div>
  <div class="event-examples">
    <h4>Code examples</h4>
    <dl class="event-examples-list">
    
<dt>
  Supply a callback function to handle the <code>focus</code> event as an init option.
</dt>
<dd>
<pre><code>$('.selector').autocomplete({
   focus: function(event, ui) { ... }
});</code></pre>
</dd>

    
<dt>
  Bind to the <code>focus</code> event by type: <code>autocompletefocus</code>.
</dt>
<dd>
<pre><code>$('.selector').bind('autocompletefocus', function(event, ui) {
  ...
});</code></pre>
</dd>

    </dl>
  </div>
</li>


<li class="event" id="event-select">
  <div class="event-header">
    <h3 class="event-name"><a href="#event-select">select</a></h3>
    <dl>
      <dt class="event-type-label">Type:</dt>
        <dd class="event-type">autocompleteselect</dd>
    </dl>
  </div>
  <div class="event-description">
    <p>Triggered when an item is selected from the menu; ui.item refers to the selected item. The default action of select is to replace the text field's value with the value of the selected item. Cancelling this event prevents the value from being updated, but does not prevent the menu from closing.</p>
  </div>
  <div class="event-examples">
    <h4>Code examples</h4>
    <dl class="event-examples-list">
    
<dt>
  Supply a callback function to handle the <code>select</code> event as an init option.
</dt>
<dd>
<pre><code>$('.selector').autocomplete({
   select: function(event, ui) { ... }
});</code></pre>
</dd>

    
<dt>
  Bind to the <code>select</code> event by type: <code>autocompleteselect</code>.
</dt>
<dd>
<pre><code>$('.selector').bind('autocompleteselect', function(event, ui) {
  ...
});</code></pre>
</dd>

    </dl>
  </div>
</li>


<li class="event" id="event-close">
  <div class="event-header">
    <h3 class="event-name"><a href="#event-close">close</a></h3>
    <dl>
      <dt class="event-type-label">Type:</dt>
        <dd class="event-type">autocompleteclose</dd>
    </dl>
  </div>
  <div class="event-description">
    <p>When the list is hidden - doesn't have to occur together with a change.</p>
  </div>
  <div class="event-examples">
    <h4>Code examples</h4>
    <dl class="event-examples-list">
    
<dt>
  Supply a callback function to handle the <code>close</code> event as an init option.
</dt>
<dd>
<pre><code>$('.selector').autocomplete({
   close: function(event, ui) { ... }
});</code></pre>
</dd>

    
<dt>
  Bind to the <code>close</code> event by type: <code>autocompleteclose</code>.
</dt>
<dd>
<pre><code>$('.selector').bind('autocompleteclose', function(event, ui) {
  ...
});</code></pre>
</dd>

    </dl>
  </div>
</li>


<li class="event" id="event-change">
  <div class="event-header">
    <h3 class="event-name"><a href="#event-change">change</a></h3>
    <dl>
      <dt class="event-type-label">Type:</dt>
        <dd class="event-type">autocompletechange</dd>
    </dl>
  </div>
  <div class="event-description">
    <p>After an item was selected; ui.item refers to the selected item. Always triggered after the close event.</p>
  </div>
  <div class="event-examples">
    <h4>Code examples</h4>
    <dl class="event-examples-list">
    
<dt>
  Supply a callback function to handle the <code>change</code> event as an init option.
</dt>
<dd>
<pre><code>$('.selector').autocomplete({
   change: function(event, ui) { ... }
});</code></pre>
</dd>

    
<dt>
  Bind to the <code>change</code> event by type: <code>autocompletechange</code>.
</dt>
<dd>
<pre><code>$('.selector').bind('autocompletechange', function(event, ui) {
  ...
});</code></pre>
</dd>

    </dl>
  </div>
</li>

    </ul>
  </div>
  <div id="methods">
    <h2 class="top-header">Methods</h2>
    <ul class="methods-list">
      
<li class="method" id="method-destroy">
  <div class="method-header">
    <h3 class="method-name"><a href="#method-destroy">destroy</a></h3>
    <dl>
      <dt class="method-signature-label">Signature:</dt>
        <dd class="method-signature">.autocomplete( 'destroy'







)</dd>
    </dl>
  </div>
  <div class="method-description">
    <p>Remove the autocomplete functionality completely. This will return the element back to its pre-init state.</p>
  </div>
</li>


<li class="method" id="method-disable">
  <div class="method-header">
    <h3 class="method-name"><a href="#method-disable">disable</a></h3>
    <dl>
      <dt class="method-signature-label">Signature:</dt>
        <dd class="method-signature">.autocomplete( 'disable'







)</dd>
    </dl>
  </div>
  <div class="method-description">
    <p>Disable the autocomplete.</p>
  </div>
</li>


<li class="method" id="method-enable">
  <div class="method-header">
    <h3 class="method-name"><a href="#method-enable">enable</a></h3>
    <dl>
      <dt class="method-signature-label">Signature:</dt>
        <dd class="method-signature">.autocomplete( 'enable'







)</dd>
    </dl>
  </div>
  <div class="method-description">
    <p>Enable the autocomplete.</p>
  </div>
</li>


<li class="method" id="method-option">
  <div class="method-header">
    <h3 class="method-name"><a href="#method-option">option</a></h3>
    <dl>
      <dt class="method-signature-label">Signature:</dt>
        <dd class="method-signature">.autocomplete( 'option'

, optionName

, <span class="optional">[</span>value<span class="optional">] </span>



)</dd>
    </dl>
  </div>
  <div class="method-description">
    <p>Get or set any autocomplete option. If no value is specified, will act as a getter.</p>
  </div>
</li>


<li class="method" id="method-search">
  <div class="method-header">
    <h3 class="method-name"><a href="#method-search">search</a></h3>
    <dl>
      <dt class="method-signature-label">Signature:</dt>
        <dd class="method-signature">.autocomplete( 'search'

, <span class="optional">[</span>value<span class="optional">] </span>





)</dd>
    </dl>
  </div>
  <div class="method-description">
    <p>Triggers a search event, which, when data is available, then will display the suggestions; can be used by a selectbox-like button to open the suggestions when clicked. If no value argument is specified, the current input's value is used. Can be called with an empty string and minLength: 0 to display all items.</p>
  </div>
</li>


<li class="method" id="method-close">
  <div class="method-header">
    <h3 class="method-name"><a href="#method-close">close</a></h3>
    <dl>
      <dt class="method-signature-label">Signature:</dt>
        <dd class="method-signature">.autocomplete( 'close'







)</dd>
    </dl>
  </div>
  <div class="method-description">
    <p>Close the autocomplete menu. Useful in combination with the search method, to close the open menu.</p>
  </div>
</li>

    </ul>
  </div>
  <div id="theming">
    <h2 class="top-header">Theming</h2>
    <p>The jQuery UI Autocomplete plugin uses the jQuery UI CSS Framework to style its look and feel, including colors and background textures. We recommend using the ThemeRoller tool to create and download custom themes that are easy to build and maintain.
</p>
  <p>If a deeper level of customization is needed, there are widget-specific classes referenced within the ui.autocomplete.css stylesheet that can be modified. These classes are highlighed in bold below.
</p>
    
  <h3>Sample markup with jQuery UI CSS Framework classes</h3>
  &lt;input class=&quot;<strong>ui-autocomplete</strong>&quot;/&gt;
  <p class="theme-note">
    <strong>
      Note: This is a sample of markup generated by the autocomplete plugin, not markup you should use to create a autocomplete. The only markup needed for that is &lt;input/&gt;.
    </strong>
  </p>

  </div>
</div>

</p><!-- 
Pre-expand include size: 25368 bytes
Post-expand include size: 42213 bytes
Template argument size: 24687 bytes
Maximum: 2097152 bytes
-->

<!-- Saved in parser cache with key jqdocs_docs:pcache:idhash:3766-1!1!0!!en!2 and timestamp 20100128052926 -->