3 * $Id: tutorial.tmpl,v 1.8 2004/06/29 15:13:15 sbooth Exp $
5 * Copyright (C) 1996 - 2004 Stephen F. Booth <sbooth@gnu.org>
6 * Part of the GNU cgicc library, http://www.cgicc.org
8 * Permission is granted to copy, distribute and/or modify this document
9 * under the terms of the GNU Free Documentation License, Version 1.1
10 * or any later version published by the Free Software Foundation;
11 * with no Invariant Sections, with no Front-Cover Texts, and with
12 * no Back-Cover Texts.
13 * A copy of the license is included in the section entitled "GNU
14 * Free Documentation License".
17/*! \page cgicc_tutorial A Tutorial Example
20<div class="header">Introduction</div>
21<div class="subsection">
24It is easiest to understand how the GNU %cgicc library might be used
25by first looking at an example. Suppose you want an HTML form on your
26web site asking a user to enter their name, age, and sex, perhaps as
27part of a user-registration procedure, and you wish to write a CGI script
28using %cgicc to process the form in some meaningful way.
30You would begin by creating an HTML form containing the HTML fragment
33<form method="post" action="http://change_this_path/cgi-bin/foo.cgi">
34Your name : <input type="text" name="name" /><br />
35Your age : <input type="text" name="age" /><br />
36Your sex : <input type="radio" name="sex" value="male"checked="checked" />Male
37<input type="radio" name="sex" value="female" />Female <br />
41Then, on to the CGI application. Applications written using %cgicc,
42like all other applications, begin with a \c main function:
45int main(int argc, char **argv)
47 // CGI processing goes here
56<div class="header">Initialization</div>
57<div class="subsection">
60The three main classes of %cgicc you will use to process the submitted
61data are cgicc::Cgicc, cgicc::CgiEnvironment, and cgicc::FormEntry.
62These classes will be explained in detail later; for now, it is
63sufficient to know that:
66<li>The class cgicc::Cgicc is used for retrieving information on
67the submitted form elements.</li>
69<li>The class cgicc::CgiEnvironment is used to retrieve information
70on environment variables passed from the HTTP server.</li>
72<li>The class cgicc::FormEntry is used to extract various types of
73data from the submitted form elements.</li>
76All of %cgicc's functionality is accessed through class cgicc::Cgicc.
77Thus, the first step in CGI processing is to instantiate an object of
91Upon instantiation, the class cgicc::Cgicc parses all data passed to the
92CGI script by the HTTP server.
94Since errors are handled using exceptions, you may wish to wrap your CGI
95code in a \c try block to better handle unexpected conditions:
103 // Caught a standard library exception
112<div class="header">Extracting Form Information</div>
113<div class="subsection">
116Each element of data entered by the user is parsed into a cgicc::FormEntry. A
117cgicc::FormEntry contains methods for accessing data as strings, integers, and
118doubles. In the form mentioned above, a user would enter their name, age, and
119sex. Regardless of the type of value, the data is accessed using
120cgicc::FormEntry (this is not entirely true. For uploaded files, the data is
121accessed via the class cgicc::FormFile). You obtain cgicc::FormEntry objects
122via cgicc::Cgicc's \c getElement methods, all of which return typedefs of C++
123standard template library (STL) iterators:
126cgicc::form_iterator name = cgi.getElement("name");
129If the item is not found, the iterator will refer to an invalid element,
130and should not be dereferenced using \c operator* or
131\c operator->. cgicc::Cgicc provides methods for determining
132whether an iterator refers to a valid element:
135if(name != cgi.getElements().end()) {
136 // iterator refers to a valid element
140The cgicc::FormEntry class provides methods for extracting data as numbers,
141removing line breaks, etc. If you are not interested in performing any data
142validation or modification, but simply want to access a string representaion
143of the data, the simplest case is streamlined:
146std::string name = cgi("name");
154<div class="header">Output of Form Data</div>
155<div class="subsection">
158Once you have a valid element, you will more than likely want to do something
159with the data. The simplest thing to do is just echo it back to the user.
160You can extract a \c basic_string from a cgicc::FormEntry by calling the \c
161getValue method. Since \c ostream has an overload for writing \c basic_string
162objects, it is trivial to output objects of this type:
165cout << "Your name is " << name->getValue() << endl;
168Since both \c iterator and cgicc::FormEntry overload
169\c operator*, the code given above may also be written as:
172cout << "Your name is " << **name << endl;
175The first \c * returns an object of type cgicc::FormEntry, and the second *
176returns an object of type \c basic_string.
178As mentioned above, if you simply want to output a string without validating
179or modifying the data, the simplest case is streamlined:
182cout << "Your name is " << cgi("name") << endl;
190<div class="header">The HTTP Response</div>
191<div class="subsection">
194A CGI response will generally consist of an HTML document. The HTTP
195protocol requires that a certain set of headers precede all documents,
196to inform the client of the size and type of data being received,
197among other things. In a normal CGI response, the HTTP server will
198take care of sending many of these headers for you. However, it is
199necessary for the CGI script to supply the type of content it is
200returning to the HTTP server and the client. This is done by emitting
201a \c Content-Type header. If you're interested, the full HTTP 1.1
202specification may be found in RFC 2068 at
203http://www.w3.org/Protocols/rfc2068/rfc2068
205%cgicc provides several classes for outputting HTTP headers, all of which
206begin with \c HTTP. A standard HTML 4.0 document need only output a
210cout << cgicc::HTTPHTMLHeader() << endl;
213This will generate the output
216Content-Type: text/html\n\n
224<div class="header">Simple HTML Output</div>
225<div class="subsection">
228%cgicc provides one class for every HTML tag defined in the HTML 4.0
229standard in the header file \c "cgicc/HTMLClasses.h". These classes
230have the same name as the HTML tags. For example, in HTML, to indicate
231the start of a document you write \c <html> ; this can be accomplished
232using %cgicc by writing
235cout << html() << endl;
238The class \c html keeps state internally, so the code above will
239produce as output \c <html>; conversely, the code
242cout << html() << "html text!" << html() << endl;
245will produce as output <tt><html>html text!</html></tt>.
247All of %cgicc's HTML output classes are subclasses of the abstract class
248cgicc::HTMLElement. You can embed the text for the element directly in
252cout << html("html text!") << endl;
255Furthermore, it is possible to embed one cgicc::HTMLElement in another:
258cout << head(title("Title")) << endl;
261This produces as output
263<head><title>Title</title></head>
266And, if you wish be more specific about the type of HTML 4.0 you are
267going to return (strict, transitional, or frameset), you can use the
268class cgicc::HTMLDoctype before the cgicc::html tag:
271cout << HTMLDoctype(HTMLDoctype::eStrict) << endl;
277<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd">
285<div class="header">More Complex HTML Output</div>
286<div class="subsection">
289In real HTML, most tags possess a set of attributes. For example, the
290HTML \c <img> tag requires certain attributes specifying the source
291image file, the image width, height, and so on. There are a bewildering
292number of possible attributes in HTML 4.0. For a definitive
293list, see the HTML 4.0 specification at
294http://www.w3.org/TR/REC-html40/ A typical \c <img> tag might look
298<img src="file.jpg" width="100" height="100" alt="description" />
301This tag has four attributes: \c src, \c width, \c height, and \c alt, with
302the values \c file.jpg, \c 100, \c 100, and \c description, respectively.
303Attributes in HTML tags are represented by the class cgicc::HTMLAttribute,
304which essentially is a name/value pair. To build an cgicc::HTMLElement
305containing cgicc::HTMLAttribute objects, use the \c set method on
306cgicc::HTMLElement. To generate the \c <img> tag given above:
309cout << img().set("src", "file.jpg")
310 .set("width", "100").set("height", "100")
311 .set("alt", "description") << endl;
314In a similar way, multiple cgicc::HTMLElement objects may be embedded at
315the same level inside another cgicc::HTMLElement. To build an
316cgicc::HTMLElement containing multiple embedded cgicc::HTMLElement
317objects, use the \c add method on cgicc::HTMLElement:
320cout << tr().add(td("0")).add(td("1")).add(td("2")) << endl;
323This produces as output
325<tr><td>0</td><td>1</td><td>2</td></tr>
333<div class="header">Notes on Output</div>
334<div class="subsection">
337All of %cgicc's output is written to a C++ standard output stream,
338usually \c cout. It is not necessary to use %cgicc's HTML output
339classes; they are provided as a convenience. If you prefer, you may
340output the HTML code directly to \c cout.
347<div class="header">The Complete Example</div>
348<div class="subsection">
351The code below is a complete CGI program that synthesizes all the sample
359#include "cgicc/Cgicc.h"
360#include "cgicc/HTTPHTMLHeader.h"
361#include "cgicc/HTMLClasses.h"
364using namespace cgicc;
374 cout << HTTPHTMLHeader() << endl;
376 // Set up the HTML document
377 cout << html() << head(title("cgicc example")) << endl;
378 cout << body() << endl;
380 // Print out the submitted element
381 form_iterator name = cgi.getElement("name");
382 if(name != cgi.getElements().end()) {
383 cout << "Your name: " << **name << endl;
386 // Close the HTML document
387 cout << body() << html();
389 catch(exception& e) {
390 // handle any errors - omitted for brevity
402Previous: \ref lib_overview |
403Current: \ref cgicc_tutorial |
404Next: \ref cgicc_demos