Providing type-ahead support for input controls

JSF text input controls can use the JSF type-ahead feature to anticipate what a user might be typing into the input control. Input controls with type-ahead present a list of options based on the first few characters that the user types into the control. Then, the user can select one of these options or continue typing different text:

Type-ahead in an input control

As the user continues to type, the type-ahead feature filters the options to match the new values that the user has typed into the field:

Type-ahead in an input control being filtered by further input from the user

EGL can obtain the options for the type-ahead input field in one of three ways:

The steps for using type-ahead depend on which of these methods you use to obtain the list of options.

Using options from a Data Table or from a list of valid values

The simplest way to provide options for the type-ahead function is to associate the variable bound to the field with a list of options, either in a Data Table or in a list of valid values.

  1. In a JSF Handler part, create a character or numeric variable to represent the value typed in the input field on the page:
    state STRING;
  2. On the variable, set the typeahead property to YES:
    state STRING {typeahead = YES};
  3. Associate the variable with a list of options, using either the validValues or validatorDataTable properties:
    • If you use validValues, specify the options as the values of the property:
      state STRING {typeahead = YES, 
          validValues = ["AK","AL","AR","AZ",
              "NC","NY","NH","NJ",
              "NM","NE","NV","ND"]};
      In this example, 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."

      When using type-ahead with a list of valid values, the valid values cannot contain a range.

    • If you use a Data Table, set the validatorDataTable property on the variable to the name of the Data Table. You may need to bring the Data Table part into scope with an import statement.
      state string {typeahead = YES, 
          ValidatorDataTable = data.stateAbbrevs};
      The matching Data Table might look like this example, providing the same information as in the validValues example above:
      package data;
      
      dataTable stateAbbrevs type MatchValidTable {shared = no, resident = no}
        
        3 abbrev char(2);
        
        {contents = [
          ["AK"],["AL"],["AR"],["AZ"],
          ["NC"],["NY"],["NH"],["NJ"],
          ["NM"],["NE"],["NV"],["ND"]
        ]}
        
      end
      Data Tables used with type-ahead must be of the type MatchValidTable.
  4. On the web page, drag the variable from the Page Data view onto the web page. The Insert Record window opens.
  5. In the Insert Record window, click Updating an existing record.
  6. Ensure that the Control type for the variable is set to Input field. Type-ahead can be used only on input controls.
  7. Click Finish. An input control is created on the page that is bound to the variable in the JSF Handler and is configured to use type-ahead.

Using options from a custom function

For more control over the options presented in type-ahead, you can create a function that dynamically determines the options at run time.

  1. In a JSF Handler or a Library part, create the function that determines the type-ahead options. This function must accept exactly one parameter: a STRING, representing the text that the user has typed into the input control. Also, the function must return an array of STRING, representing the type-ahead options presented in the input control.
    // Return any state names for which 
    //the key is a substring of the full state name.
    function getStateChoices( key string in ) returns( string[] )
      results string[0];
      key_upper string = strlib.upperCase( key );
      value string;
    
      // Search for values with the same starting characters.
      for ( i int from 1 to syslib.size( states ) )
    
        // Compare each value in the data table to the key.
        value = strlib.upperCase( states.fullname[i] );
        if ( strlib.indexOf( value, key_upper ) == 1 )
          // This value starts with the same characters as the key.
          // Add it to the list of options.
          results.appendElement( states.fullname[i] );
        end
    
      end
    
      return( results );
    
    end
    This function compares the text that the user has typed into the input control, represented by the variable key, with the values in a Data Table. The code if ( strlib.indexOf( value, key_upper ) == 1 ) determines if the value in the Data Table starts with the characters that the user has typed, and if so, the code results.appendElement( states.fullname[i] ); adds the value in the Data Table to the array of options for type-ahead.

    Although this function uses information from a Data Table like the following example, the function could retrieve data from any source, such as a database or record variable.

    package data;
    
    dataTable states type MatchValidTable 
      {shared = no, resident = no}
    	
      3 fullname char(20);
        {contents = [
          ["ALASKA"],
          ["ALABAMA"],
          ["ARKANSAS"],
          ["ARIZONA"],
          ["NORTH CAROLINA"],
          ["NORTH DAKOTA"],
          ["NEBRASKA"],
          ["NEW HAMPSHIRE"],
          ["NEW JERSEY"],
          ["NEW MEXICO"],
          ["NEVADA"],
          ["NEW YORK"]
        ]}
    
    end
  2. In a JSF Handler part, create a character or numeric variable to represent the value typed in the input field on the page:
    state STRING;
  3. On the variable, set the typeaheadFunction property to the name of the function:
    state STRING {typeaheadFunction = getStateChoices};
  4. On the web page, drag the variable from the Page Data view onto the web page. The Insert Record window opens.
  5. In the Insert Record window, click Updating an existing record.
  6. Ensure that the Control type for the variable is set to Input field. Type-ahead can be used only on input controls.
  7. Click Finish. An input control is created on the page that is bound to the variable in the JSF Handler and is configured to use type-ahead.

Setting options for type-ahead

You can customize the appearance and behavior of the type-ahead functionality on the page. To set these options, follow these steps:

  1. On the web page, click the type-ahead icon to select it. The type-ahead icon is located immediately to the right of the input control on which type-ahead is enabled.
  2. With the type-ahead icon selected, open the Properties view.
    The Properties view with the type-ahead icon selected
  3. In the Properties view, set the options for the type-ahead feature. You can set the size of the type-ahead field, how long the control should wait before providing options, and how the input control should behave while waiting for EGL to return the options. For more information on the options associated with type-ahead, see Typeahead Complete Component.

Feedback