<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html lang="en" dir="LTR">
<head>
<!-- $Id: header.html,v 1.3 2002/03/09 18:30:37 sbooth Exp $ -->
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>A Tutorial Example</title>
<link rev="made" href="mailto:bug-cgicc@gnu.org" />
<link href="cgicc-doc.css" rel="stylesheet" type="text/css" />
</head>
<body>
<!-- Generated by Doxygen 1.2.13.1 -->
<center>
<a class="qindex" href="index.html">Main Page</a> <a class="qindex" href="namespaces.html">Namespace List</a> <a class="qindex" href="hierarchy.html">Class Hierarchy</a> <a class="qindex" href="annotated.html">Compound List</a> <a class="qindex" href="files.html">File List</a> <a class="qindex" href="namespacemembers.html">Namespace Members</a> <a class="qindex" href="functions.html">Compound Members</a> <a class="qindex" href="globals.html">File Members</a> <a class="qindex" href="pages.html">Related Pages</a> </center>
<hr><a name="cgicc_tutorial"><h2>A Tutorial Example</h2></a>
<div class="header">Introduction</div>
<div class="subsection">
<p>
It is easiest to understand how the GNU cgicc library might be used by first looking at an example. Suppose you want an HTML form on your web site asking a user to enter their name, age, and sex, perhaps as part of a user-registration procedure, and you wish to write a CGI script using cgicc to process the form in some meaningful way.
<p>
You would begin by creating an HTML form containing the HTML fragment
<p>
<div class="fragment"><pre>
<form method="post" action="http://change_this_path/cgi-bin/foo.cgi">
Your name : <input type="text" name="name" /><br />
Your age : <input type="text" name="age" /><br />
Your sex : <input type="radio" name="sex" value="male"checked="checked" />Male
<input type="radio" name="sex" value="female" />Female <br />
</form>
</pre></div>
<p>
Then, on to the CGI application. Applications written using cgicc, like all other applications, begin with a <code>main</code> function:
<p>
<div class="fragment"><pre><font class="keywordtype">int</font> main(<font class="keywordtype">int</font> argc, <font class="keywordtype">char</font> **argv)
{
<font class="comment">// CGI processing goes here</font>
}
</pre></div>
<p>
</div>
<p>
<div class="header">Initialization</div>
<div class="subsection">
<p>
The three main classes of cgicc you will use to process the submitted data are <code><a class="el" href="classcgicc_1_1Cgicc.html">cgicc::Cgicc</a></code>, <code><a class="el" href="classcgicc_1_1CgiEnvironment.html">cgicc::CgiEnvironment</a></code>, and <code><a class="el" href="classcgicc_1_1FormEntry.html">cgicc::FormEntry</a></code>. These classes will be explained in detail later; for now, it is sufficient to know that:
<p>
<ul>
<li>The class <code><a class="el" href="classcgicc_1_1Cgicc.html">cgicc::Cgicc</a></code> is used for retrieving information on the submitted form elements.
<p>
<li>The class <code><a class="el" href="classcgicc_1_1CgiEnvironment.html">cgicc::CgiEnvironment</a></code> is used to retrieve information on environment variables passed from the HTTP server.
<p>
<li>The class <code><a class="el" href="classcgicc_1_1FormEntry.html">cgicc::FormEntry</a></code> is used to extract various types of data from the submitted form elements. </ul>
All of cgicc's functionality is accessed through class <code><a class="el" href="classcgicc_1_1Cgicc.html">cgicc::Cgicc</a></code>. Thus, the first step in CGI processing is to instantiate an object of type <code><a class="el" href="classcgicc_1_1Cgicc.html">cgicc::Cgicc</a></code>:
<p>
<div class="fragment"><pre><a class="code" href="classcgicc_1_1Cgicc.html">cgicc::Cgicc</a> cgi;
</pre></div>
<p>
or
<p>
<div class="fragment"><pre><font class="keyword">using</font> <font class="keyword">namespace </font>cgicc;
Cgicc cgi;
</pre></div>
<p>
Upon instantiation, the class <code><a class="el" href="classcgicc_1_1Cgicc.html">cgicc::Cgicc</a></code> parses all data passed to the CGI script by the HTTP server.
<p>
Since errors are handled using exceptions, you may wish to wrap your CGI code in a <code>try</code> block to better handle unexpected conditions:
<p>
<div class="fragment"><pre><font class="keywordflow">try</font> {
<a class="code" href="classcgicc_1_1Cgicc.html">cgicc::Cgicc</a> cgi;
}
<font class="keywordflow">catch</font>(exception& e) {
<font class="comment">// Caught a standard library exception</font>
}
</pre></div>
<p>
</div>
<p>
<div class="header">Extracting Form Information</div>
<div class="subsection">
<p>
Each element of data entered by the user is parsed into a <code><a class="el" href="classcgicc_1_1FormEntry.html">cgicc::FormEntry</a></code>. A <code><a class="el" href="classcgicc_1_1FormEntry.html">cgicc::FormEntry</a></code> contains methods for accessing data as strings, integers, and doubles. In the form mentioned above, a user would enter their name, age, and sex. Regardless of the type of value, the data is accessed using <code><a class="el" href="classcgicc_1_1FormEntry.html">cgicc::FormEntry</a></code> (this is not entirely true. For uploaded files, the data is accessed via the class <code><a class="el" href="classcgicc_1_1FormFile.html">cgicc::FormFile</a>)</code>. You obtain <code><a class="el" href="classcgicc_1_1FormEntry.html">cgicc::FormEntry</a></code> objects via <code><a class="el" href="classcgicc_1_1Cgicc.html">cgicc::Cgicc</a>'s</code> <code>getElement</code> methods, all of which return typedefs of C++ standard template library (STL) iterators:
<p>
<div class="fragment"><pre>cgicc::form_iterator name = cgi.<a class="code" href="classcgicc_1_1Cgicc.html#z2_3">getElement</a>(<font class="stringliteral">"name"</font>);
</pre></div>
<p>
If the item is not found, the iterator will refer to an invalid element, and should not be dereferenced using <code>operator*</code> or <code>operator-></code>. <code><a class="el" href="classcgicc_1_1Cgicc.html">cgicc::Cgicc</a></code> provides methods for determining whether an iterator refers to a valid element:
<p>
<div class="fragment"><pre><font class="keywordflow">if</font>(name != cgi.<a class="code" href="classcgicc_1_1Cgicc.html#z2_10">getElements</a>().end()) {
<font class="comment">// iterator refers to a valid element</font>
}
</pre></div>
<p>
</div>
<p>
<div class="header">Output of Form Data</div>
<div class="subsection">
<p>
Once you have a valid element, you will more than likely want to do something with the data. The simplest thing to do is just echo it back to the user. You can extract a <code>basic_string</code> from a <code><a class="el" href="classcgicc_1_1FormEntry.html">cgicc::FormEntry</a></code> by calling the <code>getValue</code> method. Since <code>ostream</code> has an overload for writing <code>basic_string</code> objects, it is trivial to output objects of this type:
<p>
<div class="fragment"><pre>cout << <font class="stringliteral">"Your name is "</font> << name->getValue() << endl;
</pre></div>
<p>
Since both <code>iterator</code> and <code><a class="el" href="classcgicc_1_1FormEntry.html">cgicc::FormEntry</a></code> overload <code>operator*</code>, the code given above may also be written as:
<p>
<div class="fragment"><pre>cout << <font class="stringliteral">"Your name is "</font> << **name << endl;
</pre></div>
<p>
The first <code>*</code> returns an object of type <code><a class="el" href="classcgicc_1_1FormEntry.html">cgicc::FormEntry</a></code>, and the second * returns an object of type <code>basic_string</code>.
<p>
</div>
<p>
<div class="header">The HTTP Response</div>
<div class="subsection">
<p>
A CGI response will generally consist of an HTML document. The HTTP protocol requires that a certain set of headers precede all documents, to inform the client of the size and type of data being received, among other things. In a normal CGI response, the HTTP server will take care of sending many of these headers for you. However, it is necessary for the CGI script to supply the type of content it is returning to the HTTP server and the client. This is done by emitting a <code>Content-Type</code> header. If you're interested, the full HTTP 1.1 specification may be found in RFC 2068 at <a href="http://www.w3.org/Protocols/rfc2068/rfc2068">http://www.w3.org/Protocols/rfc2068/rfc2068</a>
<p>
cgicc provides several classes for outputting HTTP headers, all of which begin with <code>HTTP</code>. A standard HTML 4.0 document need only output a single header:
<p>
<div class="fragment"><pre>cout << <a class="code" href="classcgicc_1_1HTTPHTMLHeader.html">cgicc::HTTPHTMLHeader</a>() << endl;
</pre></div>
<p>
This will generate the output
<p>
<div class="fragment"><pre>
Content-Type: text/html\n\n
</pre></div>
<p>
</div>
<p>
<div class="header">Simple HTML Output</div>
<div class="subsection">
<p>
cgicc provides one class for every HTML tag defined in the HTML 4.0 standard in the header file "<code><a class="el" href="HTMLClasses_8h.html">cgicc/HTMLClasses.h</a></code>". These classes have the same name as the HTML tags. For example, in HTML, to indicate the start of a document you write <code><html></code> ; this can be accomplished using cgicc by writing
<p>
<div class="fragment"><pre>cout << html() << endl;
</pre></div>
<p>
The class <code>html</code> keeps state internally, so the code above will produce as output <code><html></code>; conversely, the code
<p>
<div class="fragment"><pre>cout << html() << <font class="stringliteral">"html text!"</font> << html() << endl;
</pre></div>
<p>
will produce as output <code><html>html text!</html></code>.
<p>
All of cgicc's HTML output classes are subclasses of the abstract class <code><a class="el" href="classcgicc_1_1HTMLElement.html">cgicc::HTMLElement</a></code>. You can embed the text for the element directly in the constructor:
<p>
<div class="fragment"><pre>cout << html(<font class="stringliteral">"html text!"</font>) << endl;
</pre></div>
<p>
Furthermore, it is possible to embed one <code><a class="el" href="classcgicc_1_1HTMLElement.html">cgicc::HTMLElement</a></code> in another:
<p>
<div class="fragment"><pre>cout << head(title(<font class="stringliteral">"Title"</font>)) << endl;
</pre></div>
<p>
This produces as output <div class="fragment"><pre>
<head><title>Title</title></head>
</pre></div>
<p>
And, if you wish be more specific about the type of HTML 4.0 you are going to return (strict, transitional, or frameset), you can use the class <a class="el" href="classcgicc_1_1HTMLDoctype.html">cgicc::HTMLDoctype</a> before the cgicc::html tag:
<p>
<div class="fragment"><pre>cout << HTMLDoctype(HTMLDoctype::eStrict) << endl;
</pre></div>
<p>
which produces
<p>
<div class="fragment"><pre>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd">
</pre></div>
<p>
</div>
<p>
<div class="header">More Complex HTML Output</div>
<div class="subsection">
<p>
In real HTML, most tags possess a set of attributes. For example, the HTML <code><img></code> tag requires certain attributes specifying the source image file, the image width, height, and so on. There are a bewildering number of possible attributes in HTML 4.0. For a definitive list, see the HTML 4.0 specification at <a href="http://www.w3.org/TR/REC-html40/">http://www.w3.org/TR/REC-html40/</a> A typical <code><img></code> tag might look like:
<p>
<div class="fragment"><pre>
<img src="file.jpg" width="100" height="100" alt="description" />
</pre></div>
<p>
This tag has four attributes: <code>src</code>, <code>width</code>, <code>height</code>, and <code>alt</code>, with the values <code>file.jpg</code>, <code>100</code>, <code>100</code>, and <code>description</code>, respectively. Attributes in HTML tags are represented by the class <code><a class="el" href="classcgicc_1_1HTMLAttribute.html">cgicc::HTMLAttribute</a></code>, which essentially is a name/value pair. To build an <code><a class="el" href="classcgicc_1_1HTMLElement.html">cgicc::HTMLElement</a></code> containing <code><a class="el" href="classcgicc_1_1HTMLAttribute.html">cgicc::HTMLAttribute</a></code> objects, use the <code>set</code> method on <code><a class="el" href="classcgicc_1_1HTMLElement.html">cgicc::HTMLElement</a></code>. To generate the <code><img></code> tag given above:
<p>
<div class="fragment"><pre>cout << img().set(<font class="stringliteral">"src"</font>, <font class="stringliteral">"file.jpg"</font>)
.set(<font class="stringliteral">"width"</font>, <font class="stringliteral">"100"</font>).set(<font class="stringliteral">"height"</font>, <font class="stringliteral">"100"</font>)
.set(<font class="stringliteral">"alt"</font>, <font class="stringliteral">"description"</font>) << endl;
</pre></div>
<p>
In a similar way, multiple <code><a class="el" href="classcgicc_1_1HTMLElement.html">cgicc::HTMLElement</a></code> objects may be embedded at the same level inside another <code><a class="el" href="classcgicc_1_1HTMLElement.html">cgicc::HTMLElement</a></code>. To build an <code><a class="el" href="classcgicc_1_1HTMLElement.html">cgicc::HTMLElement</a></code> containing multiple embedded <code><a class="el" href="classcgicc_1_1HTMLElement.html">cgicc::HTMLElement</a></code> objects, use the <code>add</code> method on <code><a class="el" href="classcgicc_1_1HTMLElement.html">cgicc::HTMLElement</a></code>:
<p>
<div class="fragment"><pre>cout << tr().add(td(<font class="stringliteral">"0"</font>)).add(td(<font class="stringliteral">"1"</font>)).add(td(<font class="stringliteral">"2"</font>)) << endl;
</pre></div>
<p>
This produces as output <div class="fragment"><pre>
<tr><td>0</td><td>1</td><td>2</td></tr>
</pre></div>
<p>
</div>
<p>
<div class="header">Notes on Output</div>
<div class="subsection">
<p>
All of cgicc's output is written to a C++ standard output stream, usually <code>cout</code>. It is not necessary to use cgicc's HTML output classes; they are provided as a convenience. If you prefer, you may output the HTML code directly to <code>cout</code>.
<p>
</div>
<p>
<div class="header">The Complete Example</div>
<div class="subsection">
<p>
The code below is a complete CGI program that synthesizes all the sample code given above.
<p>
<div class="fragment"><pre><font class="preprocessor">#include <iostream></font>
<font class="preprocessor">#include <vector></font>
<font class="preprocessor">#include <string></font>
<font class="preprocessor">#include "<a class="code" href="Cgicc_8h.html">cgicc/Cgicc.h</a>"</font>
<font class="preprocessor">#include "<a class="code" href="HTTPHTMLHeader_8h.html">cgicc/HTTPHTMLHeader.h</a>"</font>
<font class="preprocessor">#include "<a class="code" href="HTMLClasses_8h.html">cgicc/HTMLClasses.h</a>"</font>
<font class="keyword">using</font> <font class="keyword">namespace </font>std;
<font class="keyword">using</font> <font class="keyword">namespace </font>cgicc;
<font class="keywordtype">int</font>
main(<font class="keywordtype">int</font> argc,
<font class="keywordtype">char</font> **argv)
{
<font class="keywordflow">try</font> {
Cgicc cgi;
<font class="comment">// Send HTTP header</font>
cout << HTTPHTMLHeader() << endl;
<font class="comment">// Set up the HTML document</font>
cout << html() << head(title(<font class="stringliteral">"Cgicc example"</font>)) << endl;
cout << body() << endl;
<font class="comment">// Print out the submitted element</font>
<a class="code" href="namespacecgicc.html#a0">form_iterator</a> name = cgi.<a class="code" href="classcgicc_1_1Cgicc.html#z2_3">getElement</a>(<font class="stringliteral">"name"</font>);
<font class="keywordflow">if</font>(name != cgi.<a class="code" href="classcgicc_1_1Cgicc.html#z2_10">getElements</a>().end()) {
cout << <font class="stringliteral">"Your name: "</font> << **name << endl;
}
<font class="comment">// Close the HTML document</font>
cout << body() << html();
}
<font class="keywordflow">catch</font>(exception& e) {
<font class="comment">// handle any errors - omitted for brevity</font>
}
}
</pre></div>
<p>
</div>
<p>
<small>
[ Previous: <a href="lib_overview.html#lib_overview">Library Overview</a> | Current: <a href="cgicc_tutorial.html#cgicc_tutorial">A Tutorial Example</a> | Next: <a href="cgicc_demos.html#cgicc_demos">GNU cgicc Demos</a> ]</small>
<p>
<!-- $Id: footer.html,v 1.3 2002/03/09 18:30:37 sbooth Exp $ -->
<hr>
<address><small>
GNU cgicc - A C++ class library for writing CGI applications<br />
Copyright © 1996 - 2002
<a href="mailto:sbooth@gnu.org">Stephen F. Booth</a><br />
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front Cover Texts, and with no Back-Cover
Texts.<br />
Documentation generated Sun Mar 17 16:40:57 2002 for cgicc by
<a HREF="http://www.doxygen.org/index.html">doxygen</a> 1.2.13.1
</small></address>
</body>
</html>
