Next, set the MinimumPrefixLength attribute to “1.” The MinimumPrefixLength attribute indicates the minimum number of characters that the TextBox control must have before it invokes the Web service to obtain the list of countries.

To associate a control (a TextBox control in this case) with the AutoCompleteExtender control, add a element within the element. Here you specify the control to associate with it using the TargetControlID attribute. Remember to set the Enabled attribute to “true.”

You can associate multiple controls with the AutoCompleteExtended control by simply inserting additional element(s) into the element, like this:

For now, I just want to associate a single TextBox control with the AutoCompleteExtender control.

Adding a Web Service
The next step is to add a Web service to the current project. Right-click on the Project name in Solution Explorer and select Add New Item? (see Figure 5).

Select the Web Service item and use the default name of WebService.asmx.

Figure 6 shows that two files are added?WebService.vb and WebService.asmx (this name corresponds to the value set in the ServicePath attribute).

Figure 5. Here I’m adding a new Web service to the current project.

?

Figure 6. Here you can see the Web services files in the current project.

The list below shows some of the countries in the list in unsorted order:

• Monaco
• Macau SAR (PRC)
• Hong Kong SAR (PRC)
• Singapore
• Gibraltar
• Vatican City
• Malta
• Bermuda
• Maldives
• Bahrain
• Bangladesh
• …

Double-click on the WebService.vb file and add the following web method:

     _       Public Function GetCountries( _          ByVal prefixText As String, _          ByVal count As Integer) _          As String()        Dim result() As String        Dim countries() As String        '---read the content of the text file---        Dim fileContents As String        fileContents = _           My.Computer.FileSystem.ReadAllText( _           "C:AutoCompletecountries.txt")        '---load the countries into the array---        countries = fileContents.Split(vbLf)        Dim listOfCountries As String = String.Empty        '---find countries being with the prefixText---        For Each country As String In countries            If country.StartsWith(prefixText, _               StringComparison.OrdinalIgnoreCase) Then                '---add the country name to the list---                listOfCountries += country & vbLf            End If        Next        '---convert the countries list into an array---        result = listOfCountries.Split(vbLf)        '---sort the array---        Array.Sort(result)        Return result    End Function

The GetCountries() Web method name corresponds to the value set in the ServiceMethod attribute. In this method, you first read the list of country names into an array and then look for country names that begin with the string specified in the PrefixText parameter. The matching country names are saved into a string and eventually converted to an array and returned to the client.

In general, to tie up the AutoCompleteExtender control with a Web service, your Web method must have the following signature:

 Public Function FunctionName( _   ByVal prefixText As String, _   ByVal count As Integer) _   As String()

The prefixText parameter will contain the text typed in the associated control (such as a TextBox). The count parameter indicates the maximum number of possible values to return to the client. You can name your function with any name you like, but the function name must be set accordingly in the ServiceMethod attribute in the element. The method returns a string array.

Testing the Application
Press F5 to test the application. In the TextBox control, notice that as you type each character a list of matching country names will be shown (see Figure 7).

A Word about Web Services
Earlier on, I mentioned that the Web service must be hosted within the same Atlas application and not as a separate Web service project. Why is this so? The reason is that Web services hosted within an Atlas application are able to generate Javascript proxies to be used by the client browser. To view the proxy generated, select the WebService.asmx file in Solution Explorer and then press F5. Append the “/js” string to the back of the URL and you should be able to see the Javascript proxy (see Figure 8).

Figure 7. Testing the application.

?

Figure 8. Viewing the Javascript proxy.

Assuming you have a separate Atlas project named AtlasWebService and it contains a Web service file named WebService.asmx, to use this web service in your current Atlas application, you would modify the ServicePath attribute as follows:

One important point to note here is that, due to security constraints, the AutoCompleteExtender control requires that both the Atlas project and the Web service must be hosted on the same server (and running on the same port number). In this example, both must be hosted by IIS. Trying to run this example using the built-in Web server in Visual Studio 2005 will not work, because different projects will run on different port numbers. If you try to connect to external web services, you will get an error. On the next page I’ll discuss a way of circumventing this restriction.

Calling External Web Services
While the AutoCompleteExtender control does not by default allow you to connect to external Web services, you can actually circumvent this restriction by using a technique known as bridging, which is described in this documentation.

However, a much simpler way to call external Web services is to call them from within your own Web service. The AutoCompleteExtender control is useful not just for auto-completing a text entry; it is also useful if you want to get an instant result based on what you type in the TextBox. For example, you might have a site that translates sentences from one language to another. Using the AutoCompleteExtender control, you can translate real-time as the user types. In this section, I will show you how this can be done.

Using the same project created in the last section, add a new Web Reference to the following Web service: http://www.webservicex.com/TranslateService.asmx?WSDL (see Figure 9). Click the Add Reference button to add the Web reference.

In Default.aspx page, add a new AutoCompleteExtender control and a new TextBox control named TextBox2 and then enter the following string “Enter a string to translate” (see Figure 10).

Figure 9. Add a Web Reference to the Web service.

?

Figure 10. Add the second set of AutoCompleteExtender and TextBox controls.

         ServiceMethod="Translate"            ServicePath="WebService.asmx" MinimumPrefixLength="1">                            Enter a string to translate
        

In the WebService.vb file, add the following Translate() Web method:

     _    Public Function Translate( _       ByVal prefixText As String, _       ByVal count As Integer) _       As String()        Dim result(3) As String        Dim ws As New com.webservicex.www.TranslateService        result(0) = ws.Translate( _           com.webservicex.www.Language.EnglishTOChinese, prefixText)        result(1) = ws.Translate( _           com.webservicex.www.Language.EnglishTOJapanese, prefixText)        result(2) = ws.Translate( _           com.webservicex.www.Language.EnglishTOFrench, prefixText)        result(3) = ws.Translate( _           com.webservicex.www.Language.EnglishTOKorean, prefixText)        Return result    End Function

The Translate() Web method basically calls the translation Web service and translates whatever the user types into four different languages?Chinese, Japanese, French, and Korean.

Press F5 to test the application. Type a string to translate into the second TextBox and observe that as you type the translation is performed in real time (see Figure 11).

Figure 11. The translation is done in real time.

?

Figure 12. The translation will only take place if you end your sentence with a “.”.

     _    Public Function Translate( _       ByVal prefixText As String, _       ByVal count As Integer) _       As String()        If Not prefixText.EndsWith(".") Then            Return Nothing        End If        Dim result(3) As String        Dim ws As New com.webservicex.www.TranslateService        result(0) = ws.Translate( _           com.webservicex.www.Language.EnglishTOChinese, prefixText)        result(1) = ws.Translate( _           com.webservicex.www.Language.EnglishTOJapanese, prefixText)        result(2) = ws.Translate( _           com.webservicex.www.Language.EnglishTOFrench, prefixText)        result(3) = ws.Translate( _           com.webservicex.www.Language.EnglishTOKorean, prefixText)        Return result    End Function

Now the Web service will only be invoked whenever the user ends the sentence with a “.” (see Figure 12).

In this article, you learned how to use the AutoCompleteExtender control to enhance the usability of your Web application, specifically by trying to offer suggestions on whatever the user is typing. You have also learned how to invoke external Web services by calling them in your own Web service. In future articles on Atlas, I will show you how to perform drag-and-drop on your Web pages using Atlas.