End User Recipe: Search Users

Perhaps the most time-consuming and error-prone aspect 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 either sent 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 by the sender. The Search Users page is structured to accommodate either scenario.

You'll find that this search page is different from others in this book in several ways. First, there are two different search forms on the page: one that looks for individuals and another that concentrates on groups. Both forms have their own form buttons, but each button activates the same code and 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 either through 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 and most other Web application pages 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 or divs. 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; the 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 [r8-1].

   
   

   Figure r8-1.

   

   
   

5. Save the file.

Step 2: Add Database Components

As mentioned in the introduction to this application page, 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 are used in your workplace, you can substitute any other group that is suitable.

Note

If you create this page by hand, be careful if you copy and paste the first Search button to create the second. Dreamweaver automatically adds a number to the name of the second button to distinguish the two. If this happens to you, be sure to rename the second button the same as the first.

Note

For more details on access groups, see the User Log In application in Recipe 1.

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 desired data source connection.

   Choose Recipes from the Connection (Data Source) list.

4. Choose the needed 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 List/Menu dialog, select the lightning bolt next to the Set Value Equal To field.

4. In the Dynamic Data dialog, choose AccessGroups from the Recordset list.

5. Select AccessGroupsID from the Values list.

6. Select AccessGroupName from the Labels list.

7. Leave the Set Value Equal To field blank and click OK to close the Dynamic List/Menu dialog [r8-2].

   
   

   Figure r8-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 pages including those used elsewhere in this book the 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 page this search page and 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 naming the buttons the same (as we did at the start of this recipe), we're ensured of running the custom code when either 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.

   	<% 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 %>
   	<% 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>
   	<?php session_start(); if (isset($_POST['Search'])) { $_SESSION("Search_First") = $_POST['FirstName']; $_SESSION("Search_Last") = $_POST['LastName']; $_SESSION("Search_Email") = $_POST['Email']; $_SESSION("Search_Access") = $_POST['AccessGroup']; 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 application Mailing List you won't be able to see the results of your search.