<!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.5 2004/06/12 01:58:25 sbooth Exp $ -->
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>cgicc: A Tutorial Example</title>
<link rev="made" href="mailto:bug-cgicc@gnu.org" />
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="cgicc-doc.css" rel="stylesheet" type="text/css" />
</head>
<body>
<!-- Generated by Doxygen 1.5.9 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1><a class="anchor" name="cgicc_tutorial">A Tutorial Example </a></h1>
<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 class="fragment">
<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 class="fragment"><span class="keywordtype">int</span> <a class="code" href="cardgame_8cpp.html#3c04138a5bfe5d72780bb7e82a18e627" title="The main function.">main</a>(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span> **argv)
{
<span class="comment">// CGI processing goes here</span>
}
</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 <a class="el" href="classcgicc_1_1Cgicc.html" title="The main class of the GNU cgicc library.">cgicc::Cgicc</a>, <a class="el" href="classcgicc_1_1CgiEnvironment.html" title="Class encapsulating the CGI runtime environment.">cgicc::CgiEnvironment</a>, and <a class="el" href="classcgicc_1_1FormEntry.html" title="Class representing a single HTML form entry.">cgicc::FormEntry</a>. These classes will be explained in detail later; for now, it is sufficient to know that:<p>
<ul>
<li>
The class <a class="el" href="classcgicc_1_1Cgicc.html" title="The main class of the GNU cgicc library.">cgicc::Cgicc</a> is used for retrieving information on the submitted form elements.<p>
</li>
<li>
The class <a class="el" href="classcgicc_1_1CgiEnvironment.html" title="Class encapsulating the CGI runtime environment.">cgicc::CgiEnvironment</a> is used to retrieve information on environment variables passed from the HTTP server.<p>
</li>
<li>
The class <a class="el" href="classcgicc_1_1FormEntry.html" title="Class representing a single HTML form entry.">cgicc::FormEntry</a> is used to extract various types of data from the submitted form elements. </li>
</ul>
<p>
All of cgicc's functionality is accessed through class <a class="el" href="classcgicc_1_1Cgicc.html" title="The main class of the GNU cgicc library.">cgicc::Cgicc</a>. Thus, the first step in CGI processing is to instantiate an object of type <a class="el" href="classcgicc_1_1Cgicc.html" title="The main class of the GNU cgicc library.">cgicc::Cgicc</a>:<p>
<div class="fragment"><pre class="fragment"><a class="code" href="classcgicc_1_1Cgicc.html" title="The main class of the GNU cgicc library.">cgicc::Cgicc</a> cgi;
</pre></div><p>
or<p>
<div class="fragment"><pre class="fragment"><span class="keyword">using namespace </span>cgicc;
Cgicc cgi;
</pre></div><p>
Upon instantiation, the class <a class="el" href="classcgicc_1_1Cgicc.html" title="The main class of the GNU cgicc library.">cgicc::Cgicc</a> 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 class="fragment"><span class="keywordflow">try</span> {
<a class="code" href="classcgicc_1_1Cgicc.html" title="The main class of the GNU cgicc library.">cgicc::Cgicc</a> cgi;
}
<span class="keywordflow">catch</span>(exception& e) {
<span class="comment">// Caught a standard library exception</span>
}
</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 <a class="el" href="classcgicc_1_1FormEntry.html" title="Class representing a single HTML form entry.">cgicc::FormEntry</a>. A <a class="el" href="classcgicc_1_1FormEntry.html" title="Class representing a single HTML form entry.">cgicc::FormEntry</a> 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 <a class="el" href="classcgicc_1_1FormEntry.html" title="Class representing a single HTML form entry.">cgicc::FormEntry</a> (this is not entirely true. For uploaded files, the data is accessed via the class <a class="el" href="classcgicc_1_1FormFile.html" title="Class representing a file submitted via an HTML form.">cgicc::FormFile</a>). You obtain <a class="el" href="classcgicc_1_1FormEntry.html" title="Class representing a single HTML form entry.">cgicc::FormEntry</a> objects via <a class="el" href="classcgicc_1_1Cgicc.html" title="The main class of the GNU cgicc library.">cgicc::Cgicc</a>'s <code>getElement</code> methods, all of which return typedefs of C++ standard template library (STL) iterators:<p>
<div class="fragment"><pre class="fragment"><a class="code" href="namespacecgicc.html#2a771be8dbb16cf3bfe01cb422dbc449" title="A vector of FormEntry objects.">cgicc::form_iterator</a> name = cgi.<a class="code" href="classcgicc_1_1Cgicc.html#fc96c70b4de001b9a21610447a552bb1" title="Find a radio button in a radio group, or a selected list item.">getElement</a>(<span class="stringliteral">"name"</span>);
</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>. <a class="el" href="classcgicc_1_1Cgicc.html" title="The main class of the GNU cgicc library.">cgicc::Cgicc</a> provides methods for determining whether an iterator refers to a valid element:<p>
<div class="fragment"><pre class="fragment"><span class="keywordflow">if</span>(name != cgi.<a class="code" href="classcgicc_1_1Cgicc.html#021d316e1727c9a334614796db506d14" title="Get all the submitted form elements, excluding files.">getElements</a>().end()) {
<span class="comment">// iterator refers to a valid element</span>
}
</pre></div><p>
The <a class="el" href="classcgicc_1_1FormEntry.html" title="Class representing a single HTML form entry.">cgicc::FormEntry</a> class provides methods for extracting data as numbers, removing line breaks, etc. If you are not interested in performing any data validation or modification, but simply want to access a string representaion of the data, the simplest case is streamlined:<p>
<div class="fragment"><pre class="fragment">std::string name = cgi(<span class="stringliteral">"name"</span>);
</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 <a class="el" href="classcgicc_1_1FormEntry.html" title="Class representing a single HTML form entry.">cgicc::FormEntry</a> 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 class="fragment">cout << <span class="stringliteral">"Your name is "</span> << name->getValue() << endl;
</pre></div><p>
Since both <code>iterator</code> and <a class="el" href="classcgicc_1_1FormEntry.html" title="Class representing a single HTML form entry.">cgicc::FormEntry</a> overload <code>operator*</code>, the code given above may also be written as:<p>
<div class="fragment"><pre class="fragment">cout << <span class="stringliteral">"Your name is "</span> << **name << endl;
</pre></div><p>
The first <code>*</code> returns an object of type <a class="el" href="classcgicc_1_1FormEntry.html" title="Class representing a single HTML form entry.">cgicc::FormEntry</a>, and the second * returns an object of type <code>basic_string</code>.<p>
As mentioned above, if you simply want to output a string without validating or modifying the data, the simplest case is streamlined:<p>
<div class="fragment"><pre class="fragment">cout << <span class="stringliteral">"Your name is "</span> << cgi(<span class="stringliteral">"name"</span>) << endl;
</pre></div><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 class="fragment">cout << <a class="code" href="classcgicc_1_1HTTPHTMLHeader.html" title="Shortcut to HTTPContentHeader for text/html.">cgicc::HTTPHTMLHeader</a>() << endl;
</pre></div><p>
This will generate the output<p>
<div class="fragment"><pre class="fragment">
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>"cgicc/HTMLClasses.h"</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 class="fragment">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 class="fragment">cout << html() << <span class="stringliteral">"html text!"</span> << 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 <a class="el" href="classcgicc_1_1HTMLElement.html" title="Class representing an HTML element.">cgicc::HTMLElement</a>. You can embed the text for the element directly in the constructor:<p>
<div class="fragment"><pre class="fragment">cout << html(<span class="stringliteral">"html text!"</span>) << endl;
</pre></div><p>
Furthermore, it is possible to embed one <a class="el" href="classcgicc_1_1HTMLElement.html" title="Class representing an HTML element.">cgicc::HTMLElement</a> in another:<p>
<div class="fragment"><pre class="fragment">cout << head(title(<span class="stringliteral">"Title"</span>)) << endl;
</pre></div><p>
This produces as output <div class="fragment"><pre class="fragment">
<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" title="Specifies the DTD of the HTML 4 document.">cgicc::HTMLDoctype</a> before the cgicc::html tag:<p>
<div class="fragment"><pre class="fragment">cout << HTMLDoctype(HTMLDoctype::eStrict) << endl;
</pre></div><p>
which produces<p>
<div class="fragment"><pre class="fragment">
<!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 class="fragment">
<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 <a class="el" href="classcgicc_1_1HTMLAttribute.html" title="Class representing a name or a single name/value pair.">cgicc::HTMLAttribute</a>, which essentially is a name/value pair. To build an <a class="el" href="classcgicc_1_1HTMLElement.html" title="Class representing an HTML element.">cgicc::HTMLElement</a> containing <a class="el" href="classcgicc_1_1HTMLAttribute.html" title="Class representing a name or a single name/value pair.">cgicc::HTMLAttribute</a> objects, use the <code>set</code> method on <a class="el" href="classcgicc_1_1HTMLElement.html" title="Class representing an HTML element.">cgicc::HTMLElement</a>. To generate the <code><img></code> tag given above:<p>
<div class="fragment"><pre class="fragment">cout << img().set(<span class="stringliteral">"src"</span>, <span class="stringliteral">"file.jpg"</span>)
.set(<span class="stringliteral">"width"</span>, <span class="stringliteral">"100"</span>).set(<span class="stringliteral">"height"</span>, <span class="stringliteral">"100"</span>)
.set(<span class="stringliteral">"alt"</span>, <span class="stringliteral">"description"</span>) << endl;
</pre></div><p>
In a similar way, multiple <a class="el" href="classcgicc_1_1HTMLElement.html" title="Class representing an HTML element.">cgicc::HTMLElement</a> objects may be embedded at the same level inside another <a class="el" href="classcgicc_1_1HTMLElement.html" title="Class representing an HTML element.">cgicc::HTMLElement</a>. To build an <a class="el" href="classcgicc_1_1HTMLElement.html" title="Class representing an HTML element.">cgicc::HTMLElement</a> containing multiple embedded <a class="el" href="classcgicc_1_1HTMLElement.html" title="Class representing an HTML element.">cgicc::HTMLElement</a> objects, use the <code>add</code> method on <a class="el" href="classcgicc_1_1HTMLElement.html" title="Class representing an HTML element.">cgicc::HTMLElement</a>:<p>
<div class="fragment"><pre class="fragment">cout << tr().add(td(<span class="stringliteral">"0"</span>)).add(td(<span class="stringliteral">"1"</span>)).add(td(<span class="stringliteral">"2"</span>)) << endl;
</pre></div><p>
This produces as output <div class="fragment"><pre class="fragment">
<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 class="fragment"><span class="preprocessor">#include <iostream></span>
<span class="preprocessor">#include <vector></span>
<span class="preprocessor">#include <string></span>
<span class="preprocessor">#include "<a class="code" href="Cgicc_8h.html" title="The main header file for the GNU cgicc library.">cgicc/Cgicc.h</a>"</span>
<span class="preprocessor">#include "<a class="code" href="HTTPHTMLHeader_8h.html" title="Shortcut to HTTPContentHeader for text/html.">cgicc/HTTPHTMLHeader.h</a>"</span>
<span class="preprocessor">#include "<a class="code" href="HTMLClasses_8h.html" title="The header file containing HTML output classes.">cgicc/HTMLClasses.h</a>"</span>
<span class="keyword">using namespace </span>std;
<span class="keyword">using namespace </span>cgicc;
<span class="keywordtype">int</span>
<a class="code" href="cardgame_8cpp.html#3c04138a5bfe5d72780bb7e82a18e627" title="The main function.">main</a>(<span class="keywordtype">int</span> argc,
<span class="keywordtype">char</span> **argv)
{
<span class="keywordflow">try</span> {
Cgicc cgi;
<span class="comment">// Send HTTP header</span>
cout << HTTPHTMLHeader() << endl;
<span class="comment">// Set up the HTML document</span>
cout << html() << head(title(<span class="stringliteral">"cgicc example"</span>)) << endl;
cout << body() << endl;
<span class="comment">// Print out the submitted element</span>
<a class="code" href="namespacecgicc.html#2a771be8dbb16cf3bfe01cb422dbc449" title="A vector of FormEntry objects.">form_iterator</a> name = cgi.getElement(<span class="stringliteral">"name"</span>);
<span class="keywordflow">if</span>(name != cgi.getElements().end()) {
cout << <span class="stringliteral">"Your name: "</span> << **name << endl;
}
<span class="comment">// Close the HTML document</span>
cout << body() << html();
}
<span class="keywordflow">catch</span>(exception& e) {
<span class="comment">// handle any errors - omitted for brevity</span>
}
}
</pre></div><p>
</div>
<p>
<div class="nav">
Previous: <a class="el" href="lib_overview.html">Library Overview</a> | Current: <a class="el" href="cgicc_tutorial.html">A Tutorial Example</a> | Next: <a class="el" href="cgicc_demos.html">GNU cgicc Demos</a>
</div>
</div>
<!-- $Id: footer.html,v 1.7 2004/06/12 01:58:25 sbooth Exp $ -->
<hr>
<address><small>
<a href="http://www.cgicc.org">GNU cgicc</a> - A C++ class library for
writing CGI applications<br />
Copyright © 1996 - 2004
<a href="mailto:sboothATgnuDOTorg">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 Tue Jun 9 15:30:16 2009 for cgicc by
<a HREF="http://www.doxygen.org/index.html">doxygen</a> 1.5.9
</small></address>
</body>
</html>
distrib
>
Mandriva
>
2010.1
>
x86_64
>
media
>
contrib-release
>
by-pkgid
>
faa1042277fc54511a5cd73681616a31
>
files
>
114
