Index: openacs-4/packages/acs-templating/www/doc/guide/search.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/search.adp,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-templating/www/doc/guide/search.adp 27 Oct 2014 16:40:24 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/guide/search.adp 7 Aug 2017 23:48:03 -0000 1.3 @@ -1,16 +1,19 @@ -{/doc/acs-templating {Templating}} {Templating System User Guide: Search-and-Select +{/doc/acs-templating {ACS Templating}} {Templating System User Guide: Search-and-Select Forms} Templating System User Guide: Search-and-Select Forms - - -

Implementing Search-and-Select Forms

Form designers are often confronted by the need to provide users +

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:

    +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 @@ -22,38 +25,45 @@ 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 proceding. If no -matches are found, the sytem prompts the user to search again.

      +system prompts the user to choose a city before proceeding. If no +matches are found, the system prompts the user to search again.

      2. -

    To illustrate how to implement this type of page flow using the +

+

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 +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:

    +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 user name or screen name and submits +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.

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

    5. The user enters part of a user name 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.

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

    7. If multiple matches are found, the page includes a listing of +user_search. If this parameter is defined, the page +queries the database for potential matches.

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

    9. 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 +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.

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

      11. -

    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:

      +user_id so that the administrator may search again.

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

      2. +
    +

    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).
      5. -
    templating\@arsdigita.com - +yield a match.(i.e. zzzzz).
  1. Submit the search form with criteria likely to produce multiple +results (i.e. e).
  2. Submit the search form with criteria likely to product a single +result (i.e. Sally).
    3. +
+
+ \ No newline at end of file