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