Implementing Search-and-Select Forms

Templating System : User Guide

Form designers are often confronted by the need to provide users with a way to choose from hundreds or even thousands of potential options, exceeding the practical capacity of a select list or set of checkboxes or radio buttons. One common solution is to allow the user to select from a search result:

  1. The user is prompted to enter or choose some search criteria. For example, travel sites typically begin the reservation process by prompting the user to enter a city of origin and destination.

  2. The search may return any number of results. Depending on the specific application, the system may require the user to make one choice, or allow multiple selections. If the search returns no results, the system returns the user to the search form to modify the search criteria and search again.

    To continue the travel site example, if an exact match is found for the cities entered by the user, the system immediately returns a list of flights. If several possible matches are found, the system prompts the user to choose a city before proceeding. If no matches are found, the system prompts the user to search again.

To illustrate how to implement this type of page flow using the templating system, we will build the framework for a simple user-management interface. Required actions for such an interface might include editing basic user properties, changing user permissions or adding users to roles or groups.

The simplest way to implement this page flow using the templating system is to create a single page that conditionally includes two different forms:

  1. Say the administrator wishes to edit the name and screen name of a user. The administrator requests a page, user-edit.acs. The page looks for a query parameter named user_id to specify which user to edit.

  2. Initially, user_id is not specified. In this case, the page includes a user search form.

  3. The user enters part of a username or screen name and submits the form, which returns to the same URL with the query parameter user_search. If this parameter is defined, the page queries the database for potential matches.

  4. If one match is found, the page sets a user_id variable and includes the actual user edit form.

  5. If multiple matches are found, the page includes a listing of users. The name of each each user is linked back to the same page, with the appropriate user_id. The page prompts the administrator to choose one. A link is also provided with no user_id so that the administrator may search again.

  6. If the administrator chooses a user, the page detects the user_id and displays the edit form.

A working implementation of this example is provided in the files demo/user-edit.tcl and demo/user-edit.adp. You must execute the demo data file (demo/demo.sql) for the page to function.

Try the following scenarios:

  1. Submit the search form without entering any search criteria.
  2. Submit the search form with obscure criteria that does not yield a match.(i.e. zzzzz).
  3. Submit the search form with criteria likely to produce multiple results (i.e. e).
  4. Submit the search form with criteria likely to product a single result (i.e. Sally).