tutorial.tmpl
1/* -*-html-*- */
2/*
3 * $Id: tutorial.tmpl,v 1.8 2004/06/29 15:13:15 sbooth Exp $
4 *
5 * Copyright (C) 1996 - 2004 Stephen F. Booth <sbooth@gnu.org>
6 * Part of the GNU cgicc library, http://www.cgicc.org
7 *
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".
15 */
16
17/*! \page cgicc_tutorial A Tutorial Example
18
19\htmlonly
20<div class="header">Introduction</div>
21<div class="subsection">
22\endhtmlonly
23
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.
29
30You would begin by creating an HTML form containing the HTML fragment
31
32\verbatim
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 />
38</form>
39\endverbatim
40
41Then, on to the CGI application. Applications written using %cgicc,
42like all other applications, begin with a \c main function:
43
44\code
45int main(int argc, char **argv)
46{
47 // CGI processing goes here
48}
49\endcode
50
51\htmlonly
52</div>
53\endhtmlonly
54
55\htmlonly
56<div class="header">Initialization</div>
57<div class="subsection">
58\endhtmlonly
59
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:
64
65<ul>
66<li>The class cgicc::Cgicc is used for retrieving information on
67the submitted form elements.</li>
68
69<li>The class cgicc::CgiEnvironment is used to retrieve information
70on environment variables passed from the HTTP server.</li>
71
72<li>The class cgicc::FormEntry is used to extract various types of
73data from the submitted form elements.</li>
74</ul>
75
76All of %cgicc's functionality is accessed through class cgicc::Cgicc.
77Thus, the first step in CGI processing is to instantiate an object of
78type cgicc::Cgicc:
79
80\code
81cgicc::Cgicc cgi;
82\endcode
83
84or
85
86\code
87using namespace cgicc;
88Cgicc cgi;
89\endcode
90
91Upon instantiation, the class cgicc::Cgicc parses all data passed to the
92CGI script by the HTTP server.
93
94Since errors are handled using exceptions, you may wish to wrap your CGI
95code in a \c try block to better handle unexpected conditions:
96
97\code
98try {
99 cgicc::Cgicc cgi;
100}
101
102catch(exception& e) {
103 // Caught a standard library exception
104}
105\endcode
106
107\htmlonly
108</div>
109\endhtmlonly
110
111\htmlonly
112<div class="header">Extracting Form Information</div>
113<div class="subsection">
114\endhtmlonly
115
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:
124
125\code
126cgicc::form_iterator name = cgi.getElement("name");
127\endcode
128
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:
133
134\code
135if(name != cgi.getElements().end()) {
136 // iterator refers to a valid element
137}
138\endcode
139
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:
144
145\code
146std::string name = cgi("name");
147\endcode
148
149\htmlonly
150</div>
151\endhtmlonly
152
153\htmlonly
154<div class="header">Output of Form Data</div>
155<div class="subsection">
156\endhtmlonly
157
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:
163
164\code
165cout << "Your name is " << name->getValue() << endl;
166\endcode
167
168Since both \c iterator and cgicc::FormEntry overload
169\c operator*, the code given above may also be written as:
170
171\code
172cout << "Your name is " << **name << endl;
173\endcode
174
175The first \c * returns an object of type cgicc::FormEntry, and the second *
176returns an object of type \c basic_string.
177
178As mentioned above, if you simply want to output a string without validating
179or modifying the data, the simplest case is streamlined:
180
181\code
182cout << "Your name is " << cgi("name") << endl;
183\endcode
184
185\htmlonly
186</div>
187\endhtmlonly
188
189\htmlonly
190<div class="header">The HTTP Response</div>
191<div class="subsection">
192\endhtmlonly
193
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
204
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
207single header:
208
209\code
210cout << cgicc::HTTPHTMLHeader() << endl;
211\endcode
212
213This will generate the output
214
215\verbatim
216Content-Type: text/html\n\n
217\endverbatim
218
219\htmlonly
220</div>
221\endhtmlonly
222
223\htmlonly
224<div class="header">Simple HTML Output</div>
225<div class="subsection">
226\endhtmlonly
227
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
233
234\code
235cout << html() << endl;
236\endcode
237
238The class \c html keeps state internally, so the code above will
239produce as output \c <html>; conversely, the code
240
241\code
242cout << html() << "html text!" << html() << endl;
243\endcode
244
245will produce as output <tt><html>html text!</html></tt>.
246
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
249the constructor:
250
251\code
252cout << html("html text!") << endl;
253\endcode
254
255Furthermore, it is possible to embed one cgicc::HTMLElement in another:
256
257\code
258cout << head(title("Title")) << endl;
259\endcode
260
261This produces as output
262\verbatim
263<head><title>Title</title></head>
264\endverbatim
265
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:
269
270\code
271cout << HTMLDoctype(HTMLDoctype::eStrict) << endl;
272\endcode
273
274which produces
275
276\verbatim
277<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd">
278\endverbatim
279
280\htmlonly
281</div>
282\endhtmlonly
283
284\htmlonly
285<div class="header">More Complex HTML Output</div>
286<div class="subsection">
287\endhtmlonly
288
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
295like:
296
297\verbatim
298<img src="file.jpg" width="100" height="100" alt="description" />
299\endverbatim
300
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:
307
308\code
309cout << img().set("src", "file.jpg")
310 .set("width", "100").set("height", "100")
311 .set("alt", "description") << endl;
312\endcode
313
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:
318
319\code
320cout << tr().add(td("0")).add(td("1")).add(td("2")) << endl;
321\endcode
322
323This produces as output
324\verbatim
325<tr><td>0</td><td>1</td><td>2</td></tr>
326\endverbatim
327
328\htmlonly
329</div>
330\endhtmlonly
331
332\htmlonly
333<div class="header">Notes on Output</div>
334<div class="subsection">
335\endhtmlonly
336
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.
341
342\htmlonly
343</div>
344\endhtmlonly
345
346\htmlonly
347<div class="header">The Complete Example</div>
348<div class="subsection">
349\endhtmlonly
350
351The code below is a complete CGI program that synthesizes all the sample
352code given above.
353
354\code
355#include <iostream>
356#include <vector>
357#include <string>
358
359#include "cgicc/Cgicc.h"
360#include "cgicc/HTTPHTMLHeader.h"
361#include "cgicc/HTMLClasses.h"
362
363using namespace std;
364using namespace cgicc;
365
366int
367main(int argc,
368 char **argv)
369{
370 try {
371 Cgicc cgi;
372
373 // Send HTTP header
374 cout << HTTPHTMLHeader() << endl;
375
376 // Set up the HTML document
377 cout << html() << head(title("cgicc example")) << endl;
378 cout << body() << endl;
379
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;
384 }
385
386 // Close the HTML document
387 cout << body() << html();
388 }
389 catch(exception& e) {
390 // handle any errors - omitted for brevity
391 }
392}
393\endcode
394
395\htmlonly
396</div>
397\endhtmlonly
398
399\htmlonly
400<div class="nav">
401\endhtmlonly
402Previous: \ref lib_overview |
403Current: \ref cgicc_tutorial |
404Next: \ref cgicc_demos
405\htmlonly
406</div>
407\endhtmlonly
408*/