List /View

Many web applications are all about data. We store our data in a database management system, and build the web application to allow access to that data. Our first step towards building a web application strats with the concept of the list and the view.

So Much Data, So Little Space

When we view data on the web, we need a way to present a reasonable amount of data, even if there are thousands of things we could show. When I go to amazon.com, I don't see all of the millions of books at once. I might see a select list of books, and when I select one of them, I can then view the details of a single book. The terms list & view are borrowed from the Rails web development platform. Until Rails came along, I called the these category & item, respectively.

The List

We address the list first, because this is the way we present the user with choices. An easy way to imagine a list is to think of what is returned when we do a search on a search engine. We see a list of items, with a description that gives us enough detail to determine if we are interested. If we wish to view the details of an item, we click on a link which will take us to the view page.

Loaded Querystring

When we looked at forms, we may have noticed that using the GET method appends the data submitted via the form to the end of the formhandler page:

formhandler.php?id=5

While it is not advised to use the GET method for forms, it is highly useful to use GET to append data via the querystring in a link. We call a link to a page with data embedded in the querystring a loaded querystring.

When we build a list out of the database, we loop through our records, and can create links to each individual item. Although we create several links, we only need to create one page to receive all the links. This is our view page.

The View

We create a single page (the view) and design it to accommodate any number of different 'like' items. For example, it is the view we see for a single book on Amazon. The individual page is one page, but the data that is swapped out varies because we switch to a different record in the database. To do this, we need the unique ID number of the record.

The ID Number On The Querystring

We can use our single view page to accomodate any number of different items. Typically the item is identified by the unique ID number of the individual record, since it is the single unique identifying piece. That id number is appended to the name of our view page:

view.php?id=5

Then, we can construct a link to this item, which when viewed via the HTML source, would look like this:

<a href="view.php?id=5">My PHP Book</a>

In the above example, My PHP Book is the title of the page. Both the ID number and the title of the book are retrieved from the database. The line of PHP/MySQL code could look like this:

print '<a href="view.php?id=' . row['BookID'] . '">' . row['BookTitle'] . '</a>';

Muffins

The following example demonstrates the list and view pages in action.

List as Entry Point of the Web Application

The list and view pages together make a simple web application. We'll call the list page the entry point of the application, because the view pages are loaded by visiting the list page first. How can you view a single item on the view page, without loading the querystring? This is why the list is the entry point.

Include Files

We'll use the above example as a model for our own web application. In doing this, we want to use include files to encapsulate functionaliity, for example, our database connection information, which we no longer want to place on every web page. One important include file we'll use is called utilINC.php, which stores ‘utility’ functions that we’ll use across most of our site pages. muffinlist.php requires this page to operate and can only allow access to it once, hence the use of the  require_once() function.

HidePageErrors

We are using a global variable, HidePageErrors to indicate we wish to show errors on this page.  This variable is designated as global  (available everywhere) inside the error handling function, myerror(), which is user constructed, and resides in the utilINC.php file.

When HidePageErrors=TRUE, we default to a generic error message designed for the public, which references a constant value named SUPPORTEMAIL, which will contain the current email address for getting help with the website.

utilINC.php

This file stores our ‘user created’ utility functions.  One of these functions is called dbOut(), which is designed to ‘clean’ the string of data as it leaves the database, and enters our page.  This function is called a wrapper, because it ‘wraps’ other functions that we can now change, as our site develops, or if we need special handling. Placing all the ‘cleaning’ code in a wrapper allows us to change this capability site wide.

 One of the PHP functions dbOut() implements is stripslashes(), which along with its opposite addslashes() render harmless single quotes, which trip up an insertion of data into a database.  In SQL, single quotes are used to designate a string, but must be escaped (by adding a slash in front of the literal quote) to be entered into the database. 

Behind the scenes there are 2 files referenced as include files inside utilINC.php, they are connINC.php & configINC.php. 

connINC.php

All the login and password information is stored in an include file named connINC.php, which also houses a single function conn(), which when called will connect to MySQL via credentials provided.  If no data is entered, the default level of access admin is used.

Inside the function, in lessening order of access, are the following designated sets of MySQL credentials:

Each designated credential set should include the capabilities of the credentials below.  The following relies on you creating MySQL users with the exact capabilities identified.  This is not automatically done.  The idea is that we use the lowest level of access necessary for the particular connection and thereby curb the possibility of SQL Injection Attack.

config.php

Behind the scenes in utilINC.php is config.php, a file for storing site information designed to allow configuration changes.  One piece of data there is SUPPORTEMAIL, which is a constant.  Constants appear by convention as all upper case, and have no ‘dollar’ sign in front of them, but act much like a variable that can’t be overwritten.

Error Handling

There are also error handling functions built into configINC.php.  An error handler is code that processes an error in a custom manner.  We’ll choose to display different data about page errors based upon current conditions.  In general, we want to see errors while we develop, but want to hide them while our users are using our pages. View the following versions of the same test page error.php, which is set to show all errors or display a generic error for users.

Note that there are several different error levels, and many are ‘fatal’, meaning they are not easily caught by code (for example a simple parse error). For more details, see error handling in PHP.

Page Architecture

All of the above files mentioned above create the base page architecture for many of the pages to follow. We can include a single page, utilINC.php, which will bring other related pages along with it, for example, configINC.php & connINC.php. For a diagram, and more information view Page Architecture Details

Final Version of Muffin List/View

Below is final version of the Muffin List/View, with all include files. Use this version as the basis for your List/View assignment, although you will need to choose your own items to list (not muffins).

Self Documenting Code

You may notice some odd handling of 'comments' in these example pages. On the top of the utilINC.php page for example is this set of comments:

/**
 * utilINC.php stores site-wide utility functions
 *
 * Stores functions like myerror(), which handles MySQL and other
 *  or die() errors, myRedirect() to direct users away from pages and 
 *  dbOut() which cleans data coming from MySQL
 *
 *
 * @package ITC280
 * @author Bill Newman <williamnewman@gmail.com>
 * @version 1.0 2008/05/01
 * @link http://www.newmanix.com/itc280/
 * @license http://opensource.org/licenses/osl-3.0.php Open Software License ("OSL") v. 3.0
 * @todo none
 */

These pages are designed to 'self-document' when used with a PHP documentation program such as PHPDocumentor. We'll explore these in detail another time! However, look at what the PHPDocumentor can do to our pages: SELF DOCUMENTED SITE SAMPLE