htmlForm

htmlForm
CGI Form class

Description

htmlForm encapsulates the <FORM></FORM> tags. It is used to create data input forms, comprised of various data entry controls (such as text input boxes, drop down lists, checkboxes, etc.) and action buttons.

Each form is associated with an action URL that will receive and process data from the form. Such action URL's can be any CGI script or html++ application, and are typically of the form "http://www.domain.com/cgi-bin/appname".

A document can have multiple forms, but the HTML specification does not permit nested forms. In other words, you cannot have a form within a form. Each form on a page must be completely contained within it's own <FORM></FORM> block using separate htmlForm objects.

Browsers encode form data before passing it to the server. It is up to the server to either decode the information (the field names and values) or pass it, still encoded, directly to the application. The standard encoding format for form data is "application/x-www-form-urlencoded". This standard converts spaces to "+" symbols, non-printable characters into "%xx" hex codes, and separates values with "&" characters. This type of encoding is the reason URL's sometimes seem rather lengthy or otherwise unusual.

Another type of encoding exists, called "multipart/form-data", and is required when using file upload elements (see htmlInputFile). Netscape supports this encoding type, as does Microsoft Internet Explorer version 4 (version 3 can support it as well but requires a patch).

multipart/form-data encoding is not automatically decoded by most web servers, so any data transmitted from a browser to the server using this encoding method is passed directly to the application. Processing "multipart/form-data" encoded data is complex, and is one of the reasons file upload elements are not widely used on web pages. However, html++'s htmlCgi class automatically recognizes and properly decodes such data, relieving you of all the gory details.

Typically, the default encoding type will be all that is required for most forms. However, as mentioned above, the "multipart/form-data" encoding type is required when using the htmlInputFile file upload element.

For convenience, htmlForm automatically sets the proper encoding type whenever an htmlInputFile object is added directly to an htmlForm object. If however, your application adds htmlInputFile objects to an intermediate object (such as htmlContainer or htmlFont), you must manually specify "multipart/form-data" encoding using the Encode() method.

Declaration

#include <dcmicro/htmlpp/form.h>

Hierarchy

See Also

htmlCgi, htmlInputCheckBox, htmlInputHidden, htmlInputImage, htmlInputPassword, htmlInputRadio, htmlInputReset, htmlInputSelect, htmlInputSubmit, htmlInputText, htmlInputTextArea, htmlInputFile

Related Constants/Definitions

typedef enum {

submit_unknown = -1,

submit_post,

submit_get

} SubmitMethod ;

Constructors

htmlForm()

Constructs an empty form object.

htmlForm( const String& action, SubmitMethod method = submit_post )

Constructs an empty form object, setting the action URL to action using the specified submission method.

htmlForm( const htmlForm& rhs )

Copy constructor.

Destructor

virtual ~htmlForm()

Destroys the object.

Member Methods

Add    virtual htmlObject FAR * Add( const htmlObject& element )

Adds element to the form, and returns a pointer to the new object. If element is a htmlInputFile object, the form encoding method will be automatically set to "multipart/form-data", unless it has already been set using the Encode() method.

Add    virtual htmlObject FAR * Add( const String& text )

Adds text to the form, and returns a pointer to the new object.

Action htmlForm& Action( const String& action )

Sets the action URL for the form to action (e.g., "/cgi-bin/script"), then returns a reference to the object.

Action String Action() const

Returns the action setting for the form as a string.

Encode htmlForm& Encode( const String& encode_type )

Sets encoding type for the form to encode_type, then returns a reference to the object.

"application/x-www-form-urlencoded" (the default), is usually used if the METHOD attribute has the value POST.
"multipart/form-data" is used when the form contains a file upload element (htmlInputFile). Note that the htmlForm class will automatically enable this encoding method whenever htmlInputFile objects are added, unless the Encode() method has already been called.

Encode String Encode() const

Returns the encoding type for the form as a string.

Method htmlForm& Method( SubmitMethod method )

Sets the submit method for the form to method (submit_post or submit_get), then returns a reference to the object.

submit_get (the default) appends the input information to the URL which, on most receiving systems, becomes the value of the environment variable QUERY_STRING.
submit_post sends the input information in a data body that is available on stdin, with the data length set in the environment variable CONTENT_LENGTH.

The htmlCgi class automates retrieval of form data from web browsers using either submit method. From this perspective, the issue of whether to use one submit method over another is essentially cosmetic with regards to the browser.

Method SubmitMethod Method() const

Returns the submit method setting for the form as an integer (submit_post or submit_get).

Name htmlForm& Name( const String& name )

Sets the JavaScript-accessible form name to name, and returns a reference to the object. JavaScript can use name, to distinguish between multiple forms on a single document.

Name String Name() const

Returns the form name as a string, or an empty string if not set.

Target htmlForm& Target( const String& target_window )

Sets the target window that displays the data returned by the invoked program (the action of the form) to target_window, then returns a reference to the object. See Target Windows for additional details.

Target String Target() const

Returns the target window for the form, or an empty string if not set.

Print    void Print( ostream& os ) const

Outputs the object to os.

Clone htmlObject FAR * Clone() const

Returns a base-class pointer to a deep copy of the object.

Example Use

See Also: Tutorial : Forms : Aligning With Tables in the User Guide

The following two programs illustrate use of the htmlForm and htmlCgi classes to pass data from a form (generated using html++, though it could be any HTML form document) to a server-side html++ application. The application then processes the data and outputs a dynamically-generated page.

// program 1: Create the data input form

#include <stdio.h>

#include <stdlib.h>

#include <dcmicro/htmlpp/htmlpp.h>

int main( void )

{

   htmlCgi   server ;

   htmlPage  page( "html++ form input example" ) ;

   //  Create a form, setting the action

   //  statement to "/cgi-bin/formdemo"

   htmlForm   form( "/cgi-bin/formdemo" );

   //  Set up input areas for last name,

   //  first name, and email address. Allow

   //  up to 20 characters for the names,

   //  and 30 characters for the email.

   form << "Last Name: "

        << htmlInputText( "lname", 20 )

        << htmlBreak() ;

   form << "First Name: "

        << htmlInputText( "fname", 20 )

        << htmlBreak() ;

   form << "Email address: "

        << htmlInputText( "email", 30 )

        << htmlBreak() ;

   //  Add a submit button with a custom label

   form << htmlCenter( htmlInputSubmit("Press to continue") );

   page << form ;

   server << page ;

   return 0 ;

}

// program 2: Process the form data

#include <stdio.h>

#include <stdlib.h>

#include <dcmicro/htmlpp/htmlpp.h>

int main( void )

{

   htmlPage   page( "html++ formdemo.cpp application" ) ;

   //  Construct an htmlCgi object to receive

   //  the CGI form data.

   htmlCgi  server( cin ) ;

   //  Output a few data items from the

   //  server environment.

   page << "Server_Software: " << server.Server_Software

        << htmlBreak()

        << "Server_Name: " << server.Server_Name

        << htmlBreak()

        << "Gateway_Interface: " << server.Gateway_Interface

        << htmlBreak()

        << "Request_Method: " << server.Request_Method

        << htmlBreak()

        << "Remote_Host: " << server.Remote_Host

        << htmlParagraph() ;

   //  Output all CGI data from the form

   String  name ;

   String  value ;

   Boolean good_data = server.Enumerate( name, value, TRUE ) ;

   while ( good_data )

   {

      page << htmlBold( name )

           << " : "

           << value

           << htmlBreak() ;

      //  loop for next form field

      good_data = server.Enumerate( name, value ) ;

   }

   server << page ;

   return 0 ;

}

Program One Output

Content-Type: text/html

<HTML>

<HEAD>

<TITLE>html++ form input example</TITLE>

</HEAD>

<BODY>

<FORM ACTION="/cgi-bin/formdemo" METHOD="POST">

Last Name: <INPUT TYPE="TEXT" NAME="lname" SIZE="20"><BR>

First Name: <INPUT TYPE="TEXT" NAME="fname" SIZE="20"><BR>

Email address: <INPUT TYPE="TEXT" NAME="email" SIZE="30"><BR>

<CENTER><INPUT TYPE="SUBMIT" VALUE="Press to continue"></CENTER>

</FORM>

</BODY>

</HTML>

Program Two Output

Content-Type: text/html

<HTML>

<HEAD>

<TITLE>html++ formdemo.cpp application</TITLE>

</HEAD>

<BODY>

Server_Software: Stronghold/2.0.1 Apache/1.2b11<BR>

Server_Name: www.dcmicro.com<BR>

Gateway_Interface: CGI/1.1<BR>

Request_Method: POST<BR>

Remote_Host: rangelan.connectup.com<P></P>

<B>lname</B> : Smith<BR>

<B>fname</B> : John<BR>

<B>email</B> : jsmith@anywhere.com<BR>

</BODY>

</HTML>

©1998 DC Micro Development. All rights reserved.
No portion of this document may be c opied or reproduced without expressed written consent.
html++ is a trademark of DC Micro Development.

	htmlForm encapsulates the <FORM></FORM> tags. It is used to create data input forms, comprised of various data entry controls (such as text input boxes, drop down lists, checkboxes, etc.) and action buttons.

	Each form is associated with an action URL that will receive and process data from the form. Such action URL's can be any CGI script or html++ application, and are typically of the form "http://www.domain.com/cgi-bin/appname".

	A document can have multiple forms, but the HTML specification does not permit nested forms. In other words, you cannot have a form within a form. Each form on a page must be completely contained within it's own <FORM></FORM> block using separate htmlForm objects.

	Browsers encode form data before passing it to the server. It is up to the server to either decode the information (the field names and values) or pass it, still encoded, directly to the application. The standard encoding format for form data is "application/x-www-form-urlencoded". This standard converts spaces to "+" symbols, non-printable characters into "%xx" hex codes, and separates values with "&" characters. This type of encoding is the reason URL's sometimes seem rather lengthy or otherwise unusual.

	Another type of encoding exists, called "multipart/form-data", and is required when using file upload elements (see htmlInputFile). Netscape supports this encoding type, as does Microsoft Internet Explorer version 4 (version 3 can support it as well but requires a patch).

	multipart/form-data encoding is not automatically decoded by most web servers, so any data transmitted from a browser to the server using this encoding method is passed directly to the application. Processing "multipart/form-data" encoded data is complex, and is one of the reasons file upload elements are not widely used on web pages. However, html++'s htmlCgi class automatically recognizes and properly decodes such data, relieving you of all the gory details.

	Typically, the default encoding type will be all that is required for most forms. However, as mentioned above, the "multipart/form-data" encoding type is required when using the htmlInputFile file upload element.

	For convenience, htmlForm automatically sets the proper encoding type whenever an htmlInputFile object is added directly to an htmlForm object. If however, your application adds htmlInputFile objects to an intermediate object (such as htmlContainer or htmlFont), you must manually specify "multipart/form-data" encoding using the Encode() method.

	htmlCgi, htmlInputCheckBox, htmlInputHidden, htmlInputImage, htmlInputPassword, htmlInputRadio, htmlInputReset, htmlInputSelect, htmlInputSubmit, htmlInputText, htmlInputTextArea, htmlInputFile

	typedef enum {
	submit_unknown = -1,
	submit_post,
	submit_get
	} SubmitMethod ;

	htmlForm( const String& *action, SubmitMethod method* = submit_post )

	Constructs an empty form object, setting the action URL to action using the specified submission method.

	Add	virtual htmlObject FAR * Add( const htmlObject& *element* )

	Adds element to the form, and returns a pointer to the new object. If element is a htmlInputFile object, the form encoding method will be automatically set to "multipart/form-data", unless it has already been set using the Encode() method.

	Add	virtual htmlObject FAR * Add( const String& *text* )

	Adds text to the form, and returns a pointer to the new object.

	Sets the action URL for the form to action (e.g., "/cgi-bin/script"), then returns a reference to the object.

	Encode	htmlForm& Encode( const String& *encode_type* )

	Sets encoding type for the form to encode_type, then returns a reference to the object.

	Sets the submit method for the form to method (submit_post or submit_get), then returns a reference to the object.


	The htmlCgi class automates retrieval of form data from web browsers using either submit method. From this perspective, the issue of whether to use one submit method over another is essentially cosmetic with regards to the browser.

	Returns the submit method setting for the form as an integer (submit_post or submit_get).

	Sets the JavaScript-accessible form name to name, and returns a reference to the object. JavaScript can use name, to distinguish between multiple forms on a single document.

	Returns the form name as a string, or an empty string if not set.

	Target	htmlForm& Target( const String& *target_window* )

	Sets the target window that displays the data returned by the invoked program (the action of the form) to target_window, then returns a reference to the object. See Target Windows for additional details.

	Returns the target window for the form, or an empty string if not set.


	See Also: Tutorial : Forms : Aligning With Tables in the *User Guide*

	The following two programs illustrate use of the htmlForm and htmlCgi classes to pass data from a form (generated using html++, though it could be any HTML form document) to a server-side html++ application. The application then processes the data and outputs a dynamically-generated page.

	// program 1: Create the data input form
	#include <stdio.h>
	#include <stdlib.h>
	#include <dcmicro/htmlpp/htmlpp.h>

	int main( void )
	{
	htmlCgi server ;
	htmlPage page( "html++ form input example" ) ;

	// Create a form, setting the action
	// statement to "/cgi-bin/formdemo"
	htmlForm form( "/cgi-bin/formdemo" );

	// Set up input areas for last name,
	// first name, and email address. Allow
	// up to 20 characters for the names,
	// and 30 characters for the email.
	form << "Last Name: "
	<< htmlInputText( "lname", 20 )
	<< htmlBreak() ;

	form << "First Name: "
	<< htmlInputText( "fname", 20 )
	<< htmlBreak() ;

	form << "Email address: "
	<< htmlInputText( "email", 30 )
	<< htmlBreak() ;

	// Add a submit button with a custom label
	form << htmlCenter( htmlInputSubmit("Press to continue") );

	page << form ;

	server << page ;
	return 0 ;
	}


	// program 2: Process the form data
	#include <stdio.h>
	#include <stdlib.h>
	#include <dcmicro/htmlpp/htmlpp.h>

	int main( void )
	{
	htmlPage page( "html++ formdemo.cpp application" ) ;

	// Construct an htmlCgi object to receive
	// the CGI form data.
	htmlCgi server( cin ) ;

	// Output a few data items from the
	// server environment.
	page << "Server_Software: " << server.Server_Software
	<< htmlBreak()
	<< "Server_Name: " << server.Server_Name
	<< htmlBreak()
	<< "Gateway_Interface: " << server.Gateway_Interface
	<< htmlBreak()
	<< "Request_Method: " << server.Request_Method
	<< htmlBreak()
	<< "Remote_Host: " << server.Remote_Host
	<< htmlParagraph() ;

	// Output all CGI data from the form
	String name ;
	String value ;
	Boolean good_data = server.Enumerate( name, value, TRUE ) ;
	while ( good_data )
	{
	page << htmlBold( name )
	<< " : "
	<< value
	<< htmlBreak() ;

	// loop for next form field
	good_data = server.Enumerate( name, value ) ;
	}

	server << page ;
	return 0 ;
	}


	Content-Type: text/html
	<HTML>
	<HEAD>
	<TITLE>html++ form input example</TITLE>
	</HEAD>
	<BODY>
	<FORM ACTION="/cgi-bin/formdemo" METHOD="POST">
	Last Name: <INPUT TYPE="TEXT" NAME="lname" SIZE="20"><BR>
	First Name: <INPUT TYPE="TEXT" NAME="fname" SIZE="20"><BR>
	Email address: <INPUT TYPE="TEXT" NAME="email" SIZE="30"><BR>
	<CENTER><INPUT TYPE="SUBMIT" VALUE="Press to continue"></CENTER>
	</FORM>
	</BODY>
	</HTML>