File Coverage

blib/lib/HTML/FormEngine.pm
Criterion Covered Total %
statement 45 501 8.9
branch 1 222 0.4
condition 1 160 0.6
subroutine 9 48 18.7
pod 27 28 96.4
total 83 959 8.6


line stmt bran cond sub pod time code
1             =head1 NAME
2              
3             HTML::FormEngine - create,validate and control html/xhtml forms
4              
5             =cut
6              
7             ######################################################################
8              
9             package HTML::FormEngine;
10             require 5.004;
11              
12             # Copyright (c) 2003-2004, Moritz Sinn. This module is free software;
13             # you can redistribute it and/or modify it under the terms of the
14             # GNU GENERAL PUBLIC LICENSE, see COPYING for more information.
15              
16 1     1   20320 use strict;
  1         2  
  1         34  
17 1     1   5 use vars qw($VERSION);
  1         1  
  1         56  
18             $VERSION = '1.01';
19              
20             ######################################################################
21              
22             =head1 DEPENDENCIES
23              
24             =head2 Perl Version
25              
26             5.004
27              
28             =head2 Standard Modules
29              
30             Carp
31              
32             =head2 Nonstandard Modules
33              
34             Clone 0.13
35             Hash::Merge 0.07
36             Locale::gettext 1.01
37             Date::Pcalc 1.2
38             Digest::MD5 2.24
39             HTML::Entities 1.27
40              
41             =cut
42              
43             ######################################################################
44              
45 1     1   624 use Clone qw(clone);
  1         2687  
  1         61  
46 1     1   739 use Hash::Merge qw(merge);
  1         2485  
  1         63  
47 1     1   8 use Carp;
  1         2  
  1         41  
48 1     1   476 use HTML::FormEngine::SkinClassic;
  1         3  
  1         6354  
49              
50             ######################################################################
51              
52             =head1 SYNOPSIS
53              
54             =head2 Example Code
55              
56             #!/usr/bin/perl -w
57              
58             use strict;
59             use CGI;
60             use HTML::FormEngine;
61             #use POSIX; # for setlocale
62             #setlocale(LC_MESSAGES, 'german'); # for german error messages
63              
64             my $q = new CGI;
65             print $q->header;
66              
67             my $Form = HTML::FormEngine->new(scalar $q->Vars);
68             my @form = (
69             {
70             templ => 'select',
71             NAME => 'Salutation',
72             OPTION => [[['mr.','mrs.']]],
73             },
74             {
75             templ => 'hidden_no_title',
76             NAME => 'test123',
77             VALUE => 'test',
78             },
79             {
80             SIZE => 10,
81             MAXLEN => 20,
82             PREFIX => [[' ', ' / ']],
83             NAME => 'name',
84             TITLE => 'For- / Surname ',
85             ERROR_IN => 'not_null'
86             },
87             {
88             MAXLEN => 30,
89             NAME => 'Email',
90             ERROR => ['not_null', ['rfc822'], ['match', 'matched net!']] # rfc822 defines the email address standard
91             },
92             {
93             templ => 'radio',
94             TITLE => 'Subscribe to newsletter?',
95             NAME => 'newsletter',
96             OPT_VAL => [[1, 2, 3]],
97             OPTION => [['Yes', 'No', 'Perhaps']],
98             VALUE => 1
99             },
100             {
101             templ => 'check',
102             OPTION => 'I agree to the terms of condition!',
103             NAME => "agree",
104             TITLE => '',
105             ERROR => sub{ return("you've to agree!") if(! shift); }
106             }
107             );
108              
109             $Form->set_seperate(1);
110             $Form->conf(\@form);
111             $Form->make();
112              
113             print $q->start_html('FormEngine example: Registration');
114             if($Form->ok){
115             $Form->clear();
116             print "
You've successfully subscribed!

";
117             }
118             print $Form->get,
119             $q->end_html;
120              
121             =head2 Example Output
122              
123             This output is produced by FormEngine when using the example code and
124             no data was submitted:
125              
126            
127            
128            
129            
130            
131            
132            
133              
134            
135            
136            
137              
138            
139              
140            
141            
142            
143            
144              
145            
146              
147            
148            
149            
150            
151            
152            
153              
154            
155            
156            
157            
158            
159            
160            
161            
162            
163            
164              
165            
166            
167              
168            
169            
170            
171              
172            
173              
174            
175            
176            
177            
178            
179            
180              / 
181            
182              
183            
184            
185              
186            
187            
188            
189            
190            
191              
192            
193            
194            
195            
196            
197            
198            
199            
200            
201            
202              
203            
204            
205              
206            
207            
208            
209              
210              
211            
212            
213            
214            
215            
216            
217            
218            
219            
220            
221              
222            
223            
224            
225            
226            
227            
228            
229              
230              
231            
232             Yes
233            
234              
235            
236            
237            
238            
239              
240            
241            
242            
243              
244            
245             No
246            
247              
248              
249            
250            
251            
252            
253            
254            
255            
256              
257              
258            
259             Perhaps
260            
261              
262            
263            
264            
265            
266              
267            
268            
269            
270            
271            
272            
273            
274            
275            
276            
277              
278            
279            
280            
281              
282            
283             I agree to the terms of condition!
284            
285              
286              
287            
288            
289            
290            
291            
292            
293            
294            
295            
296            
297              
298            
299            
300            
301            
302            
303              
304            
305              
306             =head1 DESCRIPTION
307              
308             FormEngine.pm is a Perl 5 object class which provides an api for
309             managing html/xhtml forms. FormEngine has its own, very flexible
310             template system for defining form skins. A default skin and a more
311             flexible one is provided. This should be sufficent in most cases, but
312             extending the skins or making your own isn't difficult (please send
313             them to me!).
314              
315             FormEngine also provides a set of functions for checking the form
316             input, it is very easy to define your own check methods or to adapt
317             the given.
318              
319             I is used for internationalization (e.g. error messages). So
320             use C if you want to have german
321             error messages, butten lables and so on (there isn't support for any
322             other language yet, but it shouldn't be difficult to translate the .po
323             file, don't hesitate!).
324              
325             Another usefull feature is the C method which forces the user
326             to read through his input once again before submitting it.
327              
328             FormEngine is designed to make extension writing an easy task!
329              
330             =head1 OVERVIEW
331              
332             Start with calling the C method, it will return an FormEngine
333             object. As argument you should pass a reference to a hash of input
334             values (calling C is also possible, environments like
335             mod_perl or CGI.pm offer already a hash of input values, see
336             C for more). Now define an array which contains the form
337             configuration and pass a reference to C. Then call C, this
338             will generate the html code. Next you can use C to check if the
339             form was submitted and all input values are correct. If this is the
340             case, you can e.g. display a success message and call
341             C for getting the value of a certain field and
342             e.g. write it in a database. Else you should call C (which will
343             return the html form code) or C which will directly print the
344             form.
345              
346             If you want the form to be always displayed, you can use C to
347             empty it (resp. display the defaults) when the transmission was
348             successfull.
349              
350             =head1 USING FORMENGINE
351              
352             The easiest way to define your form is to create an array of hash
353             references:
354              
355             my @form = (
356             {
357             templ => 'select',
358             NAME => 'Salutation',
359             OPTION => [[['mr.','mrs.']]],
360             },
361             {
362             templ => 'hidden_no_title',
363             NAME => 'test123',
364             VALUE => 'test',
365             },
366             {
367             SIZE => 10,
368             MAXLEN => 20,
369             PREFIX => [[' ', ' / ']],
370             NAME => 'name',
371             TITLE => 'For- / Surname ',
372             ERROR_IN => 'not_null'
373             },
374             {
375             MAXLEN => 30,
376             NAME => 'Email',
377             ERROR => ['not_null', ['rfc822'], ['match', 'matched net!']] # rfc822 defines the email address standard
378             },
379             {
380             templ => 'radio',
381             TITLE => 'Subscribe to newsletter?',
382             NAME => 'newsletter',
383             OPT_VAL => [[1, 2, 3]],
384             OPTION => [['Yes', 'No', 'Perhaps']],
385             VALUE => 1
386             },
387             {
388             templ => 'check',
389             OPTION => 'I agree to the terms of condition!',
390             NAME => "agree",
391             TITLE => '',
392             ERROR => sub{ return("you've to agree!") if(! shift); }
393             }
394             );
395              
396             This was taken out of the example above. The I key defines the
397             field type (resp. template), the capital written keys are explained
398             below. If I is not defined, it is expected to be C.
399              
400             Then pass a reference to that array to the C method like this:
401              
402             $Form->conf(\@form);
403              
404             Another possibility is to define a hash of hash references and pass a
405             reference on that to C. This is seldom needed, but has the
406             advantage that you can define low level variables:
407              
408             my %form = (
409             METHOD => 'get',
410             FORMNAME => 'myform',
411             SUBMIT => 'Yea! I want that!',
412             'sub' => [
413             # Here you place your form definition (see above)
414             ]
415             );
416              
417             $Form->conf(\%form);
418              
419             The meaning of the keys is explained below. You can call
420             C for setting low level (main) variables as well, the
421             only difference is that the variables set through L
422             HASHREF )> are persistend, that means even if you call the L
423             FORMCONF )> method again they're still set if not overwritten.
424              
425             =head2 The Default Skin (FormEngine)
426              
427             If you want to use the same fieldname several times (e.g. for a group
428             of checkboxes or for two textfields like name and forename), you have
429             to call C and pass 1 (for true). See C for
430             more.
431              
432             The following templates are known by the default skin:
433              
434             =over
435              
436             =item
437              
438             B - text input field(s), one row
439              
440             =item
441              
442             B