End User Recipe: Search Users

Perhaps the most time-consumingand error-susceptibleaspect of sending email to a group of people is entering the email addresses. The Search Users page of the Mail Merge application provides an easy way to collect and apply the required addresses. Typically in a workgroup, email is sent either to individuals whose email address is known or to a specific set of people tasked with a particular job, such as managers, whose email address might not be known to the sender. The Search Users page is structured to accommodate either scenario.

You'll find that this search page differs from others in this book in several ways. First, the pages uses two different search forms: one that looks for individuals and another that concentrates on groups. Both forms have their own form buttons, but each button activates the same codeand that's the second major difference. Instead of the form just passing parameters to another page to handle the actual search, the Search Users page first places all the selected search criteria into session variables, which can be referenced throughout the application. This process has the added benefit of ensuring that the currently selected criteria will be present if the user returns to this page by way of either the Back button or a link. After the variables are stored, the user is redirected to the results page.

A simple recordset is used to gather the available groups for a drop-down list in one of the search forms. By attaching the list dynamically, new groups can be included as a search item as they become available, without additional coding.

Step 1: Implement Search Users Design

The obvious difference between this Web application page and most others is that this page includes more than one form. When designing the layout for this page, make sure to completely separate the two forms by putting them in two separate table rows. You'll also want to make sure that each form is named differently; the forms contained in our snippet are called SearchUsers and SearchAccessGroups, reflecting their functionality. However, for our purposes, it's important that the submit buttons in both forms use the same name, such as Search; having identically named buttons will ensure that the same custom code is called regardless of which form is submitted.

1.	In the server model of your choice, create a dynamic page. In the MailMerge folder, locate the folder for your server model and open the search_users page from there.
2.	Add a table to the content region of your page to contain the interface elements for the application. You'll need to make sure that the table is suitable to contain two separate forms. From the Snippets panel, drag the Recipes > MailMerge > Wireframes > Search Users - Wireframe snippet into the Content editable region.
3.	Insert the first form and a table with five rows and two columns; name the form SearchUsers or something similar. The left column should include the following labels: First Name, Last Name, and Email. The form should also include a form button labeled and named Search. Place your cursor in the row below the words SEARCH USERS and insert the Recipes > MailMerge > Forms > Search Access Group - Form snippet.
4.	Add the second form (named SearchAccessGroup or something similar) for searching the groups. The table within the form should consist of three rows and two columns. One row should include the label Access Groups and be paired with a list form element. This form should also incorporate a submit button with the name and label Search. Place your cursor in the bottom row of the inserted table and insert the Recipes > MailMerge > Forms > Search Users - Form snippet [r7-1]. r7-1.
5.	Select the button in the second form and change its name from Search2 to Search. Macromedia Dreamweaver automatically adds a number to the name of the second button to distinguish the two.
6.	Save the file.

Step 2: Add Database Components

As the introduction to this application page mentioned, only one recordset is required. To allow the user to select any of the groups set up for access to the workgroup, we'll create a recordset that includes the names of all the groups. If access groups are not used in your workplace, you can substitute any other group that is suitable.

Note

For more details on access groups, see the user log-in application in Recipe 1, "User Login."

1.	From the Bindings panel, choose Add (+) and select Recordset (Query).
2.	In the simple Recordset dialog, enter an appropriate name. Enter AccessGroups in the Name field.
3.	Select the data source connection. Choose Recipes from the Connection (Data Source) list.
4.	Choose the table. From the Tables list, select AccessGroups (accessgroups for PHP).
5.	Leave the Columns option set to All.
6.	Make sure the Filter is set to None.
7.	Keep the Sort option set to None and click OK to close the dialog.
8.	Save the page after the recordset is inserted.

Step 3: Data Binding Process

We'll put our recordset right to use and apply it to the list element found in the Access Groups form. In addition to making the list dynamic, we'll need to add a hidden form element next to the list. The hidden form element is required for our custom code (added later in this recipe) to work properly.

Let's start by attaching the proper recordset values to the list element.

1.	Select the AccessGroup list form element.
2.	From the Property inspector, choose Dynamic.
3.	In the Dynamic Data dialog, choose AccessGroups from the Recordset list.
4.	Select AccessGroupsID from the Values list.
5.	Select AccessGroupName from the Labels list.
6.	Leave the Set Value Equal To field blank, and click OK to close the Dynamic List/Menu dialog [r7-2]. r7-2.

Now we'll add the hidden form element with the needed name and value.

1.	Place the cursor to the right of the AccessGroups list element.
2.	From the Forms tab of the Insert bar, choose the hidden form element.
3.	In the Property inspector, enter Email in the Name field.
4.	Enter EmptyUsers in the Value field.

We put this hidden form element in the Access Groups form so that our custom SQL statement (inserted later in the Mailing List page) will not find a match in the Email field when the AccessGroups list is used.

Step 4: Set Form Action

In many other search pagesincluding those used in recipes elsewhere in this bookthe form action is set to another dynamic page, which handles the actual search depending on values passed from the initial search page. In this recipe, we're going to demonstrate an alternative approach that sets the action to the calling pagethis search pageand uses custom code to redirect the user to the results page after certain session variables have been set. This "same page" method is effective when the search criteria are needed in various other pages in the application.

Because we have two search forms, we'll need to set the actions for both of them, starting with the Search Users form:

1.	Place your cursor anywhere in the Search Users form.
2.	In the Tag Selector, choose the <form#SearchUsers> tag.
3.	From the Property inspector, select the folder icon and the current page. Choose search_users.asp. Select search_users.asp. Choose search_users.cfm. Select search_users.php.

Now let's repeat the same procedure for the second form:

1.	Place your cursor anywhere in the Search Access Group form.
2.	In the Tag Selector, choose the <form#SearchAccessGroup> tag.
3.	From the Property inspector, select the folder icon and the current page from the Select File dialog. Choose search_users.asp. Select search_users.asp. Choose search_users.cfm. Select search_users.php.

Step 5: Insert Custom Code

We're now ready for the final step in this recipe: inserting the custom code. As noted throughout the recipe, the custom code serves two purposes: to set the search criteria to easily accessible session variables and to send the user to the results page.

The custom code is inserted at the top of the page. What keeps it from being called immediately? An if-then statement surrounds the code and ensures that it will be executed only when the Request string is equal to Search, which happens to be the name assigned to the submit buttons in both forms. By giving the buttons the same name (as we did at the start of this recipe), we ensure that the custom code is run when either one is pressed.

1.	Switch to Code view and place your cursor at the top of the page. ASP and PHP users should place the cursor below the connection statement.
2.	Insert the following code: From the Snippets panel, open the Recipes > MailMerge > CustomCode folder for your server model and insert the Search Users Form - Session Variables snippet. [View full width] <% if (cStr(Request("Search"))<>"") then Session("Search_First") = cStr(Request("FirstName")) Session("Search_Last") = cStr(Request("LastName")) Session("Search_Email") = cStr(Request("Email")) Session("Search_Access") = cStr(Request ("AccessGroup")) Response.Redirect("mailing_list.asp") end if %> [View full width] <% if (String(Request("Search"))!="undefined") { Session("Search_First") = String(Request ("FirstName")); Session("Search_Last") = String(Request("LastName")); Session("Search_Email") = String(Request("Email")); Session("Search_Access") = String(Request ("AccessGroup")); Response.Redirect("mailing_list.asp"); } %> <cfif IsDefined("Form.Search ")> <cfparam name="Form.FirstName" default=""> <cfparam name="Form.LastName" default=""> <cfparam name="Form.Email" default=""> <cfparam name="Form.AccessGroup" default="0"> <cfset Session.Search_First = Form.FirstName> <cfset Session.Search_Last = Form.LastName> <cfset Session.Search_Email = Form.Email> <cfset Session.Search_Access = Form.AccessGroup> <cflocation url="mailing_list.cfm"> </cfif> [View full width] <?php if (isset($_POST['Search'])) { session_start(); $_SESSION["Search_Access"] = isset ($_POST['AccessGroup'])?$_POST['AccessGroup']:null; $_SESSION["Search_First"] = isset ($_POST['FirstName'])?$_POST['FirstName']:null; $_SESSION["Search_Last"] = isset ($_POST['LastName'])?$_POST['LastName']:null; $_SESSION["Search_Email"] = isset ($_POST['Email'])?$_POST['Email']:null; header("Location: mailing_list.php"); } ?> You'll note that ColdFusion requires the form elements be initialized through <cfparam> tags before the session variables can be set.
3.	Save the file.

Your page is now ready for initial testing, but until we complete the next page in the applicationMailing Listyou won't be able to see the results of your search.