17.3 How do I…Create an HTML form?
Problem
In order to create sophisticated web applications, I need to include forms in my documents. I want to use the forms to insert new data into the database and pass information to the database to perform queries. How do I create an HTML form?
Technique
A complete set of procedures for creating HTML forms is provided by the PL/SQL Web Toolkit. When an HTML form is submitted to the Web Agent, a second stored procedure is called to process it. Each field in the form is passed to the second procedure as a parameter. Table 17.5 shows the form procedures within the HTP package.
Table 17.5 Form-related procedures
Procedure Description htp.formOpen Prints the tag that starts the form. htp.formClose Prints the tag that ends the form. htp.formCheckbox Inserts a checkbox into the form. htp.formHidden Sends the content of the field to the browser, although it is not visible to the user. htp.formImage Creates an image field that submits the form and returns the x and y coordinate of where the user clicked the image. htp.formPassword Creates a field where user’s input is not readable as it is typed. htp.formRadio Creates a radio button in the form. htp.formReset Creates a reset button that clears all the fields of the form when clicked. htp.formSubmit Creates a submit button that submits the form when clicked. Procedure Description htp.formText Creates a field for a single line of text. htp.formSelectOpen Begins a select list that enables the user to select alternatives. htp.formSelectOption Represents one choice in a select list. htp.formSelectClose Ends a select list. htp.formTextarea Creates a text area that enables the user to create multiple lines of text. htp.formTextareaOpen Creates a text area that enables you to specify default values. htp.formTextareaClose Ends a text area field. The HTP.FORMOPEN procedure is used to begin a new form. The name of the processing procedure must be passed to the procedure as a parameter. The HTP.FORMCLOSE procedure ends the definition of the form. Within the form definition, a variety of HTP procedures can be used to create text items, check boxes, radio buttons, text areas, and selection lists.
Steps
1. Run SQL*Plus and connect using the WAITE account. CHP17_3.SQL, shown in Figure 17.10, creates a sample table that receives the data entered into the form this How-To creates.
The EMP17 table created in the script will receive data entered into an HTML form. Run the script to create the sample file.
SQL> START CHP17_3
Table created.
2. Run the CHP17_4.SQL file in SQL*Plus, as shown in Figure 17.11. The stored procedure contained in the file creates a form allowing data entry.
Line 1 specifies the keywords required to create a new procedure named FORM17. Lines 2 through 13 contain the procedure body. The HTP.HTITLE procedure in line 4 gives the HTML document a name by generating the <TITLE> and </TITLE> tags. The HTP.FORMOPEN procedure in line 5 begins the area of the HTML document containing the form and supplying the name of the processing procedure after the form has been submitted. Line 6 uses the HTP.PREOPEN procedure and gen-erates the <PRE> tag to begin a pre-formatted text area. Lines 7 and 8 use the HTP.P procedure to print to the document and the HTF.FORMTEXT function to create text fields, respectively. The names of the fields specified in the procedures are the parameters passed to the processing procedure. The HTP.PRECLOSE procedure in line 9 creates the </PRE> tag that ends the formatted text beginning on line 6. The HTP.PARAGRAPH procedure in line 10 begins a new paragraph in the document by generating the <P> tag. The HTP.FORMSUBMIT procedure in line 11 creates a Submit button that submits the form when clicked. The HTP.FORMCLOSE procedure in line 12 ends the declaration of the form.
The form can be displayed by opening the URL http://localhost/owa_waite/plsql/form17. Although the form can be displayed at this point, it cannot be submitted until the processing procedure is created, as shown in the following steps.<p> 3. Run the CHP17_5.SQL file in SQL*Plus, as shown in Figure 17.12. The stored procedure contained in the file processes the form created in the previous steps.
Line 1 specifies the keywords for creating a stored procedure and gives it the name declared in the HTP.FORMOPEN procedure in the calling document. This ACTION17 procedure is executed when the Submit button is clicked. The two text fields from the calling document are specified as the procedure parameters. Lines 1 through 3 contain the procedure specification. All form fields must be provided as parameters to the processing procedure and must default to NULL. Lines 4 through 10 contain the procedure body. The INSERT statement on lines 5 and 6 creates a new record in the table using values in the form fields. Lines 8 and 9 use the HTP.P procedure to display a submission message to the user when the record is created. Note the use of HTF.BOLD function to insert <B> and </B> tags for bold typeface. You can use the HTF package whenever you need a function equivalent of a procedure in the HTP package.
Although the procedure can be called directly as a URL, it will not perform any useful function unless called from the form created in Step 2. The next step demonstrates the form posting.
4. Start your browser and open the URL http://localhost/owa_waite/plsql/form17. Figure 17.13 shows the form within the Netscape Navigator browser.
Enter values into the two fields on the form and select the Submit button to process it. Figure 17.14 shows the results displayed after the fields are entered and the form submitted.
In addition to displaying the information entered into the form, the values are inserted into the EMP17 table created in Step 1. The simple form created in the earlier steps does not display the numerous controls an HTML form can contain. The following steps create a more complex form using many of the available controls.
5. Run the CHP17_6.SQL file in SQL*Plus, as shown in Figure 17.15. The stored procedure contained in the file creates a complex form that includes text fields, radio buttons, a checkbox, and a select list.
Line 1 specifies the keywords required to create the stored procedure and names it. Lines 2 through 27 contain the body of the stored procedure. Lines 3 and 26 begin and end the HTML document with the HTP, HTMLOPEN, and HTP.HTMLCLOSE procedures, respectively. Line 5 uses the HTP.LINE procedure to generate an <HR> tag for displaying a line. Line 6 begins a form with the HTP.FORMOPEN procedure. The parameter passed to the HTP.FORMOPEN procedure specifies the name of the procedure receiving the input form data when the form is submitted.<p> Line 7 uses the HTP.PREOPEN procedure to begin a section of pre-formatted text within the document. Lines 8 and 9 use the HTP.PRINT procedure containing the HTF.FORMTEXT function to create two text fields. Lines 11 and 12 create two radio buttons using the HTP.FORMRADIO procedure. By specifying the same name for the two radio buttons, the browser knows the buttons occupy the same radio group.
Lines 13 through 18 create a drop-down listbox containing the elements created by the HTP.FORMSELECTOPTION procedure. The selection list is created with the HTP.FORMSELECTOPEN procedure and ended with the HTP.FORMSELECTCLOSE procedure. The HTF.FORMCHECKBOX function contained in the HTP.PRINT procedure in line 19 creates a checkbox. The values generated by a checkbox are ON or OFF. The HTP.SUBMIT procedure in line 22 creates a Submit button that processes the form when selected. Line 23 uses the HTP.RESET procedure to create a reset button that clears the form when selected. The HTP.FORMCLOSE procedure in line 24 ends the form area.
Creating the procedure lets you call the /ows_waite/plsql/emp_frm17 page from any browser. The CHP17_6 procedure referenced by HTP.FORMOPEN must be created in order to process the form. The next step creates the stored procedure to process the form.
6. Run the CHP17_7.SQL file in SQL*Plus, as shown in Figure 17.16. The procedure within the file processes the form created in the previous step and displays the values entered into the items.
Lines 1 through 6 contain the specification for the stored procedure. The parameters to the stored procedure represent the form variables. As there is no guarantee that a value will be passed when the form is posted, a default value is included for each parameter. The order of the parameters is unimportant because the Web Agent reorders them at runtime.
Lines 7 through 16 contain the procedure body. Lines 8 and 19 begin and end the document by specifying the HTP.HTMLOPEN and HTP.HTMLCLOSE procedures, respectively. Line 9 uses the HTP.HTITLE procedure to generate the tags for the document’s title and heading. Lines 10 through 13 use the HTP.P procedure to print the parameters passed from the calling document. The <B> tag is included in the parameter to print the values in boldfaced text. The <BR> tag is included to generate a linefeed. Notice that the value of the EXEMPT checkbox is either On or Off, and not TRUE or FALSE. The value for the EXEMPT checkbox is tested by the IF statement in line 14.
7. Run a browser and open the URL http://localhost/owa_waite/plsql/emp_frm17. Figure 17.17 shows the form displayed by the Netscape browser.
Enter a first and last name into the text fields, select a value from the radio buttons and listbox, and check the checkbox. If you want to clear information entered, you can select the Reset button. Submit the form by selecting the Submit button. Each of the values from the calling form are displayed by the processing form. Figure 17.18 shows the output in the Netscape Navigator window after the form is posted.
How It Works
In order to create a form, two stored procedures are required. The first procedure lets the user enter values into the form, and the second procedure receives these values as parameters and processes the form. A form begins with the <FORM METHOD="POST" ACTION="processing procedure"> tag and ends with the </FORM> tag. To use the GET method to post the form, use METHOD="GET" in the FORM tag. Between the tags, form elements and other HTML tags are defined. Text fields, selection lists, radio buttons, checkboxes, and text areas can all be defined within a form.<P> Step 1 creates a table that receives the data entered into a form. Step 2 creates a stored procedure that generates a simple form to enter a name. When the form is submitted, the procedure created in Step 3 inserts the data into the sample table and displays the values of the field in a document. Step 4 shows the operation of the simple form within a browser. Step 5 creates a stored procedure generating a form with many of the objects an HTML form uses. The form contains text boxes, radio buttons, a checkbox, and a selection list. The stored procedure created in Step 6 processes the data from the calling form by displaying the values within a document. Step 7 shows the posting of the complex form in a browser.
Comments
The PL/SQL Agent can receive parameters through a URL or from an HTML form when it is submitted. Forms enable you to generate sophisticated web applications, and you can choose between the GET and POST methods for posting a form. It is recommended that you use the POST method instead of the GET method whenever possible.
The GET method is used for links and non-form URLs, and is restricted by the operating system limit on the length of the QUERY_STRING CGI environment variable, which it uses while posting a form. On the other hand, CGI uses the standard input to read data sent by the POST method, and thus an unlimited number of parameters can be posted without worrying about the client or server truncating data.
The REQUEST_METHOD CGI environment variable is set to GET or POST depending on the method used to post the form. The order of parameters is unimportant, but providing a default value for parameters is a recommended practice if you cannot guarantee that a value will be passed from the browser for a particular parameter.