AJAX Control Toolkit Tutorial: AutoComplete

Ajax Control Toolkit AutoComplete Extender Control is attached to the Text Box to perform autocomplete operations. It will show words when entered; i.e, suggested keywords in the text box. As I have configured it for countries and entered the keyword pa, it will show a list that contains all the countries that contain "pa" in their names.

It generates the drop down list of the suggested words by keyword, after fetching from the Web Service.

You can learn more in my previous parts here,

The best thing about the autocomplete is that as you type the repetitive words in an autocomplete extender control, it does not make a new call but shows it from cache.

It uses the Web Services and the method name to fetch the required list to return.

Now we will check out the initial code with its output.

<asp:TextBox ID="myTextBox" runat="server"></asp:TextBox>
<div class="row">
<div id="ajaxcontroltoolkitplaceholder">
<ajaxToolkit:AutoCompleteExtender runat="server" ID="autoComplete1" TargetControlID="myTextBox" ServiceMethod="GetCountriesList" ServicePath="AutoComplete.asmx" MinimumPrefixLength="2" ShowOnlyCurrentWordInCompletionListItem="true">
</ajaxToolkit:AutoCompleteExtender>
</div>
</div>

Output

Output

So, let’s start to check its properties in detail.

TargetControlID

This is the Text Box control in which an autocomplete extender works by typing the prefix keywords.
1. <asp:TextBox ID="myTextBox" runat="server"></asp:TextBox>
ServiceMethod

It is the Web Service method to be called. The same signature can be used, as shown below:

ServiceMethod="GetCountriesList"
1. [System.Web.Services.WebMethod]
3. [System.Web.Script.Services.ScriptMethod]
5. public string[] GetCountriesList(string prefixText, int count)
7. {... }
Note that you can replace "GetCountriesList " with a name of your choice, but the return type, parameter name, and type must exactly match, including the case.
ServicePath

This is the path where the service resides in the Application or http path. If the path of the service is not defined, then the page method should be called.

ServicePath="AutoComplete.asmx"

If your Service is in some directory structure, then mention the full path of the Service it points to.
ContextKey

If you wish to use another parameter, Web Method can achieve it with the help of the context key. It should have the same signature with an additional parameter, named contextKey of type string.

ServiceMethod="GetCountriesList"
1. [System.Web.Services.WebMethod]
3. [System.Web.Script.Services.ScriptMethod]
5. public string[] GetCountriesList(string prefixText, int count,string contextKey)
7. {... }
Note, that you can replace "GetCountriesList " with a name of your choice, but the return type, parameter name and type must exactly match, including the case.
UseContextKey

This indicates whether or not the ContextKey property should be used. This will be automatically enabled, if the ContextKey property is ever set (on either the client or the server). If the context key is used, it should have the same signature as above in the context key.

UseContextKey="true"
MinimumPrefixLength

It is the minimum number of characters, before you get the response from your Web Service.

MinimumPrefixLength="2"
CompletionInterval

It shows the time in milliseconds; i.e, when the timer will kick in to get the suggestions, using the Web Service.

CompletionInterval="5000"

I have set five seconds, when the user enters the prefix it will fetch result after five seconds.
EnableCaching

It will enable the client side caching for the control.

EnableCaching="true"

The first time, it will fetch the result against the prefix, but when you type the same prefix again, no call is sent to the Service, but it will fetch it from cache.
CompletionSetCount

It is the number of suggestions you get in response to your prefix.

As I have seven countries starting from Sa,
1. countriesList.Add("Saudia Arabia");
3. countriesList.Add("Saint Kitts and Nevis");
5. countriesList.Add("Saint Lucia");
7. countriesList.Add("Saint Vincent and the Grenadines");
9. countriesList.Add("Samoa ");
11. countriesList.Add("San Marino");
13. countriesList.Add("Sao Tome and Principe");
Hence, when I search by giving prefix “sa”, it will fetch the 3 results, not all, as we have restricted the CompletionSetCount.

Output
CompletionListCssClass

Css class is used to style the end result from the Service.

CompletionListCssClass="CompletionList"
CompletionListItemCssClass

Css Class will be used to style an item in the AutoComplete list.

CompletionListItemCssClass="CompletionListItem"
CompletionListHighlightedItemCssClass

Css Class will be used to style a highlighted item in the AutoComplete list.

CompletionListHighlightedItemCssClass="CompletionListHighlightedItem"

The style will look as shown below:
1. <style type="text/css">
2. .CompletionList
3. {
4. border: solid 1px Red;
5. margin: 0px;
6. padding: 3px;
7. height: 120px;
8. overflow: auto;
9. background-color: #FFFFFF;
10. }
12. .CompletionListItem
13. {
14. color: blue;
15. }
17. .CompletionListHighlightedItem
18. {
19. background-color: white;
20. }
21. </style>
The output for all the styles is shown below:
DelimiterCharacters

With this setting, you can select multiple items, separated by the delimiter character; I have put a comma, another option is semicolon or any other character, with which you like to delimit.

DelimiterCharacters=", "
FirstRowSelected

As the name suggests, it enables the first row of the selected list.

FirstRowSelected="true"
ShowOnlyCurrentWordInCompletionListItem

If the condition is true and DelimiterCharacters are specified, then the AutoComplete will list the items, according to the display suggestions for the current word to be completed and will not display the rest of the tokens.

ShowOnlyCurrentWordInCompletionListItem="true"

Complete Code of Ajax AutoComplete is shown below.

<ajaxToolkit:AutoCompleteExtender
runat="server"
ID="autoComplete1"
TargetControlID="myTextBox"
ServiceMethod="GetCountriesList"
ServicePath="AutoComplete.asmx"
UseContextKey="true"
MinimumPrefixLength="2"
CompletionInterval="1000"
EnableCaching="true"
CompletionSetCount="3"
CompletionListCssClass="CompletionList"
CompletionListItemCssClass="CompletionListItem"
CompletionListHighlightedItemCssClass="CompletionListHighlightedItem"
FirstRowSelected="true"
DelimiterCharacters=", "
ShowOnlyCurrentWordInCompletionListItem="true">
</ajaxToolkit:AutoCompleteExtender>