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:
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.
- Create a new web page in the EGLWeb project named customersearchAJAX.jsp:
- In the Project Explorer view, right-click the WebContent folder
of the EGLWeb project and then click .
- In the File Name field, type
this text as the name of the new file, including the extension:
customersearchAJAX.jsp
- Make sure that the Folder field
shows the /EGLWeb/WebContent folder.
- In the Template list, click My
Templates.
- In the Preview box, click the A_gray.htpl template.
- Click Finish. The
new page is created and opens in the editor.
- Remove the default text from the page and replace it
with the following text:
Customer search with type-ahead
- Press Enter three times to create blank space below
the page title.
- Open the JSF Handler for the page by right-clicking on
the content area of the page and then clicking Edit Page
Code.
- 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.
- Remove the onConstructionFunction property
from the JSF Handler, but leave the onPreRenderFunction:
handler customersearchAJAX type JSFHandler
{onPreRenderFunction = onPreRender,
view = "customersearchAJAX.jsp",
viewRootVar = viewRoot}
- Remove the stub onConstruction() function.
- 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.
- 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.
- 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.
- Optimize imports and save the JSF Handler file.
- Expand JSF Handler and Data in
the Page Data view. Drag the lastNameInput variable
onto the customersearchAJAX.jsp page. The Insert
Record window opens.
- 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.
- Click Options.
- 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.
- Click OK.
- 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:
- Drag the CustomerToDisplay variable from the Page Data
view onto the bottom of the page. The Insert Control
window opens.
- In the Insert Control window, click Displaying
an existing record (read-only).
- 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:
- Click Finish. The
controls representing the search results are added to the page.
- 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:
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:
When you choose a customer's
name, you can then click Submit and see the
customer's information:
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.