< Previous | Next >

Lesson 6: Use type-ahead to prompt the user

Controls with the type-ahead feature try to anticipate what the user might be typing into an input field, speeding up the process of entering information. In this lesson, you learn to create a separate search page that uses type-ahead functionality to search in a different way than in the previous page.

Type-ahead functionality uses AJAX, or Asynchronous Javascript and XML, which is a web technology that allows web applications to change portions of a web page without reloading the entire page. In this case, the AJAX functionality allows your EGL JSF Handler to add and remove suggestions to the input control without resubmitting the page. The EGL type-ahead functionality provides a shortcut to this common use of AJAX functionality, preventing you from having to put together an AJAX request by yourself. In the next lesson, you will learn to create custom AJAX requests.

By convention, input controls with type-ahead provide options based on the first few characters the user types into a field:
A drop-down menu shows all names in the database that begin with the letter "L".

Depending on how you write the EGL code for the type-ahead, you can provide suggestions based on the first few characters of input or from an arbitrary function that determines the suggestions dynamically.

To provide suggestions for type-ahead based on the first few characters of input, you must specify those suggestions at design time, either in the validValues property or in a Data Table part. This example uses the validValues approach:
state STRING {typeahead = YES, 
    validValues = ["AK","AL","AR","AZ",
        "NC","NY","NH","NJ",
        "NM","NE","NV","ND"]};
In this variable, the valid values are the abbreviations of U.S. states beginning with the letters "A" and "N." When the user types the letter "A" into the input control, type-ahead will provide the abbreviations beginning with "A", and likewise with the letter "N" and the abbreviations beginning with "N."

In this lesson, you use type-ahead functionality to suggest the last names of customers in the database for the user to search on. In this case, you must determine the type-ahead suggestions at run time, because the suggestions will depend on the values in the database. Therefore, you will create a function in a new JSF Handler that compares what the user has typed into an input field with the last names of customers in the database. The function then provides the matching names as type-ahead suggestions.

  1. Create a new web page in the EGLWeb project named customersearchAJAX.jsp:
    1. In the Project Explorer view, right-click the WebContent folder of the EGLWeb project and then click New > Web page.
    2. In the File Name field, type this text as the name of the new file, including the extension:
      customersearchAJAX.jsp
    3. Make sure that the Folder field shows the /EGLWeb/WebContent folder.
    4. In the Template list, click My Templates.
    5. In the Preview box, click the A_gray.htpl template.
    6. Click Finish. The new page is created and opens in the editor.
    7. Remove the default text from the page and replace it with the following text:
      Customer search with type-ahead
    8. Press Enter three times to create blank space below the page title.
  2. Open the JSF Handler for the page by right-clicking on the content area of the page and then clicking Edit Page Code.
  3. Add these three variables to the JSF Handler:
    lastNameInput STRING {TypeaheadFunction = suggestLastNames};
    allLastNames Customer[0];
    customerToDisplay Customer;

    The first variable will be bound to an input control on the page. The TypeaheadFunction property indicates that this variable will have a function that provides type-ahead suggestions. You will create this function later in this lesson.

    The second variable will hold the list of last names in the database. The function providing suggestions will need this list.

    The third variable is a single record that will show the results of the search.

  4. Remove the onConstructionFunction property from the JSF Handler, but leave the onPreRenderFunction:
    handler customersearchAJAX type JSFHandler
    	{onPreRenderFunction = onPreRender,
    	view = "customersearchAJAX.jsp",
    	viewRootVar = viewRoot} 
  5. Remove the stub onConstruction() function.
  6. Complete the stub onPreRender() function:
    	function onPreRender()
    		get allLastNames with
    			#sql{
    				select
    					LASTNAME
    				from EGL.CUSTOMER
    				group by
    					EGL.CUSTOMER.LASTNAME
    			};
    	end
    This function will run each time the page is refreshed, in order to retrieve a list of customer last names from the database to compare with the user's input.
  7. Add the following function to the JSF Handler:
    	function suggestLastNames(typedCharacters STRING in) returns (STRING[])
    		matchingLastNames STRING[0];
    		oneCustomer Customer;
    		oneCustomerName STRING;
    
    		//This variable represents the characters the user has typed.
    		typedCharacters = StrLib.upperCase(typedCharacters);
    
    		//Compare the user input to the values in the database.
    		for (counter INT from 1 to allLastNames.getSize())
    			oneCustomer = allLastNames[counter];
    			oneCustomerName = StrLib.upperCase(oneCustomer.LastName);
    
    			if (StrLib.indexOf(oneCustomerName, typedCharacters) == 1)
    				//This value starts with the same characters.
    				//Add this value to the type-ahead suggestions.
    				matchingLastNames.appendElement(oneCustomer.LastName);
    			end
    		end
    		return (matchingLastNames);
    	end
    This function is the function referred to in the TypeaheadFunction property of the variable you created earlier. As its name implies, this function provides the suggestions for type-ahead. This function must receive a single parameter: a STRING representing the characters that the user has typed into the input control. Also, it must return an array of STRINGs, representing the suggestions. With this function, you can determine the type-ahead suggestions with any arbitrary EGL logic.

    In this case, the function follows the convention that the suggestions should start with the same characters as the user has typed into the input control. The function compares the characters that the user has typed in to each customer's last name, in each case, setting both values to upper case to eliminate any differences in capitalization. Each time the function finds a match, it adds the customer's last name to the array of results representing the type-ahead suggestions.

  8. Add the following function to the JSF Handler:
    	function displayCustomer()
    		get customerToDisplay with
    			#sql{
    				select
    					CUSTOMERID, FIRSTNAME, LASTNAME, PASSWORD, PHONE, 
    					EMAILADDRESS, STREET, APARTMENT, CITY, "STATE", 
    					POSTALCODE, DIRECTIONS
    				from EGL.CUSTOMER
    				where
    					LASTNAME = :lastNameInput
    			};
    	end
    This function will be bound to a button on the page. When the type-ahead control has helped the user find the name of a unique customer, the user will click the button and run this function to retrieve the customer's details.
  9. Optimize imports and save the JSF Handler file.


  10. Expand JSF Handler and Data in the Page Data view. Drag the lastNameInput variable onto the customersearchAJAX.jsp page. The Insert Record window opens.
  11. Click Updating an existing record and make sure that the Control type for the input control is set to Input Field. You can use type-ahead only on JSF input controls.
  12. Click Options.
  13. In the Options window, clear the Delete button check box and select the Submit button check box. Leave the default label of Submit for the button.
  14. Click OK.
  15. Click Finish. The input control and a button are created on the page. Because of the TypeaheadFunction property on the variable, the new input control is automatically configured for type-ahead. You can view the options for the type-ahead functionality, such as the length of the delay before offering suggestions, by clicking the type-ahead icon to the right of the input control and opening the Properties view:
    Properties view showing the options for the type-ahead control
  16. Drag the CustomerToDisplay variable from the Page Data view onto the bottom of the page. The Insert Control window opens.
  17. In the Insert Control window, click Displaying an existing record (read-only).
  18. Under Fields to display, select the check boxes next to the fields in the customer record that you want to display in your search results. For example, you might select the CustomerId, FirstName, LastName, and Phone fields:
    The Configure Data Controls window has four fields selected.
  19. Click Finish. The controls representing the search results are added to the page.
  20. Bind the displayCustomer() function to the Submit button on the page by dragging the function from the Page Data view onto the button.
You now have configured the page to use type-ahead. The page looks like this:
A picture of the completed page

You can test the page by running it on the server and typing the first character or two of a customer's name into the input field:

A picture of the type-ahead control providing suggestions

When you choose a customer's name, you can then click Submit and see the customer's information:

A picture of the page showing the results of the search

Here is the complete code of the customersearchAJAX.egl file. If you see any errors marked by red X symbols in the file, make sure your code matches the code in this file:Completed customersearchAJAX.egl file after lesson 6.

Lesson checkpoint

In this lesson, you learned to apply type-ahead support to an input field. Type-ahead can help the user enter valid information, but you must beware of the strain on the system providing the suggestions. Each time the value of the input control changes, the function associated with the type-ahead control runs. This function should be a simple as possible to prevent the system from becoming overloaded.
For more information on type-ahead, see Providing type-ahead support for input controls.
This concludes the tutorial.
< Previous | Next >

Feedback