JqueryUI - Autocomplete


Advertisements


Auto completion is a mechanism frequently used in modern websites to provide the user with a list of suggestions for the beginning of the word, which he/she has typed in a text box. The user can then select an item from the list, which will be displayed in the input field. This feature prevents the user from having to enter an entire word or a set of words.

JQueryUI provides an autocomplete widget — a control that acts a lot like a <select> dropdown, but filters the choices to present only those that match what the user is typing into a control. jQueryUI provides the autocomplete() method to create a list of suggestions below the input field and adds new CSS classes to the elements concerned to give them the appropriate style.

Any field that can receive input can be converted into an Autocomplete, namely, <input> elements, <textarea> elements, and elements with the contenteditable attribute.

Syntax

The autocomplete() method can be used in two forms −

$ (selector, context).autocomplete (options) Method

The autocomplete (options) method declares that an HTML <input> element must be managed as an input field that will be displayed above a list of suggestions. The options parameter is an object that specifies the behavior of the list of suggestions when the user is typing in the input field.

Syntax

$(selector, context).autocomplete (options);

You can provide one or more options at a time using Javascript object. If there are more than one options to be provided then you will separate them using a comma as follows −

$(selector, context).autocomplete({option1: value1, option2: value2..... });

The following table lists the different options that can be used with this method −

Sr.No. Option & Description
1 appendTo

This option is used append an element to the menu. By default its value is null.

Option - appendTo

This option is used append an element to the menu. By default its value is null. When the value is null, the parents of the input field will be checked for a class of ui-front. If an element with the ui-front class is found, the menu will be appended to that element.

Syntax

$( ".selector" ).autocomplete({ appendTo: "#identifier" });
2 autoFocus

This option when set to true, the first item of the menu will automatically be focused when the menu is shown. By default its value is false.

Option - autoFocus

This option when set to true, the first item of the menu will automatically be focused when the menu is shown. By default its value is false.

Syntax

$( ".selector" ).autocomplete({ autoFocus: true });
3 delay

This option is an Integer representing number of milliseconds to wait before trying to obtain the matching values (as specified by the source option). This can help reduce thrashing when non-local data is being obtained by giving the user time to enter more characters before the search is initiated. By default its value is 300.

Option - delay

This option is an Integer representing number of milliseconds to wait before trying to obtain the matching values (as specified by the source option). This can help reduce thrashing when non-local data is being obtained by giving the user time to enter more characters before the search is initiated. By default its value is 300.

Syntax

$( ".selector" ).autocomplete({ delay: 500 });
4 disabled

This option if specified and true, the autocomplete widget is initially disabled. By default its value is false.

Option - disabled

This option if specified and true, the autocomplete widget is initially disabled. By default its value is false.

Syntax

$( ".selector" ).autocomplete({ disabled: true });
5 minLength

The number of characters that must be entered before trying to obtain the matching values (as specified by the source option). This can prevent too large a value set from being presented when a few characters isn’t enough to whittle the set down to a reasonable level. By default its value is 1.

Option - minLength

The number of characters that must be entered before trying to obtain the matching values (as specified by the source option). This can prevent too large a value set from being presented when a few characters isn’t enough to whittle the set down to a reasonable level. By default its value is 1.

Syntax

$( ".selector" ).autocomplete({ minLength: 0 });
6 position

This option identifies the position of the suggestions menu in relation to the associated input element. The of option defaults to the input element, but you can specify another element to position against. By default its value is { my: "left top", at: "left bottom", collision: "none" }.

Option - position

This option identifies the position of the suggestions menu in relation to the associated input element. The of option defaults to the input element, but you can specify another element to position against. By default its value is { my: "left top", at: "left bottom", collision: "none" }.

Syntax

$( ".selector" ).autocomplete({ position: { my : "right top", at: "right bottom" } });
7 source

This option specifies the manner in which the data that matches the input data is obtained. A value must be provided or the autocomplete widget won’t be created. By default its value is none; must be specified.

Option - source

This option specifies the manner in which the data that matches the input data is obtained. A value must be provided or the autocomplete widget won’t be created. This value can be a :

  • String representing the URL of a server resource that will return matching data,

  • an array of local data from which the value will be matched,or

  • a function that serves as a general callback from providing the matching values.

Syntax

$( ".selector" ).autocomplete({ source: [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ] });

The following section will show you a few working examples of autocomplete widget functionality.

Default Functionality

The following example demonstrates a simple example of autocomplete widget functionality, passing no parameters to the autocomplete() method.

<!doctype html>
<html lang = "en">
   <head>
      <meta charset = "utf-8">
      <title>jQuery UI Autocomplete functionality</title>
      <link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
         rel = "stylesheet">
      <script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
      <script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
      
      <!-- Javascript -->
      <script>
         $(function() {
            var availableTutorials  =  [
               "ActionScript",
               "Bootstrap",
               "C",
               "C++",
            ];
            $( "#automplete-1" ).autocomplete({
               source: availableTutorials
            });
         });
      </script>
   </head>
   
   <body>
      <!-- HTML --> 
      <div class = "ui-widget">
         <p>Type "a" or "s"</p>
         <label for = "automplete-1">Tags: </label>
         <input id = "automplete-1">
      </div>
   </body>
</html>

Let us save the above code in an HTML file autocompleteexample.htm and open it in a standard browser which supports javascript, you should see the following output. Now, you can play with the result −

Use of autoFocus

The following example demonstrates the usage of option autoFocus in the autocomplete widget of JqueryUI.

<!doctype html>
<html lang = "en">
   <head>
      <meta charset = "utf-8">
      <title>jQuery UI Autocomplete functionality</title>
      <link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
         rel = "stylesheet">
      <script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
      <script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
      
      <!-- Javascript -->
      <script>
         $(function() {
            var availableTutorials = [
               "ActionScript",
               "Bootstrap",
               "C",
               "C++",
            ];
            $( "#automplete-2" ).autocomplete({
               source: availableTutorials,
               autoFocus:true
            });
         });
      </script>
   </head>
   
   <body>
      <!-- HTML --> 
      <div class = "ui-widget">
         <p>Type "a" or "s"</p>
         <label for = "automplete-2">Tags: </label>
         <input id = "automplete-2">
      </div>
   </body>
</html>

Let us save the above code in an HTML file autocompleteexample.htm and open it in a standard browser which supports javascript, you must also see the following output. Now, you can play with the result −

Use of minLength and delay

The following example demonstrates the usage of two options minLength and delay in the autocomplete widget of JqueryUI.

<!doctype html>
<html lang = "en">
   <head>
      <meta charset = "utf-8">
      <title>jQuery UI Autocomplete functionality</title>
      <link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
         rel = "stylesheet">
      <script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
      <script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
      
      <!-- Javascript -->
      <script>
         $(function() {
            var availableTutorials = [
               "ActionScript",
               "Bootstrap",
               "C",
               "C++",
               "Ecommerce",
               "Jquery",
               "Groovy",
               "Java",
               "JavaScript",
               "Lua",
               "Perl",
               "Ruby",
               "Scala",
               "Swing",
               "XHTML"	
            ];
            $( "#automplete-3" ).autocomplete({
               minLength:2,   
               delay:500,   
               source: availableTutorials
            });
         });
      </script>
   </head>
   
   <body>
      <!-- HTML --> 
      <div class = "ui-widget">
         <p>Type two letter for e.g:ja,sc etc</p>
         <label for = "automplete-3">Tags: </label>
         <input id = "automplete-3">
      </div>
   </body>
</html>

Let us save the above code in an HTML file autocompleteexample.htm and open it in a standard browser which supports javascript, you must also see the following output. Now, you can play with the result −

Use of Label

The following example demonstrates the usage of option label in the autocomplete widget of JqueryUI.

<!doctype html>
<html lang = "en">
   <head>
      <meta charset = "utf-8">
      <title>jQuery UI Autocomplete functionality</title>
      <link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
         rel = "stylesheet">
      <script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
      <script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
      
      <!-- Javascript -->
      <script>
         $(function() {
            $( "#autocomplete-4" ).autocomplete({
               source: [
                  { label: "India", value: "IND" },
                  { label: "Australia", value: "AUS" }
               ]
            });
         });
      </script>
   </head>
   
   <body>
      <!-- HTML --> 
      <div class = "ui-widget">
         <p>Type I OR A</p>
         <input id = "autocomplete-4">
      </div>
   </body>
</html>

Let us save the above code in an HTML file autocompleteexample.htm and open it in a standard browser which supports javascript, you must also see the following output. Now, you can play with the result −

Use of External Source

The following example demonstrates the use of external file for source option in the autocomplete widget of JqueryUI.

<!doctype html>
<html lang = "en">
   <head>
      <meta charset = "utf-8">
      <title>jQuery UI Autocomplete functionality</title>
      <link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
         rel = "stylesheet">
      <script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
      <script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
      
      <!-- Javascript -->
      <script>
         $(function() {
            $( "#autocomplete-5" ).autocomplete({
               source: "/jqueryui/search.php",
               minLength: 2
            });
         });
      </script> 
   </head>
   
   <body>
      <input id = "autocomplete-5">
   </body>
</html>

The file search.php is placed at the same location as the above file (autocompleteexample.html). Contents of search.php are as below −

<?
$term = $_GET[ "term" ];
$companies = array(
   array( "label" => "JAVA", "value" => "1" ),
   array( "label" => "DATA IMAGE PROCESSING", "value" => "2" ),
   array( "label" => "JAVASCRIPT", "value" => "3" ),
   array( "label" => "DATA MANAGEMENT SYSTEM", "value" => "4" ),
   array( "label" => "COMPUTER PROGRAMMING", "value" => "5" ),
   array( "label" => "SOFTWARE DEVELOPMENT LIFE CYCLE", "value" => "6" ),
   array( "label" => "LEARN COMPUTER FUNDAMENTALS", "value" => "7" ),
   array( "label" => "IMAGE PROCESSING USING JAVA", "value" => "8" ),
   array( "label" => "CLOUD COMPUTING", "value" => "9" ),
   array( "label" => "DATA MINING", "value" => "10" ),
   array( "label" => "DATA WAREHOUSE", "value" => "11" ),
   array( "label" => "E-COMMERCE", "value" => "12" ),
   array( "label" => "DBMS", "value" => "13" ),
   array( "label" => "HTTP", "value" => "14" )
	
);

$result = array();
foreach ($companies as $company) {
   $companyLabel = $company[ "label" ];
   if ( strpos( strtoupper($companyLabel), strtoupper($term) )!== false ) {
      array_push( $result, $company );
   }
}

echo json_encode( $result );
?>

Let us save the above code in an HTML file autocompleteexample.htm and open it in a standard browser which supports javascript, you must also see the following output. Now, you can play with the result −

Type two letter words for e.g: ja, sc etc

$ (selector, context).autocomplete ("action", params) Method

The autocomplete ("action", params) method can perform an action on the list of suggestions, such as show or hide. The action is specified as a String in the first argument (e.g., "close" to hide the list). Check out the actions that can be passed, in the following table.

Syntax

$(selector, context).autocomplete ("action", params);;

The following table lists the different actions that can be used with this method −

Sr.No. Action & Description
1 close

This action hides the list of suggestions in the Autocomplete menu. This method does not accept any arguments.

Action - close

This action hides the list of suggestions in the Autocomplete menu. This method does not accept any arguments.

Syntax

$( ".selector" ).autocomplete("close");
2 destroy

This action removes the autocomplete functionality. Lists of suggestions are deleted. This method does not accept any arguments.

Action - destroy

This action removes the autocomplete functionality. Lists of suggestions are deleted. This method does not accept any arguments.

Syntax

$( ".selector" ).autocomplete("destroy");
3 disable

This action disables the autocompletion mechanism. The list of suggestions no longer appears. This method does not accept any arguments.

Action - disable

This action disables the autocompletion mechanism. The list of suggestions no longer appears. This method does not accept any arguments.

Syntax

$( ".selector" ).autocomplete("disable");
4 enable

This action reactivates the autocompletion mechanism. The list of suggestions will again be displayed. This method does not accept any arguments.

Action - enable

This action reactivates the autocompletion mechanism. The list of suggestions will again be displayed. This method does not accept any arguments.

Syntax

$( ".selector" ).autocomplete("enable");
5 option( optionName )

This action retrieves the value of the specified param optionName. This option corresponds to one of those used with autocomplete (options).

Action - option( optionName )

This action retrieves the value of the specified param optionName. This option corresponds to one of those used with autocomplete (options).

Syntax

var isDisabled = $( ".selector" ).autocomplete( "option", "disabled" );
6 option

This action gets an object containing key/value pairs representing the current autocomplete options hash.

Action - option

This action gets an object containing key/value pairs representing the current autocomplete options hash.

Syntax

var options = $( ".selector" ).autocomplete( "option" );
7 option( optionName, value )

This action sets the value of the autocomplete option associated with the specified optionName. The argument optionName is name of the option to be set and value is the value to be set for the option.

Action - option( optionName, value )

This action sets the value of the autocomplete option associated with the specified optionName. The argument optionName is name of the option to be set and value is the value to be set for the option.

Syntax

$( ".selector" ).autocomplete( "option", "disabled", true );
8 option( options )

This action is sets one or more options for the autocomplete. The argument options is a map of option-value pairs to be set.

Action - option( options )

This action is sets one or more options for the autocomplete. The argument options is a map of option-value pairs to be set.

Syntax

$( ".selector" ).autocomplete( "option", { disabled: true } );
9 search( [value ] )

This action searches for correspondence between the string value and the data source (specified in options.source). The minimum number of characters (indicated in options.minLength) must be reached in value, otherwise the search is not performed.

10 widget

Retrieve the <ul> DOM element corresponding to the list of suggestions. This is an object of jQuery class that allows easy access to the list without using jQuery selectors.

Action - widget

Retrieve the <ul> DOM element corresponding to the list of suggestions. This is an object of jQuery class that allows easy access to the list without using jQuery selectors.

Syntax

$( ".selector" ).autocomplete("widget");

Example

Now let us see an example using the actions from the above table. The following example demonstrates the use of option( optionName, value ) method.

<!doctype html>
<html lang = "en">
   <head>
      <meta charset = "utf-8">
      <title>jQuery UI Autocomplete functionality</title>
      <link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
         rel = "stylesheet">
      <script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
      <script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
      
      <!-- Javascript -->
      <script>
         $(function() {
            var availableTutorials = [
               "ActionScript",
               "Bootstrap",
               "C",
               "C++",
               "Ecommerce",
               "Jquery",
               "Groovy",
               "Java",
               "JavaScript",
               "Lua",
               "Perl",
               "Ruby",
               "Scala",
               "Swing",
               "XHTML"	
            ];
            $( "#automplete-6" ).autocomplete({
               source: availableTutorials
            });
            $( "#automplete-6" ).autocomplete("option", "position",
               { my : "right-10 top+10", at: "right top" }) 
         });
      </script>
   </head>
   
   <body>
      <!-- HTML --> 
      <div class = "ui-widget">
         <p>Type "a" or "s"</p>
         <label for = "automplete-6">Tags: </label>
         <input id = "automplete-6">
      </div>
   </body>
</html>

Let us save the above code in an HTML file autocompleteexample.htm and open it in a standard browser which supports javascript, you must also see the following output −

Extension Points

The autocomplete widget can be extended as its built with the widget factory. When extending widgets, you have the ability to override or add to the behavior of existing methods. The following table lists methods that act as extension points with the same API stability as the plugin methods listed above.

Sr.No. Method & Description
1 _renderItem( ul, item )

This method controls the creation of each option in the widget's menu. This method creates a new <li> element, appends it to the menu and return it.

_renderItem( ul, item )

This method controls the creation of each option in the widget's menu. This method creates a new <li> element, appends it to the menu and return it. Where −

  • <ul> is the element that must be appended to the newly created <li> element.

  • item

    can be a label(String), the string to display for the item, or a value(String), the value to insert into the input when the item is selected.
2 _renderMenu( ul, items )

This method controls building the widget's menu.

_renderMenu( ul, items )

This method controls building the widget's menu. Where −

  • <ul> is an Array of items that match the user typed term. Each item is an Object with label and value properties.

3 _resizeMenu()

This method controls sizing the menu before it is displayed.The menu element is available at this.menu.element. This method does not accept any arguments.

_resizeMenu()

This method controls sizing the menu before it is displayed.The menu element is available at this.menu.element. This method does not accept any arguments.

Event Management on Autocomplete Elements

In addition to the autocomplete (options) method which we saw in the previous sections, JqueryUI provides event methods which gets triggered for a particular event. These event methods are listed below −

Sr.No. Event Method & Description
1 change(event, ui)

This event is triggered when the value of the <input> element is changed based upon a selection. When triggered, this event will always come after the close event is triggered.

Event - change(event, ui)

This event is triggered when the value of the <input> element is changed based upon a selection. When triggered, this event will always come after the close event is triggered. Where event is of type Event, and ui is of type Object. Possible values of ui are −

  • item − The item selected from the menu, if any. Otherwise the property is null.

Syntax

$( ".selector" ).autocomplete({
   change: function( event, ui ) {}
});
2 close(event, ui)

This event is triggered whenever the autocomplete menu closes.

Event - close(event, ui)

This event is triggered whenever the autocomplete menu closes. Where event is of type Event, and ui is of type Object.

Syntax

$( ".selector" ).autocomplete({
   close: function( event, ui ) {}
});
3 create(event, ui)

This event is triggered when the autocomplete is created.

Event - create(event, ui)

This event is triggered when the autocomplete is created.. Where event is of type Event, and ui is of type Object. Possible values of ui are −

  • item − The item selected from the menu, if any. Otherwise the property is null.

Syntax

$( ".selector" ).autocomplete({
   create: function( event, ui ) {}
});
4 focus(event, ui)

This event is triggered whenever one of the menu choices receives focus. Unless canceled (for example, by returning false), the focused value is set into the <input> element.

Event - focus(event, ui)

This event is triggered whenever one of the menu choices receives focus. Unless canceled (for example, by returning false), the focused value is set into the <input> element. Where event is of type Event, and ui is of type Object. Possible values of ui are −

  • item − The focused item.

Syntax

$( ".selector" ).autocomplete({
   focus: function( event, ui ) {}
});
5 open(event, ui)

This event is triggered after the data has been readied and the menu is about to open.

Event - open(event, ui)

This event is triggered after the data has been readied and the menu is about to open. Where event is of type Event, and ui is of type Object.

Syntax

$( ".selector" ).autocomplete({
   open: function( event, ui ) {}
});
6 response(event, ui)

This event is triggered after a search completes, before the menu is shown. This event is always triggered when a search completes, even if the menu will not be shown because there are no results or the Autocomplete is disabled.

Event - response(event, ui)

This event is triggered after a search completes, before the menu is shown. This event is always triggered when a search completes, even if the menu will not be shown because there are no results or the Autocomplete is disabled. Where event is of type Event, and ui is of type Object. Possible values of ui are −

  • content − Contains the response data and can be modified to change the results that will be shown.

Syntax

$( ".selector" ).autocomplete({
   response: function( event, ui ) {}
});
7 search(event, ui)

This event is triggered after any delay and minLength criteria have been met, just before the mechanism specified by source is activated. If canceled, the search operation is aborted.

8 select(event, ui)

This event is triggered when a value is selected from the autocomplete menu. Canceling this event prevents the value from being set into the <input> element (but doesn’t prevent the menu from closing).

Event - select(event, ui)

This event is triggered when a value is selected from the autocomplete menu. Canceling this event prevents the value from being set into the <input> element (but doesn’t prevent the menu from closing). Where event is of type Event, and ui is of type Object. Possible values of ui are −

  • item − An Object with label and value properties for the selected option.

Syntax

$( ".selector" ).autocomplete({
   select: function( event, ui ) {}
});

Example

The following example demonstrates the event method usage in autocomplete widgets. This example demonstrates the use of events focus, and select.

<!doctype html>
<html lang = "en">
   <head>
      <meta charset = "utf-8">
      <title>jQuery UI Autocomplete functionality</title>
      <link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
         rel = "stylesheet">
      <script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
      <script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
      
      <style>
         #project-label {
            display: block;
            font-weight: bold;
            margin-bottom: 1em;
         }
         #project-icon {
            float: left;
            height: 32px;
            width: 32px;
         }
         #project-description {
            margin: 0;
            padding: 0;
         }
      </style>
      
      <!-- Javascript -->
      <script>
         $(function() {
            var projects = [
               {
                  value: "java",
                  label: "Java",
                  desc: "write once run anywhere",
               },
               {
                  value: "jquery-ui",
                  label: "jQuery UI",
                  desc: "the official user interface library for jQuery",
               },
               {
                  value: "Bootstrap",
                  label: "Twitter Bootstrap",
                  desc: "popular front end frameworks ",
               }
            ];
            $( "#project" ).autocomplete({
               minLength: 0,
               source: projects,
               focus: function( event, ui ) {
                  $( "#project" ).val( ui.item.label );
                     return false;
               },
               select: function( event, ui ) {
                  $( "#project" ).val( ui.item.label );
                  $( "#project-id" ).val( ui.item.value );
                  $( "#project-description" ).html( ui.item.desc );
                  return false;
               }
            })
				
            .data( "ui-autocomplete" )._renderItem = function( ul, item ) {
               return $( "<li>" )
               .append( "<a>" + item.label + "<br>" + item.desc + "</a>" )
               .appendTo( ul );
            };
         });
      </script>
   </head>
   
   <body>
      <div id = "project-label">Select a project (type "a" for a start):</div>
      <input id = "project">
      <input type = "hidden" id = "project-id">
      <p id = "project-description"></p>
   </body>
</html>

Let us save the above code in an HTML file autocompleteexample.htm and open it in a standard browser which supports javascript. You must also see the following output −



Advertisements