10.1 Overview of the Winestore Application

only for RuBoard - do not distribute or recompile

The winestore application was developed to meet the requirements outlined in Chapter 1. It has four separate modules that we discuss in this and the next three chapters:

Customer management: Becoming a member, amending membership details, logging in, and logging out. The scripts that implement this functionality are in this chapter. The web database application techniques illustrated include querying and writing data, sessions, post validation, batch error reporting, encryption of passwords, receipt pages to avoid the reload problem, and managing user authentication.
Shopping cart: Adding wines to a shopping cart, deleting items from the cart, adjusting quantities, and emptying the cart. The shopping cart is discussed in Chapter 11.
Ordering and shipping: Processing the cart so that it becomes an order, confirming shipping details by email, and confirming shipping details with an HTML receipt. These scripts are the subject of Chapter 12.
Browsing and searching: Searching and browsing the wines. The searching and browsing module is briefly outlined in Chapter 13, along with related topics.

10.1.1 Winestore Scripts

Figure 10-1 and Figure 10-2 show the scripts developed for the winestore application and how they interact. The three key user interface scripts, cart.1 , search.1, and cart.2, are shown in both figures. cart.5, the key script that manages browser redirection using the header( ) function, is omitted from the figures; we discuss why later in this section. Figure 10-1 shows the cart, customer, searching, ordering, and shipping scripts. Scripts are shown as boxes. Solid boxes indicate scripts that interact with the user, while dashed boxes don't produce output but instead redirect to the script shown.

Figure 10-1. The winestore application architecture

The main or home page of the online winestore is shown in Figures 10-1 and 10-2 and is labeled cart.1. This page allows the user to add bottles and cases of the three selected "hot new wines" to his shopping cart; this functionality is shown by the double-ended arrow to the add to cart script labeled cart.3. The cart.3 script is shown as a dashed rectangle in Figure 10-1, indicating that it's a one-component query module that has no output and instead redirects to the calling page.

The front page also allows the user to view his shopping cart by clicking on the cart icon or the View Cart button at the base of the page. View-the-cart functionality is provided by the cart.2 script introduced later in this section. Four other actions are also possible from the front page:

Searching the wines using the script search.1
Becoming a member or changing customer details using the customer.2 script
Emptying the cart using the cart.4 script
Logging in or logging out using the scripts order.1 and order.2, respectively

The customer management process is provided by five scripts. The customer.1, customer.2, and customer.3 scripts provide the become-a-member and change details features. The script customer.2 presents an empty customer <form> to new customers. The <form> allows entry of all customer details, including an email address that is used as the login name of the user and a password for future visits to the site. The customer.1 script validates customer data and, on success, writes to the database and redirects to the customer receipt script customer.3. On validation failure, customer.1 redirects to customer.2, where the validation errors are reported interleaved with the <form> widgets.

For customers who are amending their details, the password and email <input> widgets are omitted from the customer <form>. For compactness, we have omitted password-change functionality from the online site. Other possible extensions to the password module include emailing password reminders to the user and emailing account activation details.

The remaining two customer scripts are shown in Figure 10-2. The login and logout scripts are shown, along with the three scripts from Figure 10-1 that interact with these scripts. The login script interacts with the user, while the logout script doesn't produce output but instead redirects to the home page.

Figure 10-2. More winestore application architecture

The script order.1 allows a user to provide his username and password credentials. On successful processing of credentials, the user is logged in. A logged-in user can then log out using the order.2 script. The order.2 logout script is a one-component script that always redirects the browser to the front page after the logout action.

The view cart script cart.2 shows the user the contents of his shopping cart. If the cart contains items, the quantities are presented in a <form> environment that allows the user to make changes to quantities. Changing a quantity to zero deletes the item. To update changes in quantities, the cart.6 script is requested by clicking the Update Quantities button; this script redirects to cart.2, and either shows the user the correctly updated quantities or reports an error describing why the update failed. The user can also empty his cart completely by clicking on a button that requests the cart.4 script.

When logged in, orders are placed by clicking on the Make Purchase button in the view cart screen. When the button is clicked, the script order.3 is requested and the complex database processing used to finalize an order is performed; an overview of the purchasing process is presented in Chapter 3, and we outline the script in Chapter 12. If the ordering process fails, order.3 redirects to cart.2, where errors are reported. If the ordering process succeeds, order.3 redirects to shipping.1. The shipping.1 script sends the user an email confirmation of his order and redirects to shipping.2 which shows the user the same receipt as an HTML page. From shipping.2, the user can return to the home page.

The view cart script cart.2 also allows the user to return to the home page, search, log in, log out, or use the customer module.

The search.1 script allows the user to browse wines that are in stock. The user can also choose to browse a specific wine type such as Red or White and a specific region such as Margaret River. Bottles or cases of wine can be added to the shopping cart by clicking on a link that requests and passes parameters to the cart.3 script. As on the other main pages, the user can also click on buttons to view his cart, empty his cart, return to the home page, become a member, log in, log out, or update his membership details.

At the beginning of this section we stated that one important script was omitted from Figure 10-1 and Figure 10-2. This script is cart.5. This script is requested when a button is pressed on all pages that have more than one button, and it's responsible for redirecting the browser to the correct script. Each button is an <input> element of type submit, and all are elements of one <form>. As there is only one <form>, only one script can be specified as the action attribute, and this script is cart.5. The script processes requests, identifies which button was clicked by inspecting the name attribute of the <input> element, and then redirects the browser to the appropriate script. Therefore, in practice, many arrows shown in Figure 10-1 and Figure 10-2 should actually pass via cart.5.

An alternative approach to redirection via cart.5 is to include multiple <form> elements in a script or use embedded links instead of buttons. Both alternatives work well, but all approaches have drawbacks. The advantage of our approach is that buttons are intuitive for the user and the HTML is kept simple. The disadvantage is the extra HTTP response and request required for each redirection.

The winestore application can be used at either the book's web site or on your local server, if you have followed the instructions to install the examples in Appendix A. The source code described can also be viewed at the book's web site and if the installation instructions have been followed can be edited and viewed in the directory /usr/local/apache/htdocs/wda/ on your local server. A summary of the winestore scripts, their filenames, and functions is shown in Table 10-1.

Table 10-1. The winestore scripts, filenames, and functions
Script	Filename	Function
cart.1	example.cart.1.php	Home page and Hot New Wines panel
cart.2	example.cart.2.php	Cart contents view
cart.3	example.cart.3.php	Add to cart
cart.4	example.cart.4.php	Empty cart
cart.5	example.cart.5.php	Manage redirection
cart.6	example.cart.6.php	Update cart quantities
customer.1	example.customer.1.php	Validate and update customer
customer.2	example.customer.2php	Customer entry <form>
customer.3	example.customer.3.php	Customer receipt
order.1	example.order.1.php	Log in
order.2	example.order.2.php	Log out
order.3	example.order.3.php	Finalize order
shipping.1	example.shipping.1.php	Email order confirmation
shipping.2	example.shipping.2.php	Order receipt
search.1	example.search.1.php	Browse and search wines
include.inc	include.inc	Common functionality
db.inc	db.inc	DBMS parameters
error.inc	error.inc	Custom error handler

only for RuBoard - do not distribute or recompile

10.1 Overview of the Winestore Application