Changeset 46 in text-formbuilder

Timestamp:

12/15/04 16:49:51 (20 years ago)

Author:

peichman

Message:

added examples documentation; documented the create_form function; updated README

Location:

trunk

Files:

• Changes (modified) (1 diff)
• MANIFEST (modified) (1 diff)
• README (modified) (2 diffs)
• lib/Text/FormBuilder.pm (modified) (7 diffs)
• lib/Text/FormBuilder/Examples.pod (added)

trunk/Changes

@@ -9 +9 @@
     * added write_script method to write a skeleton CGI
       script around the FormBuilder object
+    * added external documentation of usage examples
     
 0.06 - 19 Nov 2004

trunk/MANIFEST

@@ -5 +5 @@
 t/Text-FormBuilder.t
 lib/Text/FormBuilder.pm
+lib/Text/FormBuilder/Examples.pod
 lib/Text/FormBuilder/Parser.pm
 lib/Text/FormBuilder/grammar

trunk/README

@@ -1 @@
-Text-FormBuilder version 0.05
-=============================
+Text-FormBuilder version 0.07_03
+================================
 
 INSTALLATION
@@ -17 +17 @@
   CGI::FormBuilder 2.13
   Text::Template 1.44
+  Parse::RecDescent
 
 Optional:

trunk/lib/Text/FormBuilder.pm

@@ -7 +7 @@
 use vars qw($VERSION @EXPORT);
 
-$VERSION = '0.07_02';
+$VERSION = '0.07_03';
 @EXPORT = qw(create_form);
 
@@ -48 +48 @@
 
 my $HTML_EXTS   = qr/\.html?$/;
+my $MODULE_EXTS = qr/\.pm$/;
 my $SCRIPT_EXTS = qr/\.(pl|cgi)$/;
 
@@ -61 +62 @@
         } else {
             # write webpage, script, or module
-            if ($destination =~ $HTML_EXTS) {
-                $parser->write($destination);
+            if ($destination =~ $MODULE_EXTS) {
+                $parser->write_module($destination);
             } elsif ($destination =~ $SCRIPT_EXTS) {
                 $parser->write_script($destination);
             } else {
-                $parser->write_module($destination);
+                $parser->write($destination);
             }
         }
@@ -686 +687 @@
 karate, and bass guitar.
 
+=head1 METHODS
+
 =head2 new
 
@@ -886 +889 @@
 Uses L<YAML> to print out a human-readable representation of the parsed
 form spec.
+
+=head1 EXPORTS
+
+There is one exported function, C<create_form>, that is intended to ``do the
+right thing'' in simple cases.
+
+=head2 create_form
+
+    # get a CGI::FormBuilder object
+    my $form = create_form($source, $options, $destination);
+    
+    # or just write the form immediately
+    create_form($source, $options, $destination);
+
+C<$source> accepts any of the types of arguments that C<parse> does. C<$options>
+is a hashref of options that should be passed to C<build>. Finally, C<$destination>
+is a simple scalar that determines where and what type of output C<create_form>
+should generate.
+
+    /\.pm$/             ->write_module($destination)
+    /\.(cgi|pl)$/       ->write_script($destination)
+    everything else     ->write($destination)
+
+For anything more than simple, one-off cases, you are usually better off using the
+object-oriented interface, since that gives you more control over things.
 
 =head1 DEFAULTS
@@ -1151 +1179 @@
 (since CGI::FormBuilder users may be more likely to already have HTML::Template)
 
-Better examples in the docs (maybe a standalone or two as well)
-
 C<!include> directive to include external formspec files
 
@@ -1161 +1187 @@
 Creating two $parsers in the same script causes the second one to get the data
 from the first one.
-
-Get the fallback to CGI::FormBuilder builtin lists to work.
 
 I'm sure there are more in there, I just haven't tripped over any new ones lately. :-)