Step 4Determine Number of Companies Selected
If more than one company is returned from the call to the database, we want to activate the SelectableNavigator control so that the user can navigate through the list of possible choices.
if(dt.Rows.Count > 1)
"Company", dt, "StartNewSearch", "SelectTicker",
We initialize the navigator in the server code, passing it the result set to use as its company list, as well as several other pieces of information, including the name of the OnSelect
functions. Refer to the SelectableNavigator section for more detailed information.
As we continue with our example, we'll assume that more than one company match was returned, and that the user is now sent to the SelectableNavigator control.
The SelectableNavigator allows the user to browse through a list of itemsin our case, company names. They will hear the ticker symbol, and then the name of the company; they can navigate through the list by using the built-in commands "First," "Next," and "Previous." They can also cancel out of the list entirely by saying "Cancel," or they can make their selection by saying, "Select" after an item has been read.
The SelectableNavigator user control exposes two client-side functions that we must code for: OnSelect and OnCancel. When we initialize our SelectableNavigator from the server code, we indicate the names of the client function that will handle these two events.
For the OnCancel
event, the StartNewSearch
function is run, which occurs when the user says the word "Cancel." Two things occur in this function:
Step 6Choosing the Company
- Clears the semantic item siTicker; its value becomes the empty string, and the state is set to "Empty." When RunSpeech next loops through the speech controls on the page, the prompt for CompanyOrTickerQA will be run again, as its semantic item's state is "Empty." In this way, we tell the page to "start over."
- Sets the client variable userCanceled to true, to indicate to the CompanyOrTickerQA prompt function that we have just cancelled from the SelectableNavigator.
When the user either says the word "Select" after an item is read, or if the user says the name of one of the items in the list, the OnSelect
event is fired. We have to manually set the semantic item in this case, by querying the currently selected index of the navigator; this is wrapped for us in the method Item()
of the SelectableNavigator.
// OnSelect event handler
if(siTicker.attributes["MaxShares"] == "0")
siTicker.attributes["ZeroMaxShares"] = "true";
Our client function "SelectTicker" sets the semantic item and attributes with the selected company information, and logically decides if the user is allowed to continue:
- Set attributes: We first set some attributes for the semantic item to values from the current row in the SelectableNavigator's dataset. We'll use these values in prompt functions later, to determine what to say to the user.
- Set Text value: The SetText method both sets the value of the semantic item and stores that information to the viewstate, so that the values can be accessed after postback; call this method after any attributes are set, so that those values will also be saved.
- Check Max Shares: One of the pieces of information that is returned from the dataset is how many shares the user could potentially buy of the selected company. If they cannot buy any, because their account balance is too low, we clear siTicker and send them back to the first QA, with a special flag ("ZeroMaxShares") to tell the prompt function to change what is spoken to the user.