STUDENT: Mike McCarthy HARVARD ID: 00161118 CLASS: E13 Practical Perl PROJECT: TurboMart Online Store FILE: README.txt SUBMITTED: 01/13/2004 ----------------------------------------------------------------- INTRODUCTION: ------------ TurboMart is a ficticious web-based retail store where customers can view and order products, generate an order summary, and finalize their transactions. An itemized invoice and confirmation number is emailed to the customer at the completion of each sale. A manager interface is provided for maintenance and review of the inventory and customer databases, and for changing the super user login and password. The site is entirely self-documenting. The 'Site Design' link on the main page enables the visitor to view all the design plans, code files, and graphics. This website was created in fulfillment of the final project option for E13 Practical Perl and submitted for review 01/13/2004. NOTE: Code files are no longer public. The manager login and password are now required to access the files. Because of this change several text strings in THIS document have been obliterated and replaced with x's. ----------------------------------------------------------------- SHORT DESCRIPTION OF FILES: --------------------------- 1) index.html Main page - login form, links 2) login.cgi Processes customer/manager logins 3) add_cust.html Customer registration form 4) add_cust.cgi Processes customer registration form 5) shop.cgi Displays item catalog and order form 6) process_order.cgi Processes orders, displays order summary 7) confirm.cgi Displays invoice, emails confirmation 8) manager.cgi Displays manager options 9) mgr_request.cgi Option-specific setup for mgr. selection 10) add_item.cgi Allows mgr. to add new items to the catalog 11) delete_item.cgi Allows mgr. to delete items from the catalog 12) delete_cust.cgi Allows mgr. to delete customer from database 13) show_items.cgi Displays the 'inventory' database table 14) show_cust.cgi Displays the 'customers' database table 15) edit_superuser.cgi Allows mgr. to change super user login/pwd 16) logout.cgi Redirects client to main page 17) hot.html Displays current 'hot' item from catalog 18) designPlan.html Links to all components of the project design 19) update_supernum.pl Changes security key in super_num.log 20) update_item.pl Increments current item number (for new items) 21) xxxx.xxx Storage file for mgr. login/password 22) super_num.log Storage file for manager's security key 23) item_id.log Storage file for current new item number 24) customers.sql 'customers' database table CREATE statement 25) inventory.sql 'inventory' database table CREATE statement 26) HT_TEMPLATE header/trailer subroutines 27) xxxx.xxx All code files consolidated in one file 28) README.txt This document LONG DESCRIPTION OF FILES: -------------------------- 1) index.html ---------- TurboMart home page containing login/password form. Returning customers will use their registerd login/password, managers will use the super user login/password which currently is set to "xxxxxx" and "xxxxxx" respectively. Page also includes these links: a) REGISTER - calls 'add_cust.html' b) HOT ITEM - calls 'hot.html' c) CONTACT US - uses 'mailto' browser builtin d) SITE DESIGN - calls 'designPlan.html' 2) login.cgi --------- Examines login and password supplied at index.html. If they match the super user login/password stored in xxxx.log, client will be redirected to 'manager.cgi' with a security 'key' appended in the url. This 'key' is a randomly generated floating point number that is also written to the file 'super_num.log'. After the redirection, the 'manager.cgi' script checks to see if the query string 'key' matches the current contents of 'super_num.log'. This security feature prevents a different client from accessing the 'manager.cgi' page without first logging in with the super user login/password. If the login/password do not match the super user's, the entered strings will be looked up in the 'customers' database table. If found, the returning customer will be redirected to 'shop.cgi'. Otherwise an error message will occur instructing the client to register. 3) add_cust.html ------------- Provides the form for new customers to register. The form action is add_cust.cgi. 4) add_cust.cgi ------------ Examines all registration data submitted by the client for errors. If errors or illegal data were provided, an appropriate error message will be returned. Otherwise the new customer's registration data will be inserted into the 'customers' database table and the client will be redirected to 'shop.cgi'. 5) shop.cgi -------- Displays the store catalog. Each inventory item is shown with its item number, product name, description, price and weight. In addition, there is a clickable thumbnail image of each product allowing the customer to view the picture full-size. Browser widgets are provided to allow the customer to 'Add to cart' and to indicate the 'Quantity' desired for each item ordered. There is a 'Checkout' button at the bottoms of the page which sends the order data to 'process_order.cgi'. 6) process_order.cgi ----------------- Presents the customer with a summary of their order including price calculations and shipping charges. The customer is instructed to press the 'back' button to change their order, or press 'Confirm' to finalize the transaction. If 'Confirm' is pressed, the order data is sent to 'confirm.cgi'. 7) confirm.cgi ----------- Displays a shipping label and invoice facsimile in the browser window. Generates a random 'confirmation number' consisting of two letters, a hyphen, up to 5 digits, and a trailing letter. The itemized contents of the invoice along with the confirmation number is then emailed to the customer and to the project author. 8) manager.cgi ----------- If the login/password submitted from the main page matched the super user's stored in 'super_user.log', the client will be redirected here after a security check (see login.cgi above). This page displays the manager functions as radio buttons. The selected option is sent to 'mgr_request.cgi'. 9) mgr_request.cgi --------------- Allows the manager to provide the details for the option selected from 'manager.cgi'. If one of the database query options was chosen, this page presents further options to refine the scope of the query. If 'Add item to catalog' option was chosen, the manager can provide the details of the new item and upload a .jpg or .gif image file. If 'Change mgr. login/pswd' option was chosen, the manager can change the super user's login and password. 10) add_item.cgi ------------ Receives and processes the data for new items added to the catalog. Checks for valid values in price and weight, and for valid image file extensions (.jpg, .jpeg, or .gif). Assigns a new item number to the item by reading the next available number from the 'item_id.log' file. Increments that number for the next new item by calling 'update_item.pl'. Changes the image file name to the item number followed by the file type. For example, if the uploaded picture filename is "my_product.jpg" and the current content of 'item_id.log' is "1076", the resulting new image filename would be "1076.jpg". Catalog item images are stored in the 'images/items' directory. Inserts the new item data into the 'inventory' database table. 11) delete_item.cgi --------------- Allows manager to delete an item from the catalog by selecting it from a select box. The item is then removed from the 'inventory' database table and its image file is removed from the 'images/items' directory. Certain items have been designated as 'demo items' and cannot be removed. 12) delete_cust.cgi --------------- Allows manager to delete a customer record from the 'customers' database table by choosing it from a select box in 'mgr_request.cgi'. 13) show_items.cgi -------------- Allows the manager to review all the catalog items in the inventory depending on which scope was chosen from 'mgr_request.cgi'. Items may be viewed in order by item number or by price. A truncated version of each item's description is provided to fit in a single table row (strings are not broken mid-word). 14) show_cust.cgi ------------- Allows the manager to review all the registered customers in the 'customers' database table depending on which scope was chosen from 'mgr_request.cgi'. Customers may be viewed as a complete listing (all fields) or by last name, first name, and email address only. 15) edit_superuser.cgi ------------------ Allows the manager to change super user login and password. 16) logout.cgi ---------- Redirects client to the main page. 17) hot.html -------- A promotional page which displays the item from the catalog currently designated as the 'hot' item. This item's picture is displayed on the page as an inticement for shopping. Whichever image file corresponds the 'hot' item was simply copied from its home in the 'images/items' directory and renamed 'hot.jpg' (or .gif) in the 'images' directory. Although not yet implemented, the ability to change the current 'hot item' would fit well on the 'manager.cgi's list of manager options. 18) designPlan.html --------------- Since this project is academic, this page was provided for the teaching staff to review all design phases and code files used in the creation of the TurboMart website. All code files summarized in this README.txt document can be viewed as one text file by selecting the 'code files' link. 19) update_supernum.pl ------------------ Takes as an argument, the randomly generated super user 'key' and overwrites it to the 'super_num.log' file. Called from 'login.cgi'. This is part of the manager's login security process describe in 'login.cgi' (item 2, above). 20) update_item.cgi --------------- New items added to the TurboMart catalog require an item number as their primary key. This script increments the current item number stored in 'item_id.log' so that the next newly added catalog item is assigned a unique id number. 21) xxxx.xxx -------- Contains the current login and password for accessing management functions. 22) super_num.log ------------- Contains the current security 'key' number for accessing 'manger.cgi'. 23) item_id.log ----------- Contains the id number for the next item added to the catalog. 24) customers.sql ------------- The CREATE TABLE statement used to create the 'customers' database table. 25) inventory.sql ------------- The CREATE TABLE statement user to create the 'inventory' database table. 26) HT_TEMPLATE ----------- Since most of the files created for this website contain html output, this Header/Trailer template was used to import the start/end html process and to simplify the consistency of page design. The 'header' subroutine takes two strings representing the titlebar label and the current page heading flanked by two colorbars. In lieu of using HTML Mason which was troublesome in hw4, this simple template was used as an alternative. 27) xxxx.xxx -------- Contains all the code files listed in this README as a single document delimited by a row of colon characters. An 'archiver.c' C program was created to consolidate files in its argument list into the format described above. A 'Savecopy' shell script was then created to save a copy of all project files, archive them into 'xxxx.xxx' and email it to the author as a backup copy. 28) README.txt ---------- This document. ----------------------------------------------------------------- CONCLUSION: ----------- While several aspects of this project deserve improvement, the web-programming/Perl techniques used in its creation were accomplished to the best of my ability using concepts learned during the course of this semester. In retrospect, I have discovered some shortcomings that I did not consider at the time of its design. HTML Mason would have provided a simpler method of importing the header/trailer content into each cgi script. Most of all, I neglected to design ONE module to perform all database lookups instead of accessing the data via new DBI objects in each file requiring such queries. Similarly, a single module might have been designed to display all error messages. Two manager options listed on the 'manager.cgi' page, "Edit item data" and "Edit customer data" were not implemented before the project's submission deadline. These options would have employed database manipulation techniques similar to those already demonstrated in the implementations of the enabled options. I used the CGI.pm package for its param, header, start_html, and end_html methods only. I find no advantage in using its HTML tag-producing methods and therefore wrote all other HTML tags "by hand" using standard techniques. All graphics were created with Adobe Photoshop. These files are submitted for grading, January 13, 2004. Author: Mike McCarthy