Chapter Three

Getting Started with PolyForm

It's easy to get started with PolyForm, and this chapter will show you how. You will learn to use the PolyForm Control Panel to create a series of instructions on how to handle information someone types into a form and submits.

These instructions are called a script. We call the information typed into the form the form contents. Since the form, the script, and sometimes other files all work together, we often refer to the whole set as an application.

The script tells the PolyForm CGI program which form to use, if and how you want to save the form contents, what you want to send back to the browser, and what kind of (if any) email you want PolyForm to send regarding the form contents.

The fastest way to create a new form and script is to use the PolyForm Script Wizard, which you start from the PolyForm Control Panel. You can create a form and its script, and try them out in about a minute! It might take a little longer the first time, but not much longer. You can later fine-tune the form by editing the HTML form file; you can change the script as well, using the PolyForm Control Panel.

This chapter will:

• Show you how to run the PolyForm Control Panel
• Introduce you to the PolyForm Control Panel menus, toolbar icons, and tabs
• Give you step-by-step instructions for creating a script with the Script Wizard
• Give you step-by-step instructions for creating a script with the PolyForm Control Panel
• Introduce you to several additional menu options

After reading through this chapter to create your first applications, you will be ready to add forms to your web.

Starting the PolyForm Control Panel

The method for reaching the PolyForm Control Panel icon that is used to run the PolyForm Control Panel, depends on the operating system you are using.

If your operating system is Windows 95 or Windows NT 4.0, PolyForm's Setup program creates a folder on your program menu called PolyForm 1.0. This folder contains three icons:

PolyForm CGI

Displays on your desktop a running count of the number of times forms have been submitted to PolyForm.

PolyForm Control Panel

Enables you to create PolyForm scripts and applications.

PolyForm ReadMe

Displays the release notes.

If your operating system is Windows NT 3.51, you selected a Program Group for your PolyForm icons during installation. The Program Group contains the icons listed above, plus the PolyForm Uninstall icon.

Select the PolyForm Control Panel icon and press Enter to start the PolyForm Control Panel. (See Figure 3-1.)

The first time you run PolyForm Control Panel, you should indicate which Web browser you use. On the Options menu choose Settings. Choose the Applications tab. Use the browse button beside the Browser field to indicate the path and filename of your Web browser. You may also use the browse button beside the Text Editor field and the HTML Editor field to indicate the path and filename of the editors you want to use. For more information see "Changing the PolyForm Control Panel Settings," at the end of this chapter.

The section of this chapter called "Using the PolyForm Control Panel to Create a Script," gives you step-by-step instructions to create a script as quickly as possible. If you feel like you are ready, skip ahead to that section now. Otherwise keep reading and you'll get a quick tour of the PolyForm Control Panel's menus and tabs.

Overview of the PolyForm Control Panel

When you first open the PolyForm Control Panel (either through the Start menu in Windows 95 or by double clicking the icon in a Windows NT Program Group) it is ready for you to get to work. (See Figure 3-1.)

Figure 3-1 PolyForm Control Panel

Notice the menus, the toolbar, and a series of tabs that make up the PolyForm Control Panel. A brief synopsis of the menus and toolbar icons is presented in Table 3-1.

Table 3-1 Synopsis of menus and toolbars icons

The Form Tab

The tab that is displayed when you open the PolyForm Control Panel is the Form tab. You may enter the name of an existing HTML form, or create a new form. The buttons to the right of the Form Filename field are the Browse button and the Edit button. Use the Browse button to create a new file, and use the Edit button to edit the HTML source. The "Allow only this Form to run this Script" checkbox is a security feature, discussed fully in Chapter 4, PolyForm Tools.

The Save to File Tab

On the Save to File tab, shown in Figure 3-2, you select an option for saving the form contents to the server's disk drive. You may save the form contents in a text file, in a data file, in one of two kinds of templates, or not at all. Each method of saving the form contents is discussed in detail in Chapter 4, including step-by-step instructions.

Figure 3-2 Save to File tab

The Send to Browser Tab

The Send to Browser tab, shown in Figure 3-3, gives you three options for the type of document to send to the form user's browser after a form is submitted: the URL of an existing document, a document based on a template that is an HTML document into which PolyForm has inserted information from the form, and a document that simply echoes the information entered into the form.

The Send to Browser tab also allows you to enter a Window Target for sending results to a specific window or frame in browsers that support frames. See Chapter 4 for details on these features.

Figure 3-3 Send to Browser tab

The Email Options Tab

On the Email Options tab, shown in Figure 3-4, you can tell PolyForm to send two types of email. One type is a simple list of the form contents sent to an email address you enter on this tab; it may also be a list of email addresses in a file. The other type of email message is based on a template, and may be sent to an email address entered on the form. Again, see Chapter 4 for complete descriptions of these features and step-by-step instructions on how to use them.

Figure 3-4 Email Options tab

Using the Wizard to Create a Script

PolyForm's Script Wizard is the easiest way to create a script. You choose which of the included forms to use, select a few options, and-voila!-you are ready to go.

The wizard displays the entire list of forms to choose from, but here are a few examples:

• A blank form you can customize later by editing the HTML source
• An information request form for users to request information about one or more items you list on the form
• A feedback form to ask for the user's name, email address, and comments
• Two different order forms
• A timesheet form

The rest of this section walks you through the steps to create a feedback form and script with the wizard. As you work through the following step-by-step instructions you will start by creating a feedback form document. The script you create will do the following: When someone types information in the form, then clicks the submit button, the script sends a document back to the browser that shows the user what has been typed. PolyForm also sends the form contents to you in an email message.

Here are the main steps of the process:

1. Start the Script Wizard.
2. Select the feedback form.
3. Don't save the form contents on disk.
4. Select what the user should see after submitting the form.
5. Enter your email address.
6. Name the script.
7. Build the form and script.
8. Run the script; this loads the form in your browser.

Step 1: Start the Script Wizard

The first step is to start the Script Wizard. To start the PolyForm Script Wizard, follow these steps:

1. Be sure that your Web server is running, and start the PolyForm Control Panel. To run the PolyForm Control Panel use the Start menu in Windows 95, or double click on the PolyForm Control Panel icon in the Windows NT PolyForm Program Group.
2. On the toolbar, click the wizard icon. Or, choose Script Wizard on the File menu. The PolyForm Script Wizard appears. (See Figure 3-5.)
3. Choose Next to continue. The Form screen appears.

Figure 3-5 PolyForm Script Wizard

Step 2: Select a Form

On the Form screen choose the form with which you want to work. For this example, select the Feedback Form.

1. Click the down arrow for the dropdown box to display the list of forms. (See Figure 3-6.)
2. Select Feedback Form.
3. Choose the Next button to continue. The Save form contents screen appears.

Figure 3-6 PolyForm Script Wizard Form screen

Step 3: Select How to Save the Form Contents

The wizard gives you three options for saving the form contents. You may choose to save as a simple text file, as a data file, or not to save at all. For this example, you will email the form contents to your email address instead of saving to disk.

1. On the Save Form Contents screen select the Don't Save radio button. (See Figure 3-7.)
2. Choose Next to continue. The Response to Browser screen appears.

Figure 3-7 PolyForm Script Wizard Save Form Contents screen

Step 4: Select What the User Should See After Submitting the Form

Whenever someone submits a form to PolyForm, PolyForm sends an HTML document back. This return document is called the response to the browser. The wizard gives you two choices: a very simple document that echoes the form contents, or the URL of a file that you create separately.

It is very easy to choose the first option, even if you plan later to create a specific HTML document to send to the user's browser. For this example, select the first option: to echo the form contents.

1. On the Response to Browser screen, select Send a Simple Confirmation of Data Received. (See Figure 3-8.)
2. Choose Next. The Emailing screen appears.

Figure 3-8 PolyForm Script Wizard Response to Browser screen

Step 5: Enter Email Information

When using the wizard, you may decide to send the form contents to an email address you enter. Sometimes you might want to do this in addition to or instead of saving the form contents in a file.

The script you are building will send the form contents to you by email. On this screen you also enter the From and Subject of the email message. (See Figure 3-9.)

1. Select the "Copy Form Contents To:" checkbox.
2. Type your email address in the accompanying textbox.
3. Type your name in the Name or Organization field.
4. Type Feedback Form in the Subject field.
5. Choose Next. The Script Name screen appears.

Figure 3-9 PolyForm Script Wizard Emailing screen

Step 6: Enter a Name for the Script

The script name must contain only letters, numbers, and underscores; no spaces or other symbols are permitted. Also, it must be 32 characters or fewer in length.

We recommend you use names that describe the purpose of the form and script. In this case, you might use Feedback_Form. You may also want to establish a standard approach to naming scripts. This example begins each word with an uppercase character, and connects words with an underscore. If you always follow the same standard, it will be easier to avoid mistakes.

1. Enter Feedback_Form on the Script Name screen. (See Figure 3-10.)
2. Choose Next. The Ready For Setup screen appears.

Figure 3-10 PolyForm Script Wizard Script Name screen

Step 7: Finish the Script

You are now almost done creating the script. If you want to review your selections, you may choose Back one or more times to view previous screens.

1. On the Ready for Setup screen, choose Next.
2. The wizard builds the script, creates the form, displays a progress bar, and displays the Script Complete screen.
3. On the Script Complete screen, choose Finish.

The wizard closes, and the new script is open in the PolyForm Control Panel.

Step 8: Run the Script

You run your script by opening the form in a browser, entering information on the form, and pressing the Submit button. PolyForm then executes the script and responds accordingly. If the form and response are what you expected, your wizard experience was a success. Note that you can always enhance the form or the script from the PolyForm Control Panel.

You can also run PolyForm scripts simply by choosing Run on the PolyForm Control Panel Options menu. The Run command uses your Web browser and server to load the form associated with the open script. You may then enter information and submit the form to run the script. You may, however, need to bring the browser window to the front, as follows.

1. On the PolyForm Control Panel Options menu choose Run.
2. PolyForm loads the form in your browser.
3. Enter the requested information. (See Figure 3-11.)


Figure 3-11 Feedback Form

4. Choose Submit. The browser displays the contents of the form. (See Figure 3-12.)


Figure 3-12 Response to browser

Congratulations, you have just created and run your first PolyForm script!

You will also receive the form contents as an email message if you have an SMTP mail server installed and configured. You may further customize the script or form through the PolyForm Control Panel. The following section shows you how to use the PolyForm Control Panel to create a script.

Using the PolyForm Control Panel to Create a Script

This example uses the PolyForm Control Panel to create a simple HTML comment form and its script. The end result will be very close to what you created in the previous example using the Script Wizard.

The main steps in this process are:

1. Create a new script.
2. Create the form HTML file.
3. Select the Response to the browser.
4. Enter an email address.
5. Save the script.
6. Test the script.

Step 1: Create a New Script

When you start the PolyForm Control Panel, it is ready for you to enter a new script. But if you have been working with other scripts you will need to do the following:

1. On the toolbar, choose the New Script icon.

If changes to the current script haven't been saved, PolyForm displays the Save Changes? dialog. Choose Yes to save the previous script.

If the current script has never been saved, and therefore has no script name, PolyForm Control Panel displays the Save As dialog. Enter a script name and choose OK to save the script.

You will now have a new script to work with in the PolyForm Control Panel. (See Figure 3-13.)

Figure 3-13 Control Panel with new script

Step 2: Create the Form HTML File

Typically, creating the HTML form is the first thing to do when building a script. The following example shows you one way to create a form through the PolyForm Control Panel.

1. Choose the Browse button (the button with three periods next to the Form Filename field on the Form tab of the PolyForm Control Panel). The Select or Create Form dialog appears. (See Figure 3-13.)
2. In the File Name field type a filename, for example Comment_Form.html. Choose OK. A confirmation dialog appears.
3. Choose Yes to create the file.
4. PolyForm launches an editor with the outline of an HTML form document already in place. (See Figure 3-14.)
5. Depending on which will be easier, you may insert your text and HTML tags into this initial HTML document, or delete the initial document and enter a complete document from scratch.
6. Using your editor, create the following document by inserting information into the outline shown in Figure 3-14. You may refer to Chapter 6, Form HTML Basics, for an overview of HTML for forms, as well as for detailed reference information.

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN" "html.dtd">
<HTML>
<HEAD>
<TITLE>Comment Form</TITLE>
</HEAD>
<BODY>
<H1>We'd like to hear from you!</H1>
<HR>
<FORM METHOD="POST" action="/cgi-win/polyform.exe/Comment_Form">
<p>Name: <input type="text" name="name"><br>
Email: <input type="text" name="email">
<p>Comment:<br>
<textarea name="comment" cols="40" rows="5">
</textarea>
<p>To submit the form, press this button: <INPUT TYPE="submit" 
VALUE="Submit Comments"> <P>
To clear the form, press this button: <INPUT TYPE="reset" 
VALUE="Clear Form">
</FORM>
<p>Thanks!
<HR>
</BODY>
</HTML>

Note that the action attribute of the form tag tells your server to name the script and to run PolyForm.

<FORM METHOD="POST" action="/cgi-win/polyform.exe/Comment_Form">

In this case the script name is Comment_Form. Script names must be 32 characters long or fewer; you may use letters, numbers, and the underscore, but you may not use spaces or other symbols. When you save the script, you must type the script name exactly as you entered it in the action attribute of the form.

We suggest that you use names that make it obvious what the form is about. We also suggest that you consider using consistent standards for script names. For example, always capitalize words in script names, and type an underscore between words. Comment_Form fits this standard.

7. Save the HTML file and exit from your editor.
8. Choose the Save to File tab and select Don't Save. This tab gives you several other options discussed in the "Using the Save to File Tab Tools" section of Chapter 4, PolyForm Tools.

Figure 3-14 Outline of HTML document in editor

Step 3: Select the Response to Browser

The Send to Browser tab gives you several options for what PolyForm should send to the browser when the form is submitted. You select one of the following: the URL of a document that you create and save on the server, a template file that creates an HTML document on the fly, or a simple confirmation of the data received from the form.

You may also enter a Window Target to send the results to a named frame or browser window for browsers that support frames. See Chapter 4 for more information about this feature.

In this example you will send a confirmation of data received.

1. Choose the Send to Browser tab. (See Figure 3-15.)
2. Select Send a Simple Confirmation of Data Received.

Figure 3-15 Send to Browser tab

Step 4: Enter an Email Address

Use the Email Options tab to send email both to an address you enter, and to an address submitted by the form. In this example, just send email to yourself.

If you don't have an SMTP mail server, PolyForm won't be able to send email. (See Chapter 2, Installing PolyForm, for details.)

1. Choose the Email Options tab. (See Figure 3-16.)
2. Select the "Copy Form Contents To:" checkbox.
3. In the corresponding textbox, enter your email address.

Figure 3-16 Email Options tab

Step 5: Save the Script

You have now created each element of a PolyForm script. You are ready to save the new script.

1. On the toolbar, choose the Save Script icon. The Save As dialog appears.
2. Enter the script name exactly as you typed it in the action attribute of the form, in this case Comment_Form, and choose OK.

Step 6: Test the Script

In the Script Wizard example, you tested the script by using PolyForm's Run command. This time, you'll test the script by giving the URL of the script directly to your browser.

1. In your Web browser's Location field, enter the URL of PolyForm, followed by a slash, followed by the script name (e.g., http://www.myserver.com/cgi-win/polyform.exe/Comment_Form). Substitute your Web server's Fully Qualified Domain Name for www.myserver.com in the example. If you installed PolyForm in a directory other than cgi-win, substitute your directory for cgi-win in the example. Make sure you include the full path (including server name) in the URL. Press Enter. The form you created should appear. (See Figure 3-17.)


Figure 3-17 Comment_Form form document

2. Enter some information and choose Submit Comments. Your browser displays the response to browser that you selected in the script. (See Figure 3-18.)


Figure 3-18 Comment_Form response to the browser

You have now created, saved, and run a PolyForm script through the PolyForm Control Panel. As you've seen, there are more options than the Script Wizard. You may find it desirable to create a script with the wizard initially and then modify it with the PolyForm Control Panel.

Just to add one more step to this process, try the following procedure that introduces you to the report you can generate on your scripts.

Generating the PolyForm Script Report

The Script Report answers questions you may have about your script. The report contains all the information you supplied while creating your script, through the Script Wizard or the PolyForm Control Panel, the path and filename of the form file, and the contents of the form file.

To view the script report for the open script, choose Report on the PolyForm Control Panel Options menu. PolyForm displays a report in your text editor. A complete report listing is shown in Example 3-1. You can save the report to another filename or print the report. We recommend that you keep copies of script reports for reference.

Example 3-1 Report Listing of Comment_Form Script

Report of Comment_Form script. 

3/11/96 9:58:01 PM 

-----Form Attributes-----

              Form Title: Comments
              Form file name: F:\win32app\internet\WEBSITE\CGI-WIN\PFTOOLS\FORMS\Comment_Form.html
              Form Tag Syntax: <FORM METHOD="POST" ACTION="http://localhost/cgi-win/polyform.exe/Comment_Form">
              URL of this Form: http://localhost/cgi-win/polyform.exe/Comment_Form
              Form:
              <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN" "html.dtd">
              <HTML>
              <HEAD>
              <TITLE>Comments</TITLE>
              </HEAD>
              <BODY>
              <H1>We'd like to hear from you!</H1>
              <HR>
              <FORM METHOD="POST" action="/cgi-win/polyform.exe/Comment_Form">
              <p>Name: <input type="text" name="name"><br>
              Email: <input type="text" name="email">
              <p>Comment:<br>
              <textarea name="comment" cols="40" rows="5">
              </textarea>
              <P>
              To submit the form, press this button: <INPUT TYPE="submit" VALUE="Submit Comments"> <P>
              To clear the form, press this button: <INPUT TYPE="reset" VALUE="Clear Form">
              </FORM>
              <p>Thanks!
              <HR>
              </BODY>
              </HTML>

-----Saved to File Attributes-----

              No information is saved by this script

-----Send to Browser attributes-----

              The browser will be sent an acknowledgement of the submission
              containing the submitted data and based on a default template.

-----Email Options-----

              Email containing the submitted contents of the form and transaction
              specific information will be sent to: 
              jrb@myserver.com
              (If a filename, file contains multiple email addresses)
              Subject of Email: 
              Email sent from: 

-----End of report-----

Changing the PolyForm Control Panel Settings

There may be a situation at some point that requires you to modify the information (mailserver, CGI URL, etc.) you provided to the Install Wizard when installing PolyForm. Before moving on to Chapter 4, PolyForm Tools, and each specific PolyForm tool, let's explore the Settings option on the Options menu.

To update the installation information, on the PolyForm Control Panel Options menu, choose Settings. (See Figure 3-19.)

Figure 3-19 Settings window displaying the Server Properties tab

The Server Properties tab allows you to modify the following:

HTTP Server Domain Name

In the HTTP Server Domain Name field enter a Fully Qualified Domain Name (FQDN), i.e., the Internet address of your server. You will recognize it from such examples as: website.ora.com and www.whitehouse.gov. Either your Internet service provider or network administrator can provide you with the new FQDN for your server, should it change.

Mail Server Address or Name

The mail server is the SMTP Internet mail server address. Get the new address from your Internet service provider or network administrator, should it change.

Windows CGI URL

This URL is typically specified by the server software. It must be the full URL, including the Fully Qualified Domain Name of the server (e.g., http://your.host.com/ cgi-win/). Contact your Web server administrator if you need help with this.

E-Mail Return Address

PolyForm administrator's email address. This is the default return email address for email sent through PolyForm.

After installing PolyForm, you may use the Applications tab of the Settings form to choose editors for HTML and text files. PolyForm uses the Windows Notepad unless you change this setting. (See Figure 3-20.) You may also enter the path and filename of your Web browser. Once you specify your browser here, PolyForm will load the active script's form into the browser whenever you choose Run on the Options menu in the PolyForm Control Panel.

Figure 3-20 Settings window displaying the Applications Properties tab

Contents