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 
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.
29 
30 You 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">
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 />
38 </form>
39 \endverbatim
40 
41 Then, on to the CGI application. Applications written using %cgicc,
42 like all other applications, begin with a \c main function:
43 
44 \code
45 int 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 
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:
64 
65 <ul>
66 <li>The class cgicc::Cgicc is used for retrieving information on
67 the submitted form elements.</li>
68 
69 <li>The class cgicc::CgiEnvironment is used to retrieve information
70 on environment variables passed from the HTTP server.</li>
71 
72 <li>The class cgicc::FormEntry is used to extract various types of
73 data from the submitted form elements.</li>
74 </ul>
75 
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
78 type cgicc::Cgicc:
79 
80 \code
81 cgicc::Cgicc cgi;
82 \endcode
83 
84 or
85 
86 \code
87 using namespace cgicc;
88 Cgicc cgi;
89 \endcode
90 
91 Upon instantiation, the class cgicc::Cgicc parses all data passed to the
92 CGI script by the HTTP server.
93 
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:
96 
97 \code
98 try {
99  cgicc::Cgicc cgi;
100 }
101 
102 catch(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 
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:
124 
125 \code
126 cgicc::form_iterator name = cgi.getElement("name");
127 \endcode
128 
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:
133 
134 \code
135 if(name != cgi.getElements().end()) {
136  // iterator refers to a valid element
137 }
138 \endcode
139 
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:
144 
145 \code
146 std::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 
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:
163 
164 \code
165 cout << "Your name is " << name->getValue() << endl;
166 \endcode
167 
168 Since both \c iterator and cgicc::FormEntry overload
169 \c operator*, the code given above may also be written as:
170 
171 \code
172 cout << "Your name is " << **name << endl;
173 \endcode
174 
175 The first \c * returns an object of type cgicc::FormEntry, and the second *
176 returns an object of type \c basic_string.
177 
178 As mentioned above, if you simply want to output a string without validating
179 or modifying the data, the simplest case is streamlined:
180 
181 \code
182 cout << "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 
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
204 
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
207 single header:
208 
209 \code
210 cout << cgicc::HTTPHTMLHeader() << endl;
211 \endcode
212 
213 This will generate the output
214 
215 \verbatim
216 Content-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
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
233 
234 \code
235 cout << html() << endl;
236 \endcode
237 
238 The class \c html keeps state internally, so the code above will
239 produce as output \c <html>; conversely, the code
240 
241 \code
242 cout << html() << "html text!" << html() << endl;
243 \endcode
244 
245 will produce as output <tt><html>html text!</html></tt>.
246 
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
249 the constructor:
250 
251 \code
252 cout << html("html text!") << endl;
253 \endcode
254 
255 Furthermore, it is possible to embed one cgicc::HTMLElement in another:
256 
257 \code
258 cout << head(title("Title")) << endl;
259 \endcode
260 
261 This produces as output
262 \verbatim
263 <head><title>Title</title></head>
264 \endverbatim
265 
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:
269 
270 \code
271 cout << HTMLDoctype(HTMLDoctype::eStrict) << endl;
272 \endcode
273 
274 which 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 
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
295 like:
296 
297 \verbatim
298 <img src="file.jpg" width="100" height="100" alt="description" />
299 \endverbatim
300 
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:
307 
308 \code
309 cout << img().set("src", "file.jpg")
310  .set("width", "100").set("height", "100")
311  .set("alt", "description") << endl;
312 \endcode
313 
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:
318 
319 \code
320 cout << tr().add(td("0")).add(td("1")).add(td("2")) << endl;
321 \endcode
322 
323 This 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 
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.
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 
351 The code below is a complete CGI program that synthesizes all the sample
352 code 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 
363 using namespace std;
364 using namespace cgicc;
365 
366 int
367 main(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
402 Previous: \ref lib_overview |
403 Current: \ref cgicc_tutorial |
404 Next: \ref cgicc_demos
405 \htmlonly
406 </div>
407 \endhtmlonly
408 */

GNU cgicc - A C++ class library for writing CGI applications
Copyright © 1996 - 2004 Stephen F. Booth
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.
Documentation generated Sat Jun 25 2016 04:56:12 for cgicc by doxygen 1.8.10