Note: First, this was written for dB2K, and second, it was written for an earlier specification for HTML. With the advent of HTML 4, there are more capabilities for the Web controls than are listed here. You may want to find a book (or two) on HTML ...
This may get a bit lengthy. Get something to drink, sit down, and prepare to get inundated with information ...
You may want to read, in addition to this document, the HELP file for the web classes, which can be found in the dB2K directories: web\webhelp.hlp -- just double-click it and it'll open up. This includes quite a bit of useful information about how web applications work, including servers and more ...
The purpose of this HOW TO is to help a dB2K developer who is used to working with standard dB2K forms and form controls to understand the basics of how a web application's forms and form controls work.
The most difficult part for most dB2K developers is that a web application doesn't, by definition, allow some functionality that they might like -- the application is not as interactive as it is with a desktop application, and so on. However, with a bit of work, and with the lightning fast capabilities of dB2K, you will find that most of that can be dealt with, with very little effort ...
The next part that takes getting used to is the way the HTML Form controls work, as compared to the way the dB2K form controls work. The hardest part is that you have to either rely on a wizard in dB2K to create you controls and code for you, or you have to hand-code everything. The names of the HTML form controls are different than they are in dB2K, and that makes life a bit interesting as well.
So, let's get started ...
HTML is a constantly evolving method of displaying information on the internet.
That said, there is no simple way to summarize what is already available in books, on the internet itself in tutorials, and so on ...
The basics: HTML is "Hyper-Text Markup Language" -- basically a means of formatting text. It's gotten pretty advanced, and as noted is constantly evolving.
A standard HTML document is simply a text file with a combination of text and and formatting tags. HTML tags are either open-ended (i.e., everything after them take on whatever attributes are given), or are ones that have a begin and an end tag (for formatting, this could include boldfacing text, for example -- normally you want to boldface some of your text, but not all ...). In most cases, the "end" tag is the same as the "begin" tag, but with a slash in front of it, i.e., you would use <B> to represent starting to boldface text, and </B> to stop boldfacing text. Your web browser understands how to interpret these tags.
If you introduce a tag that is not understood by HTML (usually by making a typo), the browser will ignore it. This can be good, and it can be a bit confusing at times ... there are situations where if the tag is not understood, your formatting goes all crazy, and it's hard to know what happened.
So, how do you create HTML? There are a lot of ways. The one I use, is to open WordPad, open Netscape (my browser of choice), and alternate between the two. I modify my HTML document, save the changes, and then in Netscape, if it is not already displayed, I open it, if it is displayed, I click on the "Refresh" button. I can see my changes that easily.
Any text editor will do. You can use the Source Editor in dB2K, as a matter of fact -- and one nice thing there, it highlights the tags in green (by default). It doesn't do any sort of syntax checking, but still ...
There are MANY HTML designer software packages out there, I have found that most of them put extra tags into a document that aren't necessary, and confuse things. But, it's up to you ...
When it comes down to it, there aren't a lot of them. However, it is a good idea to use the following:
<HTML> - this tells the browser it's dealing with HTML itself, although this is fairly obvious, it's a good idea. The HTML tag has an end tag, used at the end of a document. An end tag takes the form of the tag preceeded by a forward slash. The end tag for HTML, for instance, would appear as </HTML>.
<HEAD> -- this is not 100% necessary, but some items go there that can be handy, for example, if you look at an HTML document in the browser, there is usually some text in the titlebar: there is a tag (below) used to define that, and it only gets recognized in the header section of the HTML document.
<TITLE> -- this is the tag noted above, a title tag is used to denote the text you want displayed in the titlebar of the browser. It uses an end tag ... This can only be used inside the header section of an HTML document.
Meta Tags -- these are used for a variety of purposes, most of which I have no idea what they are for. These go in the header section of your HTML document. For CGI applications (dB2K web apps, for example), there is one that you should include:
<META HTTP-EQUIV="Content-Type" CONTENT="text/html">
If you use the web classes, this generated for you, details in the HOW TO on working with the web classes ...
<BODY> -- the body tag has a ton of parameters, for details on those, check any book on HTML (seriously, too much to try to explain here). You can define default colors, and more using this tag. The HTML document goes inside the BODY tags ...
<! -- COMMENTS! Yes, you can put comments into your HTML documents, and just like in dB2K code, they are not displayed for the user. The end of a comment is ->
A basic template:
You may want to use the following as a simple template for creating your HTML documents:
<TITLE>My Sample HTML Document>
<! Anything you want to comment on here ... ->
This is my sample document. I can do whatever I want here ...
Of course, there are tons of formatting tags. A couple you really need to be aware of are the difference between a break, and a paragraph tag.
<BR> -- this causes a 'break' in text. It means that no matter what, the current line ends here, and whatever text follows starts on a new line.
<P> -- this is a paragraph tag -- it means that we're done with the current paragraph, similar to the 'break' tag, but we add a blank line between this paragraph and the next ...
For everything else, you're on your own. Suggested reading: Using HTML, Special Edition, QUE Publishing. The version I have is based on HTML 3.0, and things have changed, I recommend getting whatever the current edition is. If it's as good as the one I have, it will be a handy reference for a long time. (The appendices alone have been fantastically useful ... in mine is a breakdown of all tags and all of their parameters ....)
Forms in web applications are, by default, SDI -- Single Document Interface -- there can only be one form up at a time, basically (it is possible to do some weird tricks, but we're not going to get into those here ...). A standard web application starts with an HTML document, which you might consider to be a menu, and then you select an option, and either a new HTML document is presented, or a program is executed, etc.
Forms are defined in HTML with two tags. The first is the "beginning" form tag:
And a form ends with the "closing" tag:
Seems pretty simple, eh? However, with HTML forms, they really don't do anything unless you tell the application what to do when a form is submitted.
Since we're talking about dB2K applications, we will assume that you want to call a dB2K program when the form is submitted.
To do that, you must use some options in the first FORM tag -- these are then used to call the program, and tell the web server how to handle the application, and so on.
The first parameter is the "METHOD" parameter. This has two different options "GET" or "POST". "GET" passes the values associated with any controls to the program called by the "ACTION" parameter (we'll get there in a second) by displaying them in the browser. This is not often the best way to handle things, particularly if you are concerned with security (passwords, credit card info, etc.). The "POST" option sends the data to the processing program directly, i.e., it does not display in any fashion. You are most likely to want to use "POST".
The "ACTION" parameter is used to tell your web server what program to call, and where it is, when the form is submitted.
By using these two options, a typical FORM tag might look like:
<FORM ACTION="cgi-bin/MydB2KWebApp.exe" METHOD="POST">
That is a pretty simple overview. See the webclass help file as noted at the beginning of this document for more ...
Ok, now we're down to the meat of things ...
Web applications pass the "value" of a control, and the "name" over to the web server, which then passes this information to the program defined in the form's ACTION parameter. These are called "Name/Value Pairs" ... Each control must have a name ...
The following is broken down into sections, titled by the dB2K names of the form controls. The HTML equivalent will be discussed in each section ...
Finally, these controls only ever mean anything to HTML if they are surrounded by FORM and /FORM tags ...
Text and TextLabel
There is no such thing here. Text is text is text in HTML, and there are no specific 'Text' or 'TextLabel' controls. If you type it into your document, it's text, and it gets displayed ...
The most common method of entering data is via an entryfield. In HTML this is done by using this tag:
<INPUT TYPE="TEXT" NAME="somename" SIZE=10 MAXLENGTH=15>
Let's say you wanted to ask for a customer's last name. You could use:
Last Name: <INPUT TYPE="TEXT" NAME="Lastname" SIZE=20 MAXLENGTH=25>
In this example, we have an entryfield, the name of that entryfield is "Lastname" (note that in HTML -- and in dB2K web apps -- names are case-sensitive -- i.e., "Lastname" is not the same as "lastname"). This entryfield is 20 characters wide, and the user can type a maximum of 25 characters into the field. The HTML shown above will look like the following in a web application:
The editor object, unlike most of the form controls we are looking at here, uses a different set of tags than the INPUT object does.
The editor object uses two tags -- one is a begin tag with all the definition in it, and the other is an end tag. These look like:
<TEXTAREA NAME="SomeName" ROWS=nRows COLS=nCols> </TEXTAREA>
The reason for the end tag, is that you can define a default value to appear inside the two tags. If you wanted to set up an editor control that you wanted to use for, say, comments from a customer, you might set it up like:
Comments: <TEXTAREA NAME="Comments" ROWS=10 COLS=60> Enter your comments here </TEXTAREA>
In an HTML form, this would look like:
Note the location of the text? There are ways around this ... The simplest is to put a break tag after the word "Comments:", i.e.,:
Comments:<BR> <TEXTAREA NAME="Comments" ROWS=10 COLS=60> Enter your comments here </TEXTAREA>
We will take a look at another way to get everything to line up after we discuss all of the controls ...
Just like in dB2K, radiobuttons are generally grouped together in HTML forms. The way you group them together is by assigning the exact same NAME property (see below) to each radiobutton associated with a specific decision you wish your user to make. (This is different than how you do this in dB2K ...)
In HTML forms, a radiobutton is defined as:
<INPUT TYPE="RADIO" NAME="somename" VALUE="somevalue">
We use the NAME as noted above, to group the radiobuttons, and as noted elsewhere, as part of the name/value pair. The VALUE property is the value associated with this specific radiobutton, and if this radiobutton is the one selected when a form is submitted, this is the value that is submitted with the name/value pair.
Option: A radiobutton may be "checked" -- this is useful to set a default radiobutton in your form.
NOTE: no text is displayed with a radiobutton -- however, you can display whatever text you wish either to the left or the right, simply by placing the text in your HTML form either on the left or right of the tag.
The text displayed does not have to have anything to do with the value associated with the radiobutton ... this can be a bit confusing, since in dB2K forms, the text is what is stored to a datalinked character field.
An example of a set of radiobuttons used to define a simple "Yes/No":
<INPUT TYPE="RADIO" NAME="YesNo" VALUE="Y" CHECKED>Yes<BR> <INPUT TYPE="RADIO" NAME="YesNo" VALUE="N">No
In an HTML form, this would look like:
You can do quite a bit with these, and the format of them is completely up to you -- the layout can be simple, as shown above, the radiobuttons can be side-by-side, and so on ...
The important things to remember with radiobuttons in HTML forms is that the name must be the same for each radiobutton in a group, and the value is what is actually sent to the server, not the text displayed on the screen (unless they happen to be the same).
Checkboxes look like they act the way that they do in dB2K forms, but there are some serious 'gotchas' -- things you need to be careful of.
The basic syntax is:
<INPUT TYPE="CHECKBOX" NAME="somename" VALUE="somevalue">
There is an optional parameter "CHECKED" which has no value associated with it -- if it is there, the checkbox is checked when the form is displayed, otherwise it is empty/not checked.
In dB2K, a checkbox returns true or false, depending on whether or not it is checked. In HTML Forms, a checkbox returns the VALUE if checked, and NOTHING if not checked. In otherwords, if the checkbox is NOT checked, no name/value pair is submitted with the form for the checkbox! If the checkbox is checked, the VALUE is passed with the name/value pair, not "True" or "False" (unless you set the value to "True" ...). Just like radiobuttons, no text is automatically associated with these, so you must provide it yourself, and again, it can be either on the left or the right.
Below is an example with two checkboxes, one defaults to checked, the other does not:
Red? <INPUT TYPE="CHECKBOX" NAME="Red" VALUE="Red" CHECKED><BR> Blue? <INPUT TYPE="CHECKBOX" NAME="Blue" VALUE="Blue">
In an HTML Form, these would look like:
I was going to try to avoid showing dB2K code in this HOW TO, but for this an example will be very useful. Using the examples above, the following is a way in dB2K source code to check to see if the checkboxes were checked or not, and how to assign a value to your logical field in your table:
// assuming you are using the web classes in dB2K, and the // the object is named "oCGI": if oCGI.findKey( "Red" ) qMyQuery.rowset.fields["Red"].value := true else qMyQuery.rowset.fields["Red"].value := false endif // and a shorter example for the 'blue' checkbox: qMyQuery.rowset.fields["Blue"].value := oCGI.findKey( "Blue" )
The findKey() method is part of the Associative Array class, which is what the webclasses are based on. The method returns true or false, and so in the shorter example, if the checkbox was checked, there's a name/value pair, if not there is no name/value pair, so there we go ...
Listbox and Combobox
The ListBox and the Combobox are heavily related in HTML forms, as they are really the same control, a "Select" control, and how you define them determines whether you get a combobox or a listbox.
In either case, the control has more tags than any of the others shown here. First, you need the SELECT tag:
There are two optional parameters -- SIZE, which is a number corresponding to the number of "rows" to display, and MULTIPLE, which is used by itself, and if it is there, it allows the user to select multiple options in the list provided.
Next, there is the OPTION tag, which is used to define each of the items to be displayed for your list. You must define all of your options between the SELECT tag, and the "End" SELECT tag ... (you'll see this in a moment).
The option tag works like this:
<OPTION VALUE="somevalue">Text to display
And there is an optional "SELECTED" parameter, which is used to define a default value for the list (i.e., when the form opens, if an item in the list has the SELECTED parameter, it will be the default).
Note that just like with checkboxes and radio input objects, there is no automatic text displayed with an option for a select object -- in other words, you have to provide the text ... in this case, the text must be placed after the option tag.
Finally, there's the "End" tag:
Now, putting it all together, let's say you have a list of colors:
Select a color: <SELECT NAME="Colors"> <OPTION VALUE="Blue">Blue <OPTION VALUE="Red">Red <OPTION VALUE="Green" SELECTED>Green <OPTION VALUE="Yellow">Yellow </SELECT>
In this example, the default value for the list will be 'Green'.
In a form, we would see:
Because no size was given, and because the MULTIPLE option was not given, this is a combobox as you are used to seeing in dB2K forms.
In order to make this a 'ListBox', either set the SIZE, or the MULTIPLE parameters (or both).
In other words, changing the above to:
Select a color: <SELECT NAME="Colors" SIZE=3> <OPTION VALUE="Blue">Blue <OPTION VALUE="Red">Red <OPTION VALUE="Green" SELECTED>Green <OPTION VALUE="Yellow">Yellow </SELECT>
Will result in the following in a form:
If you want your users to be able to select MULTIPLE options, you would set the MULTIPLE property as in below:
Select a color: <SELECT NAME="Colors" MULTIPLE> <OPTION VALUE="Blue">Blue <OPTION VALUE="Red">Red <OPTION VALUE="Green" SELECTED>Green <OPTION VALUE="Yellow">Yellow </SELECT>
Which results in the following in a form:
By holding the Control key down (on a PC, I think it's the "Command" key on a MacIntosh, but it's been many years since i used one), and clicking on multiple items, the user can select any or all ...
Finally, combining the size and multiple parameters, we get:
Select a color: <SELECT NAME="Colors" MULTIPLE SIZE=2> <OPTION VALUE="Blue">Blue <OPTION VALUE="Red">Red <OPTION VALUE="Green" SELECTED>Green <OPTION VALUE="Yellow">Yellow </SELECT>
Which results in the following in a form:
The width of the select box is defined by the width of the widest OPTION defined ...
The SUBMIT pushbutton is used to submit a form. The RESET pushbutton is used to clear out any selections made by the user in a form.
Both of these buttons allow you to change the text, by using the VALUE property ...:
<INPUT TYPE="SUBMIT"><BR> <INPUT TYPE="RESET" VALUE="Clear It Out!">
In a form, these would look like:
The default text for the submit button is "Submit Query" as shown above, and the default text for a reset button is "Reset".
There are other controls that you should be aware of.
In dB2K, to create a password masked entryfield (i.e., an entryfield that hides what is being typed in so prying eyes cannot see it), you have to do a lot of work trapping keystrokes and so on. In HTML, there is a simple control:
Enter Password: <INPUT TYPE="PASSWORD" NAME="Password" SIZE=10 MAXLENGTH=15>
To see this in a form:
In addition to the Password control, there is another one that is VERY useful to a dB2K web application, and that is a "Hidden" object.
The purpose of the hidden object is to be able to pass a value from one application to another. (Your dB2K web apps are generally multiple .EXE files.) This allows you to have a form of 'state' control -- i.e., a user selects a record, if you store the value of a key field in a HIDDEN control, you can pass that to the next .EXE, and the user doesn't have to see that key field value.
It works very simply:
<INPUT TYPE="HIDDEN" NAME="SomeName" VALUE="SomeValue">
Showing this in a form would be sort of pointless, since it is hidden -- this will not display, even though it uses the "INPUT" tag.
HTML Tables -- this is a very complex area, and so we are only briefly going to touch on it. However, it is useful to have at least a basic grounding in how these work, so that you can get your HTML forms to look the way you expect them to.
Nobody wants a form where the text is lined up funny compared to the controls, so being able to use an HTML table to lay everything out can be quite useful when designing your forms.
Like various tags, the TABLE has a start and end tag. The start tag is used to define various aspects of the table.
The TABLE start tag has a couple of options we'll look at here, and there are others ...
<TABLE WIDTH=75% BORDER=1>
What the above does is define a table that is 75% of the width of the browser screen, and has a small(ish) border around each cell and the outside of the table. For designing your app, setting the border is useful, just so you can see where things are lining up. You may want to remove the border when done designing the form, or you may decide you like it, and decide to leave it ...
Once you have defined the table, you have to define table ROWS, and inside of each table ROW are table DATA (or cells). Each row has attributes, as do each of the cells.
A table ROW is defined as:
<TR ALIGN="somevalue" VALIGN="somevalue">
And each row ends with an end tag ... The alignment values are:
For ALIGN (which is horizontal
alignment): "Left", "Right", or "Center"
For VALIGN (vertical alignment): "Top", "Middle" or "Bottom"
If these are left out, then the default is LEFT and TOP.
Table DATA (cells) are defined as:
<TD ALIGN="somevalue" VALIGN="somevalue" WIDTH=somenumberOrPercent>
Each cell ends with an end tag. There are other options as well. The ALIGN and VALIGN for the Table Data tag override the Table ROW setting. The width is either a number in pixels, or a percentage of the width of the table.
There is a table HEADER tag, which defines headings on the left and/or right of the table. If you are interested, you can look 'em up somewhere ...
Now, let's say we want to define a form that asks the user for their name (first and last), address, and to select a color. Fairly simple, but you want everything to line up nice and neat, as well ...
It might look like:
<CENTER> <TABLE WIDTH=75% BORDER=1> <TR VALIGN="TOP"> <TD ALIGN="RIGHT"> First Name: </TD> <TD ALIGN="LEFT"> <INPUT TYPE="TEXT" NAME="FirstName" SIZE=15 MAXLENGTH=25> </TD> </TR> <TR VALIGN="TOP"> <TD ALIGN="RIGHT"> Last Name: </TD> <TD ALIGN="LEFT"> <INPUT TYPE="TEXT" NAME="LastName" SIZE=15 MAXLENGTH=25> </TD> </TR> <TR VALIGN="TOP"> <TD ALIGN="RIGHT"> Select a color: </TD> <TD ALIGN="LEFT"> <SELECT NAME="Colors" MULTIPLE> <OPTION VALUE="Blue">Blue <OPTION VALUE="Red">Red <OPTION VALUE="Green" SELECTED>Green <OPTION VALUE="Yellow">Yellow </SELECT> </TD> </TR> </TABLE> </CENTER>
Oof. A bit confusing, eh? Ok, you can stack HTML tags on the same line, the HTML interpreter doesn't care. One thing that might help is to insert comments in there, to break out the individual rows of the table, which would make it easier to read.
Now, putting all that into a form, we get:
Hey! Now that turned out pretty cool. You would want to add a submit and probably a reset button in there, but ...
And now that you have it lining up, you could remove the BORDER setting for the table, or, you could leave it, if you prefer it like that.
Ok, I've used a couple of tags throughout this document that aren't discussed here, and we haven't looked at images yet, and the one more VERY useful set of tags and we'll be done ...
The FONT Tag
The FONT tag can be used to change the font, the color, and/or the size of the text. It is used a lot when working with HTML. Remember to turn it off, or you will end up formatting everything in your document ...
<FONT COLOR="somecolor" SIZE=someattribute FACE="SomeFontName">
Where "somecolor" is either a text color name that you know works (such as "Blue", "Red", etc.), or a hexidecimal color definition (you'll have to look those up ...).
"someattribute" used with the SIZE option is +1 through +6, and -1 through -6. You don't need much to make things REALLY large or way too small to read, so be careful with this.
The FACE option is used to define a font ... be careful and be sure to use a font that most folk are likely to have on their machines, such as "ARIAL" ...
To make something really stand out, try:
<FONT COLOR="RED" SIZE=+1 FACE="Arial">Got Your Attention Yet?</FONT>
This would look like:
Got Your Attention Yet?
The Horizontal Ruler
The Horizontal Ruler is sort of related to the dB2K LINE object, but only sort of ...
<HR WIDTH=somenumber SIZE=somenumber ALIGN="SomeSetting">
Where, for example, the width could be either a percentage of the width of the page (I used 25% in some of the stuff above in this document), or a specific width in pixels.
The SIZE refers to the thickness of the line. Experiment ...
ALIGN refers to horizontal alignment -- it defaults to the CENTER, but you can set it to LEFT or RIGHT, if you wish.
Here are some examples:
<HR> <HR WIDTH=75% SIZE=2 ALIGN="RIGHT"> <HR WIDTH=50% SIZE=3 ALIGN="LEFT"> <HR WIDTH=10% SIZE=6 ALIGN="LEFT">
And these would look like:
The Image Tag
Images can be tricky, but of course they are used all over the place on the web. Images are used to navigate, to display useful information, to be silly, whatever ...
The Image tag has quite a few options associated with it (as you might imagine). Without going into all of them ...:
<IMG SRC="filename" ALT="text" ALIGN="somevalue" BORDER=somenumber>
The SRC option is the actual path/name to the image file. NOTE: since HTML doesn't know what a dBASE table is, you cannot give: form.rowset.fields["MyImage"] as the SRC for an image in HTML.
ALT is used to display some text in the case of a large image or a slow server (or both), so that while the image is displaying the text is displayed. This same text will appear in a speedtip if the mouse is held over the image for any length of time.
ALIGN has a lot more options than you might expect ... These include "TOP", "MIDDLE", "BOTTOM", "LEFT", "RIGHT", "TEXTTOP", "ABSMIDDLE", "BASELINE", and "ABSBOTTOM". Amazing, huh? Most of these are pretty straightforward.
BORDER is only useful if an image has an address reference tag around it -- if you set the border to zero, no border appears, if you set it to a larger value (the default is something like 1), the border appears.
Using a small image file, here are some examples ...
<IMG SRC="db2k.gif"> <P> <IMG SRC="db2k.gif" ALIGN="RIGHT"> <BR CLEAR="ALL"> Powered by: <IMG SRC="db2k.gif" ALIGN="ABSMIDDLE">
Note the use of the Break tag with an option we haven't discussed, the 'Clear' option, which is used to clear text around an image ...
And this is how all that would look:
The Anchor tags are used to allow a user to move between HTML documents, call CGI programs, and even jump around in the same document ...
In order to move around in the same document, you must create a NAME tag, which is basically assigning a location in the document to which a name is then associated. These names are case-sensitive.
An example might be:
These tags are invisible to the user. However, if you wanted to then set up a link that the user could click on to jump directly to that spot in the document, it would be done as:
<A HREF="#AnchorTags">Go to Anchor Tags Section</A>
If, instead, you want to have the user be able to click on a link to another HTML document, the anchor tag would look like:
<A HREF="MySecondPage.htm">Go to Second Page</A>
Now, you can get even fancier, and if you have defined in the document named "MySecondPage.htm" a named anchor reference (as defined above), you could do this:
<A HREF="MySecondPage.htm#AnchorTags">Go to Anchor on Second Page</A>
However, all of that aside, something that any dB2K web app developer is going to need, is to be able to link to an executable. Guess what? It's just as easy as linking to an HTML document ...
<A HREF="cgi-bin/MyWebApp.exe">Launch My Web App</A>
There are other options, including links for email, and a lot more, that can be done with these tags, but this is here to get you started, not to be the "ultimate guide" ...
Well, we've covered a lot of ground ... here's hoping you've learned enough to help get you started.