Changeset 87 in text-formbuilder for trunk/lib


Ignore:
Timestamp:
06/29/05 16:02:34 (19 years ago)
Author:
peichman
Message:

added !fb directive to hold FB parameters as YAML serialized values
updated and expanded the documentation

Location:
trunk/lib/Text
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/lib/Text/FormBuilder.pm

    r85 r87  
    77use vars qw($VERSION @EXPORT); 
    88 
    9 $VERSION = '0.11'; 
     9$VERSION = '0.12_01'; 
    1010@EXPORT = qw(create_form); 
    11  
    12 #$::RD_TRACE = 1; 
    1311 
    1412use Carp; 
     
    288286    } 
    289287     
     288    my %fb_params; 
     289    if ($self->{form_spec}->{fb_params}) { 
     290        require YAML; 
     291        eval { %fb_params = %{ YAML::Load($self->{form_spec}->{fb_params}) } }; 
     292        if ($@) { 
     293            warn '[' . (caller(0))[3] . "] Bad !fb parameter block:\n$@"; 
     294        } 
     295    } 
     296     
    290297    # gather together all of the form options 
    291298    $self->{form_options} = { 
     
    314321            }, 
    315322        }, 
    316         %options, 
     323        #TODO: fields in fb_params are not getting recognized 
     324        %fb_params,     # params from the formspec file 
     325        %options,       # params from this method invocation 
    317326    }; 
    318327     
     
    684693L<Class::Base> 
    685694 
     695You will also need L<YAML>, if you want to use the L<C<dump>|/dump> 
     696method, or the L<C<!fb>|/!fb> directive in your formspec files. 
     697 
    686698=head1 DESCRIPTION 
    687699 
     
    10131025=head2 Directives 
    10141026 
     1027All directives start with a C<!> followed by a keyword. There are two types of 
     1028directives: 
     1029 
     1030=over 
     1031 
     1032=item Line directives 
     1033 
     1034Line directives occur all on one line, and require no special punctuation. Examples 
     1035of line directives are L<C<!title>|/!title> and L<C<!section>|/!section>. 
     1036 
     1037=item Block directives 
     1038 
     1039Block directives consist of a directive keyword followed by a curly-brace delimited 
     1040block. Examples of these are L<C<!group>|/!group> and L<C<!description>|/!description>. 
     1041Some of these directives have their own internal structure; see the list of directives 
     1042below for an explanation. 
     1043 
     1044=back 
     1045 
     1046And here is the complete list of directives 
     1047 
    10151048=over 
    10161049 
     
    10301063=item C<!field> 
    10311064 
    1032 B<DEPRECATED> Include a named instance of a group defined with C<!group>. 
     1065B<DEPRECATED> Include a named instance of a group defined with C<!group>. See 
     1066L<Field Groups|/Field Groups> for an explanation of the new way to include 
     1067groups. 
    10331068 
    10341069=item C<!title> 
    10351070 
    1036 Title of the form. 
     1071Line directive contianing the title of the form. 
    10371072 
    10381073=item C<!author> 
    10391074 
    1040 Author of the form. 
     1075Line directive naming the author of the form. 
    10411076 
    10421077=item C<!description> 
    10431078 
    1044 A brief description of the form. Suitable for special instructions on how to 
    1045 fill out the form. 
     1079A block directive containing a brief description of the form. Suitable for  
     1080special instructions on how to fill out the form. All of the text within the 
     1081block is folded into a single paragraph. 
    10461082 
    10471083=item C<!section> 
    10481084 
    1049 Starts a new section. Each section has its own heading and id, which are 
    1050 written by default into spearate tables. 
     1085A line directive that starts a new section. Each section has its own heading 
     1086and id, which by default are rendered into spearate tables. 
    10511087 
    10521088=item C<!head> 
    10531089 
    1054 Inserts a heading between two fields. There can only be one heading between 
    1055 any two fields; the parser will warn you if you try to put two headings right 
    1056 next to each other. 
     1090A line directive that inserts a heading between two fields. There can only be 
     1091one heading between any two fields; the parser will warn you if you try to put 
     1092two headings right next to each other. 
    10571093 
    10581094=item C<!note> 
    10591095 
    1060 A text note that can be inserted as a row in the form. This is useful for 
    1061 special instructions at specific points in a long form. 
     1096A block directive containing a text note that can be inserted as a row in the 
     1097form. This is useful for special instructions at specific points in a long form. 
     1098Like L<C<!description>|/!description>, the text content is folded into a single 
     1099paragraph. 
    10621100 
    10631101=item C<!submit> 
    10641102 
    1065 A list of one or more submit button labels in a comma-separated list. Each label 
    1066 is a L<string|/Strings>. Multiple instances of this directive may be used; later 
    1067 lists are simply appended to the earlier lists. All the submit buttons are  
    1068 rendered together at the bottom of the form. See L<CGI::FormBuilder> for an 
     1103A line directive with  one or more submit button labels in a comma-separated list. 
     1104Each label is a L<string|/Strings>. Multiple instances of this directive may be 
     1105used; later lists are simply appended to the earlier lists. All the submit buttons 
     1106are rendered together at the bottom of the form. See L<CGI::FormBuilder> for an 
    10691107explanation of how the multiple submit buttons work together in a form. 
    10701108 
     
    10731111=item C<!reset> 
    10741112 
    1075 The label for the a reset button at the end of the form. No reset button will be 
    1076 rendered unless you use this directive. 
     1113Line directive giving a label for the a reset button at the end of the form. No  
     1114reset button will be rendered unless you use this directive. 
     1115 
     1116=item C<!fb> 
     1117 
     1118The C<!fb> block directive allows you to include any parameters you want passed 
     1119directly to the CGI::FormBuilder constructor. The block should be a hashref of 
     1120parameters serialized as L<YAML>. Be sure to place the closing of the block on 
     1121its own line, flush to the left edge, and to watch your indentation. Multiple 
     1122C<!fb> blocks are concatenated, and the result is interpeted as one big chunk 
     1123of YAML code. 
     1124 
     1125    !fb{ 
     1126    method: POST 
     1127    action: '/custom/action' 
     1128    javascript: 0 
     1129    } 
    10771130 
    10781131=back 
     
    10801133=head2 Strings 
    10811134 
    1082 First, a note about multiword strings in the fields. Anywhere where it says 
    1083 that you may use a multiword string, this means that you can do one of two 
    1084 things. For strings that consist solely of alphanumeric characters (i.e. 
    1085 C<\w+>) and spaces, the string will be recognized as is: 
     1135Anywhere that it says that you may use a multiword string, this means you can 
     1136do one of two things. For strings that consist solely of alphanumeric characters  
     1137(i.e. C<\w+>) and spaces, the string will be recognized as is: 
    10861138 
    10871139    field_1|A longer label 
     
    12571309    } 
    12581310 
    1259 You can then include instances of this group using the C<!field> directive: 
    1260  
    1261     !field %DATE birthday 
    1262  
    1263 This will create a line in the form labeled ``Birthday'' which contains 
     1311You can also use groups in normal field lines: 
     1312 
     1313    birthday|Your birthday:DATE 
     1314 
     1315This will create a line in the form labeled ``Your birthday'' which contains 
    12641316a month dropdown, and day and year text entry fields. The actual input field 
    12651317names are formed by concatenating the C<!field> name (e.g. C<birthday>) with 
     
    12681320C<birthday_day>, and C<birthday_year>. 
    12691321 
    1270 You can also use groups in normal field lines: 
    1271  
    1272     birthday|Your birthday:DATE 
    1273  
    12741322The only (currently) supported pieces of a fieldspec that may be used with a 
    12751323group in this notation are name, label, and hint. 
     1324 
     1325The old method of using field groups was with the C<!field> directive: 
     1326 
     1327    !field %DATE birthday 
     1328 
     1329This format is now B<deprecated>, and the parser will warn you if you use it. 
    12761330 
    12771331=head2 Comments 
     
    12971351Make sure that multiple runs of the parser don't share data. 
    12981352 
    1299 Warn/suggest using the C<!submit> directive if some uses C<foo:submit>? 
    1300  
    1301 Set FB constructor options directly in the formspec (via a C<!fb> or similar 
    1302 directive). The major issue here would be what format to use to allow for 
    1303 array/hash refs. 
    1304  
    13051353Pieces that wouldn't make sense in a group field: size, row/col, options, 
    13061354validate. These should cause C<build> to emit a warning before ignoring them. 
     
    13251373Creating two $parsers in the same script causes the second one to get the data 
    13261374from the first one. 
     1375 
     1376Placing C<fields> in a C<!fb> directive does not behave as expected (i.e. they 
     1377don't show up). This is not a big issue, since you should be defining your fields 
     1378in the body of the formspec file, but for completeness' sake I would like to get 
     1379this figured out. 
    13271380 
    13281381I'm sure there are more in there, I just haven't tripped over any new ones lately. :-) 
     
    13421395sections. 
    13431396 
    1344 And of course, to Nathan Wiger, for giving use CGI::FormBuilder in the 
     1397And of course, to Nathan Wiger, for giving us CGI::FormBuilder in the 
    13451398first place. Thanks Nate! 
    13461399 
  • trunk/lib/Text/FormBuilder/grammar

    r84 r87  
    4040        %formspec = ();  # clear the old formspec data 
    4141    } 
    42     (list_def | description_def | group_def | note | unknown_block_directive | line)(s) 
     42    (list_def | description_def | group_def | note | fb_params | unknown_block_directive | line)(s) 
    4343    { 
    4444        # grab the last section, if there is any 
     
    5353         
    5454        $return = { 
    55             title    => $formspec{title}, 
    56             author   => $formspec{author}, 
     55            fb_params   => $formspec{fb_params}, 
     56            title       => $formspec{title}, 
     57            author      => $formspec{author}, 
    5758            description => $formspec{description}, 
    58             lists    => \%lists, 
    59             patterns => \%patterns, 
    60             subs     => \%subs, 
    61             groups   => \%groups, 
    62             sections => \@sections, 
     59            lists       => \%lists, 
     60            patterns    => \%patterns, 
     61            subs        => \%subs, 
     62            groups      => \%groups, 
     63            sections    => \@sections, 
    6364            ( @submit ?  
    6465                (submit => @submit == 1 ? $submit[0] : \@submit) : 
    6566                () 
    6667            ), 
    67             reset => $formspec{reset}, 
     68            reset       => $formspec{reset}, 
    6869        } 
    6970    } 
     
    173174group_name: /%[A-Z_]+/ 
    174175 
     176# parameters that get passed to the FB constructor; these are serialized in YAML 
     177fb_params: '!fb' block 
     178    { $formspec{fb_params} .= $item{block}; } 
     179 
    175180field_group: name label(?) hint(?) group_type comment(?) 
    176181    { 
     
    189194# this is the real heart of the thing 
    190195field: name field_size(?) growable(?) label(?) hint(?) type(?) multi(?) other(?) default(?) option_list(?) validate(?) comment(?) 
    191     { 
     196    {    
    192197        my $field = { 
    193198            name     => $item{name}, 
Note: See TracChangeset for help on using the changeset viewer.