Your First Web Database
Program
After you write the program Hello World, you’re ready to go one step further. In this chapter, you will build a program that allows users to search a contact database and display a search result. Your program does not require many Overlay tags—only a few; but it does require that you learn how HTML/OS stores and displays variables, how to use an Overlay tag called DBFIND that searches databases, and how to use LAYOUT, an Overlay tag for reorganizing information in variables.
This chapter introduces you to the concept of two-dimensional data, an important concept used throughout HTML/OS. You’ll learn how to create a database with a program called dbConsole. You’ll then learn how to write the tag to fill a variable with multiple rows and columns of search results and how to reorganize that variable so it displays nicely on the page. Figure 4.1 illustrates the program you will build.
1
Chapter
44
You start by creating a database and populating it with sample data. You use dbConsole, a point-and-click Web application for creating and managing databases, as described in the next section.
Creating a Database
To create a database, click the dbConsole icon on your HTML/OS desktop. Then select Create. You should see a screen like that shown in Figure 4.1.
A First Look at HTML/OS Databases—The following list contains a quick introduction to the basic concepts of HTML/OS databases:
1. The HTML/OS database engine is a high-performance engine capable of serving thousands of users simultaneously.
2. HTML/OS databases look like spreadsheets placed on their sides. Instead of columns, they have fields. Instead of multiple rows, they have multiple records. HTML/OS databases can contain over a million records each. Each record can contain hundreds of fields.
3. The first field of an HTML/OS database record is called record. It contains a number that uniquely identifies the record. The record field is followed by the fields you set up. 4. In HTML/OS, databases and database tables are the same things, because HTML/OS
database tables do not need to be linked together with schemas, a technique used by relational databases off the Web to join multiple database tables together. HTML/OS can join multiple database tables together at program time, a feature not typically found in database engines. This topic is discussed in further detail in Chapter 20, Database Joins.
5. The HTML/OS database engine works with your Web server. It does not need a separate database server like off-the-Web database engines. There is no database server to maintain, and you can manage the database engine easily through a Web-based program called dbConsole.
6. The HTML/OS database engine is built directly into the HTML/OS engine. To access the database from within your HTML documents, you use tags such as DBADD, DBEDIT, and DBFIND. No SQL (a widespread database query language) is needed. Unlike SQL-based solutions, HTML/OS is a type of Fourth Generation Language (4GL). When using 4GLs, database programming is simplified, because you need to use only one tag per database operation. HTML/OS databases are discussed in further detail in Chapter 11, What Is a Web Database.
To set up your contact database, specify the names of the fields you want in the database along with the field type and field length for each. In the example here, you use a database with four fields: contact_company, contact_name, contact_phone, and contact_email(excluding the field record, which is created automatically).
Set the field type of your fields to STR. STR stands for string, which is computer talk for text. Specify a field length for each of your fields. Use the values shown in Figure 4.1. Set the database name to /mycontacts, and click the Create Database button. You have created your first database.
Open the database by clicking Open in the left column of dbConsole. Your database is in the Home directory because you named it /mycontacts. (Names beginning with a slash are in the Home directory.) Then click Edit in the left column to edit a new or existing record. Add a contact to the database. Enter the contact data for your fields, and click the Save button above the record. Click the New button above the record to start a new record. Repeat until you have entered four or five records.
Creating your Web Page
You’re ready to build a Web database program. Just as in Chapter 3, Your First Program, you design your program from the top down. Exit dbConsole and use the File Manager to create a new file. Fill it with the following HTML code:
<html>
<form method=post ACTION=[Location1]> <font size=2>Enter Search:</font><br> <input type=text name=mysearch size=15> <input type=submit value=”Find”>
</form>
Search Results: [Location2] </html>
To view the Web page, click the Save/View button in your Web-based editor. You should see an HTML page that has a search box with a Find button and a place for a search result.
Adding the Overlays
In the code you entered previously, the parameter ACTION is set to [Location1] and [Location2] is placed where search results should be displayed. To complete your program, you need to write code for [Location1]and [Location2]. Since you want to redisplay your Web page when the user clicks the Find button on the page, you need to set
[Location1] to the page name by replacing ACTION=[Location1] with ACTION=<<page>> or ACTION=”/mypage.html” assuming your page is called “/mypage.html”.
[Location2] is where you insert an Overlay that searches your contact database and displays a message or a search result. What you display depends on the value of mysearch. The first time the user accesses the page, the variable mysearch is equal to ERROR, because variables in HTML/OS default to the value ERROR. On the other hand, if a user enters a search, mysearchis equal to the value the user typed into the input box. In this second case, you want to conduct a search of your database and display a table of results.
The Overlay at [Location2]needs to take into account these two cases. By using an IF-THENstatement, you can selectively perform a search when mysearchis not equal to ERROR and display a text message when it is not. Your Web page, with [Location1] and [Location2]swapped out for the proper code, is shown here:
<html>
<form method=post ACTION=<<page>> > <font size=2>Enter Search:</font><br> <input type=text name=mysearch size=15> <input type=submit value=”Find”>
</form>
Search Results:
<<IF mysearch=”ERROR” THEN
DISPLAY “Please enter search above. “ /DISPLAY ELSE sstr = ‘contact_name ~ ‘ + ‘“‘ + mysearch + ‘“‘ mydata = DBFIND(“/mycontacts”,sstr,1,20, “contact_company,contact_name,contact_phone,contact_email”) mynewdata = LAYOUT(mydata, [1], “ “, [2], “ “,[3], “ -“,[4], “<BR>”)
DISPLAY mynewdata /DISPLAY/IF>> </html>
The tags that perform a search are placed between the ELSE and the /IF in the IF-THEN statement. The tags DBFINDand LAYOUTare used. The tag DBFINDsearches a database and
places a subset of the records it finds into mydata. The LAYOUTtag is used to format the data in mydataso it can be displayed with the DISPLAYtag. The remainder of this chapter gives you a detailed explanation of how this application works.
Understanding Your Application
The following sequence of steps occurs when a user runs the Web page presented in the preceding section:
1. When a user enters a value in the search box and clicks the Find button, the text that user entered into the input box is transmitted to the Web server and saved into the variable mysearch.
2. The HTML/OS engine scans the Web page from top to bottom. As it moves through the file, it creates an HTML page for the user. The first Overlay it encounters is <<PAGE>>. HTML/OS adjusts the HTML form so it links back to the current page. <<PAGE>>is a tag that contains the name of the current document.
3. The next Overlay HTML/OS encounters is below the words Search Results. The IF-THEN statement in the Overlay runs the instructions between the ELSE and the /IF in the event mysearchis not ERROR. In this case, the Overlay fills the variable sstr with a query string. The instruction uses plus (+) signs to paste text together. If mysearch is equal to george, the instruction would fill sstrwith contact_name ~ “george”. HTML/OS uses the variable sstr as the input of the DBFINDtag on the following line.
4. HTML/OS runs the DBFIND Overlay tag. The tag fills mydata with a table of information. It can do this because HTML/OS variables are two-dimensional. They have one or more columns and one or more rows. The accompanying “Understanding HTML/OS Variables” note discusses how HTML/OS stores variables. A more thorough discussion is provided in Chapter 5, Working with
Variables.
The five parameters in DBFIND define which database to search, which records to retrieve, and which search results to place in mydata. Like all HTML/OS tags, parameters are separated from each other with a comma. Parameters can be literal text, expressions, other tags, or variables. The first parameter of DBFINDis the name
of the database. The second parameter contains the search criterion, also known as the Boolean query. If the Boolean query is empty, it means you want to extract records from the entire database. If that parameter contains a value like contact_name ~ “J”, DBFIND extracts only those records in the database with contact names beginning with the letter “J”. Boolean queries are discussed in greater detail in Chapter 12, Boolean Queries.
The third, fourth, and fifth parameters tell DBFINDwhich records to put into mydata. The third and fourth parameters tell DBFIND to fill mydata with the first up to the tenth search result. If it finds less than ten results, it places only what it finds in mydata. If DBFINDfinds no results, it sets mydata to an empty string—a one-row-by-one-column cell that’s empty. If it finds more than ten records, it puts only the first ten items it finds into mydata. The last parameter is a list of field names. It tells DBFIND what to put in each column of mydata. The columns of mydata are filled from left to right in the same order as the fields you specified in the parameter. DBFIND is discussed in further detail in Chapter 14, Building a Database Search
Page. It is also defined in Appendix C, Major HTML/OS Tags.
5. After running the DBFIND tag, HTML/OS runs the LAYOUT tag. The tag is used to reorganize mydata, so when the results display on the screen, the HTML you see is ordered the way you want. This formatting is needed, because displaying the contents of mydataon the screen produces an ugly presentation. The LAYOUTtag is described after Step 7, which is the last step taken when this Web page runs.
6. The line DISPLAY mynewdata /DISPLAYruns, placing the contents of mynewdata, the table of search results, into the Web page.
7. The Web page generated by HTML/OS is transferred to the user’s computer and displayed with a browser.
Understanding HTML/OS Variables—HTML/OS variables are two-dimensional. Most of the time, variables have one column and row; they never have less. You may want to think of HTML/OS variables as mini-spreadsheets with a minimum size of one column by one row. For example, the instruction myvariable = 5 creates the variable myvariable with one column and one row containing the value 5. When HTML/OS variables are only one column by one row, you don’t think much about their two-dimensionality. You work with them without regard to their ability to have more rows or columns; but when you need tables of well-organized values, HTML/OS’ two-dimensionality becomes indispensable. Searching
databases is a prime example. (For a more comprehensive discussion of databases, see Chapter 11, What Is a Web Database.) A database search typically yields multiple records, and each record has multiple fields. Because HTML/OS variables are two-dimensional, you can place the results of a search in a single variable. Field values are placed in different columns of a single row. The variable is filled, one record per row. As another example, suppose you want to work with a comma-delimited file containing login names and
passwords. (A more comprehensive discussion of delimited text files is provided in Chapter 6, Working with Variables.) You can load the delimited file into the cells of a variable with a single COPY tag. Or suppose you want to add up the values in a column of a variable; again, only a single tag is needed. HTML/OS variables are discussed in further detail in Chapter 5.
Using the LAYOUT Tag
When HTML/OS displays multicell variables, it displays each cell, one after the other, left to right, top to bottom, with nothing between each cell. Suppose mydata contained the following data:
John Smith 212-555-1212 Janet Jones 310-555-1212 Jack Chen 415-555-1212
The code DISPLAY mydata /DISPLAYwould generate the following text in your HTML document:
JohnSmith212-555-1212JanetJones310-555-1212JackChen415-555-1212
This is not acceptable. You want your search results to appear as they do in Figure 4.2. The HTML code for such a search result looks as follows:
John Smith - 212-555-1212 <br>Janet Jones - 310-555-1212 <br>Jack Chen - 415-555-1212 <br>.
Working backwards, since you know that HTML/OS displays data in cells of a variable left to right and top to bottom, displaying the following six-column variable produces a page like that shown in Figure 4.2.
John - Smith - 212-555-1212 <br>
Janet - Jones - 310-555-1212 <br>
Jack - Chen - 415-555-1212 <br>
To create this variable from mydata, use the LAYOUT tag, which is designed to take a variable with many columns and rows and produce a new variable with just as many rows but with columns filled in according to the parameters you specify in the tag. In this case, you want to build a six-column variable called mynewdata from mydata. The first, third, and fifth columns in mynewdatacome from mydata. The second, fourth, and sixth columns in mynewdata are filled with a space, a dash and a <BR> respectively. The instruction mynewdata=LAYOUT(mydata,[1],” “,[2],” –“,[3],”<BR>”)is what you need. The LAYOUT tag works as follows: Its first parameter is the input variable. All other parameters specify what to place in each column of its output. The LAYOUTtag works from left to right, creating columns in an output variable as it reads its own parameters. It starts with its second parameter and moves right until there are no more parameters. If a parameter contains quoted text, the entire column in the output variable is filled with the text. If the parameter is a column number in square brackets, the column in the output is copied from the specified column of the input variable.
In your example, the first parameter of LAYOUT is mydata, the three-column variable containing the result of your search. The remaining parameters define what you want to appear in each of the six columns of mynewdata. Note how you are using two kinds of parameters. To specify a column from the starting variable, you include the column number in square brackets. On the other hand, to fill a column with text, you specify the value explicitly.
Reformatting Your Report
The code in the “Adding the Overlays” section in this chapter produces a report with fields separated by dashes. (Refer to Figure 4.2.) You will more likely want to format your search result in columns using an HTML table. You may want to add column headers too. To accomplish this, you should change the parameters in LAYOUTso the tag displays multiple HTML table rows, each beginning with a <tr><td>and ending with a </td></tr>. You need to place the tags, <table>and </table>around the rows as well to delineate them. Rewrite your page as follows:
<html>
<form method=post ACTION=<<page>> > <font size=2>Enter Search:</font><br> <input type=text name=mysearch size=15> <input type=submit value=”Find”>
</form>
Search Results:
<< IF mysearch=”ERROR” THEN
DISPLAY “Please enter search above.” /DISPLAY ELSE sstr = ‘contact_name ~ ‘ + ‘“‘ + mysearch + ‘“‘ mydata = DBFIND(“/mycontacts”,sstr,1,20, “contact_company,contact_name,contact_phone,contact_email”) DISPLAY “<table border=1>” + “<tr><td>Company</td><td>Name</td><td>Phone</td></tr>” /DISPLAY mynewdata = LAYOUT(mydata, “<tr><td>”, [1], “</td><td>”, [2],
“</td><td>”, [3], “</td></tr>”)
DISPLAY mynewdata /DISPLAY DISPLAY “</table>” /DISPLAY /IF
>> </html>
This code displays a report in table format as shown in Figure 4.3. You can experiment with the parameters in LAYOUT to vary the look of your report. Alternatively, you can control your display by using FORloops, which are discussed in Chapter 6,Working with Variables.
Summary
In this chapter, you created your first Web database program. Unlike the previous chapter where you learned the Hello World program, here you set up and accessed a database, worked with two-dimensional data and did some programming. Unfortunately, you did this without any fundamental understanding or description of how HTML/OS works.
In the next two chapters, you return to the basics. You learn more about variables, how to place Overlays in documents, and how to use the most important Overlay tags. The next FFiigguurree 44..33:: Your Web database program looks like this with nicely formatted search results.
two chapters serve as a solid foundation for those chapters that follow them dedicated to specific areas of advanced Web development.
Exercises
The following exercises give you a feel for working with the LAYOUTtag. The last exercise builds on what you learned in the previous chapter regarding select boxes and the ability to use them to vary the value in a variable. Answers to all exercises are provided on this book’s companion Web site as described in the book’s Preface.
Exercise 1
Extend your report so it displays contact_email. You need to modify the LAYOUTtag to accomplish this.
Exercise 2
Add a select box to the HTML form that gives the user the ability to select a page size of 20, 40, or 100. Hint: Set the variable name of the select box to page_sizeand substitute the 20 in DBFINDwith the variable.