Changeset 19 in text-formbuilder for trunk


Ignore:
Timestamp:
11/09/04 12:47:12 (20 years ago)
Author:
peter
Message:

more documentation
added automagic parse method; moved old parse($file) method to parse_file

Location:
trunk
Files:
6 edited

Legend:

Unmodified
Added
Removed

  • trunk/Changes

    r1 r19  
    1 Revision history for Perl extension Text::FormBuilder. 
     1Release history for Text::FormBuilder. 
    22 
    3 0.01  Mon Oct  4 09:25:07 2004 
    4         - original version; created by h2xs 1.23 with options 
    5                 -Xn Text::FormBuilder 
    6  
     30.05 -  9 Nov 2004 
     4    * First CPAN release 

  • trunk/MANIFEST

    r17 r19  
    66lib/Text/FormBuilder.pm 
    77lib/Text/FormBuilder/Parser.pm 
     8lib/Text/FormBuilder/grammar 
    89META.yml                                 Module meta-data (added by MakeMaker) 

  • trunk/Makefile.PL

    r17 r19  
    99    PREREQ_PM         => {  
    1010                            CGI::FormBuilder => 2.13, 
     11                            Text::Template => 1.44, 
    1112                         }, # e.g., Module::Name => 1.1 
    1213    ($] >= 5.005 ?     ## Add these new keywords supported since 5.005 

  • trunk/README

    r17 r19  
    1 Text-FormBuilder version 0.04 
     1Text-FormBuilder version 0.05 
    22============================= 
    33 
    … …  
    1616 
    1717  CGI::FormBuilder 2.13 
     18  Text::Template 1.44 
     19 
     20Optional: 
     21 
     22  Perl::Tidy 
     23  YAML 
    1824 
    1925COPYRIGHT AND LICENCE 

  • trunk/lib/Text/FormBuilder.pm

    r16 r19  
    44use warnings; 
    55 
    6 our $VERSION = '0.04'; 
     6use vars qw($VERSION); 
     7 
     8$VERSION = '0.05'; 
    79 
    810use Carp; 
    … …  
    2022 
    2123sub parse { 
     24    my ($self, $source) = @_; 
     25    if (ref $source && ref $source eq 'SCALAR') { 
     26        $self->parse_text($$source); 
     27    } else { 
     28        $self->parse_file($source); 
     29    } 
     30} 
     31 
     32sub parse_file { 
    2233    my ($self, $filename) = @_; 
    2334     
    … …  
    5970     
    6071    # substitute in custom pattern definitions for field validation 
    61     if (my %patterns = %{ $self->{form_spec}{patterns} }) { 
     72    if (my %patterns = %{ $self->{form_spec}{patterns} || {} }) { 
    6273        foreach (@{ $self->{form_spec}{fields} }) { 
    6374            if ($$_{validate} and exists $patterns{$$_{validate}}) { 
    … …  
    7889     
    7990    # substitute in list names 
    80     if (my %lists = %{ $self->{form_spec}{lists} }) { 
     91    if (my %lists = %{ $self->{form_spec}{lists} || {} }) { 
    8192        foreach (@{ $self->{form_spec}{fields} }) { 
    8293            next unless $$_{list}; 
    … …  
    322333    # the fields from the input form spec 
    323334    my $form = $parser->form; 
     335     
     336    # write a My::Form module to Form.pm 
     337    $parser->write_module('My::Form'); 
    324338 
    325339=head1 DESCRIPTION 
    … …  
    329343=head2 parse 
    330344 
    331     $parser->parse($src_file); 
     345    # parse a file 
     346    $parser->parse($filename); 
     347     
     348    # or pass a scalar ref for parse a literal string 
     349    $parser->parse(\$string); 
     350 
     351Parse the file or string. Returns the parser object. 
     352 
     353=head2 parse_file 
     354 
     355    $parser->parse_file($src_file); 
    332356     
    333357    # or as a class method 
    … …  
    338362    $parser->parse_text($src); 
    339363 
    340 Parse the given C<$src> text. Returns the parse object. 
     364Parse the given C<$src> text. Returns the parser object. 
    341365 
    342366=head2 build 
    … …  
    348372=over 
    349373 
    350 =item form_only 
     374=item C<form_only> 
    351375 
    352376Only uses the form portion of the template, and omits the surrounding html, 
    353 title, author, and the standard footer. 
     377title, author, and the standard footer. This does, however, include the 
     378description as specified with the C<!description> directive. 
    354379 
    355380=back 
    … …  
    398423First, you parse the formspec and write the module, which you can do as a one-liner: 
    399424 
    400     $ perl -MText::FormBuilder -e"Text::FormBuilder->parse('formspec.txt')->write_module('MyForm')" 
     425    $ perl -MText::FormBuilder -e"Text::FormBuilder->parse('formspec.txt')->write_module('My::Form')" 
    401426 
    402427And then, in your CGI script, use the new module: 
    … …  
    406431     
    407432    use CGI; 
    408     use MyForm; 
     433    use My::Form; 
    409434     
    410435    my $q = CGI->new; 
    411     my $form = MyForm::get_form($q); 
     436    my $form = My::Form::get_form($q); 
    412437     
    413438    # do the standard CGI::FormBuilder stuff 
    … …  
    422447will run L<Perl::Tidy> on the generated code before writing the module file. 
    423448 
     449    # write tidier code 
     450    $parser->write_module('My::Form', 1); 
     451 
    424452=head2 dump 
    425453 
    … …  
    429457=head1 LANGUAGE 
    430458 
    431     field_name[size]|descriptive label[hint]:type=default{option1[display string],option2[display string],...}//validate 
     459    field_name[size]|descriptive label[hint]:type=default{option1[display string],...}//validate 
    432460     
    433461    !title ... 
    … …  
    469497=item C<!description> 
    470498 
     499A brief description of the form. Suitable for special instructions on how to 
     500fill out the form. 
     501 
    471502=item C<!head> 
    472503 
    … …  
    479510=head2 Fields 
    480511 
    481 Form fields are each described on a single line. 
     512Form fields are each described on a single line. The simplest field is just a 
     513name: 
     514 
     515    color 
     516 
     517This yields a form with one text input field of the default size named `color'. 
     518The label for this field as generated by CGI::FormBuilder would be ``Color''. 
     519To add a longer or more descriptive label, use: 
     520 
     521    color|Favorite color 
     522 
     523Field names cannot contain whitespace, but the descriptive label can. 
     524 
     525To use a different input type: 
     526 
     527    color|Favorite color:select{red,blue,green} 
     528 
     529Recognized input types are the same as those used by CGI::FormBuilder: 
     530 
     531    text        # the default 
     532    textarea 
     533    select 
     534    radio 
     535    checkbox 
     536    static 
     537 
     538This example also shows how you can list multiple values for the input types 
     539that take multiple values (C<select>, C<radio>, and C<checkbox>). Values are 
     540in a comma-separated list inside curly braces. Whitespace between values is 
     541irrelevant, although there cannot be any whitespace within a value. 
     542 
     543To add more descriptive display text to a vlaue in a list, add a square-bracketed 
     544``subscript,'' as in: 
     545 
     546    ...:select{red[Scarlet],blue[Azure],green[Olive Drab]} 
     547 
     548As you can see, spaces I<are> allowed within the display text for a value. 
    482549 
    483550If you have a list of options that is too long to fit comfortably on one line, 
    484 consider using the C<!list> directive. 
     551consider using the C<!list> directive: 
     552 
     553    !list MONTHS { 
     554        1[January], 
     555        2[February], 
     556        3[March], 
     557        # and so on... 
     558    } 
     559     
     560    month:select@MONTHS 
     561 
     562There is another form of the C<!list> directive: the dynamic list: 
     563 
     564    !list RANDOM &{ map { rand } (0..5) } 
     565 
     566The code inside the C<&{ ... }> is C<eval>ed by C<build>, and the results 
     567are stuffed into the list. The C<eval>ed code can either return a simple 
     568list, as the example does, or the fancier C<( { value1 => 'Description 1'}, 
     569{ value2 => 'Description 2}, ...)> form. 
     570 
     571B<NOTE:> This feature of the language may go away unless I find a compelling 
     572reason for it in the next few versions. What I really wanted was lists that 
     573were filled in at run-time (e.g. from a database), and that can be done easily 
     574enough with the CGI::FormBuilder object directly. 
     575 
     576You can also supply a default value to the field. To get a default value of 
     577C<green> for the color field: 
     578 
     579    color|Favorite color:select=green{red,blue,green} 
     580 
     581To validate a field, include a validation type at the end of the field line: 
     582 
     583    email|Email address//EMAIL 
     584 
     585Valid validation types include any of the builtin defaults from CGI::FormBuilder, 
     586or the name of a pattern that you define with the C<!pattern> directive elsewhere 
     587in your form spec: 
     588 
     589    !pattern DAY /^([1-3][0-9])|[1-9]$/ 
     590     
     591    last_day//DAY 
     592 
     593If you just want a required value, use the builtin validation type C<VALUE>: 
     594 
     595    title//VALUE 
    485596 
    486597=head2 Comments 
    … …  
    496607Field groups all on one line in the generated form 
    497608 
    498 Tests! 
     609Better tests! 
    499610 
    500611=head1 SEE ALSO 

  • trunk/t/Text-FormBuilder.t

    r9 r19  
    66# change 'tests => 1' to 'tests => last_test_to_print'; 
    77 
    8 use Test::More tests => 4; 
     8use Test::More tests => 6; 
    99BEGIN { use_ok('Text::FormBuilder'); }; 
    1010 
    … …  
    1616my $p = Text::FormBuilder->new; 
    1717isa_ok($p, 'Text::FormBuilder', 'new parser'); 
    18 isa_ok($p->parse_text('')->build->form, 'CGI::FormBuilder',  'generated CGI::FormBuilder object'); 
     18isa_ok($p->parse_text('')->build->form, 'CGI::FormBuilder',  'generated CGI::FormBuilder object (build->form)'); 
     19isa_ok($p->parse_text('')->form,        'CGI::FormBuilder',  'generated CGI::FormBuilder object (form)'); 
    1920 
    20 my $p2 = Text::FormBuilder->parse_text(''); 
    21 isa_ok($p2, 'Text::FormBuilder', 'new parser (from parse_text as class method)'); 
     21$p = Text::FormBuilder->parse_text(''); 
     22isa_ok($p, 'Text::FormBuilder', 'new parser (from parse_text as class method)'); 
     23 
     24$p = Text::FormBuilder->parse(\''); 
     25isa_ok($p, 'Text::FormBuilder', 'new parser (from parse as class method)'); 
     26 
Note: See TracChangeset for help on using the changeset viewer.