Index: trunk/lib/Text/FormBuilder.pm =================================================================== --- trunk/lib/Text/FormBuilder.pm (revision 85) +++ trunk/lib/Text/FormBuilder.pm (revision 87) @@ -7,8 +7,6 @@ use vars qw($VERSION @EXPORT); -$VERSION = '0.11'; +$VERSION = '0.12_01'; @EXPORT = qw(create_form); - -#$::RD_TRACE = 1; use Carp; @@ -288,4 +286,13 @@ } + my %fb_params; + if ($self->{form_spec}->{fb_params}) { + require YAML; + eval { %fb_params = %{ YAML::Load($self->{form_spec}->{fb_params}) } }; + if ($@) { + warn '[' . (caller(0))[3] . "] Bad !fb parameter block:\n$@"; + } + } + # gather together all of the form options $self->{form_options} = { @@ -314,5 +321,7 @@ }, }, - %options, + #TODO: fields in fb_params are not getting recognized + %fb_params, # params from the formspec file + %options, # params from this method invocation }; @@ -684,4 +693,7 @@ L +You will also need L, if you want to use the L|/dump> +method, or the L|/!fb> directive in your formspec files. + =head1 DESCRIPTION @@ -1013,4 +1025,25 @@ =head2 Directives +All directives start with a C followed by a keyword. There are two types of +directives: + +=over + +=item Line directives + +Line directives occur all on one line, and require no special punctuation. Examples +of line directives are L|/!title> and L|/!section>. + +=item Block directives + +Block directives consist of a directive keyword followed by a curly-brace delimited +block. Examples of these are L|/!group> and L|/!description>. +Some of these directives have their own internal structure; see the list of directives +below for an explanation. + +=back + +And here is the complete list of directives + =over @@ -1030,41 +1063,46 @@ =item C -B Include a named instance of a group defined with C. +B Include a named instance of a group defined with C. See +L for an explanation of the new way to include +groups. =item C -Title of the form. +Line directive contianing the title of the form. =item C -Author of the form. +Line directive naming the author of the form. =item C -A brief description of the form. Suitable for special instructions on how to -fill out the form. +A block directive containing a brief description of the form. Suitable for +special instructions on how to fill out the form. All of the text within the +block is folded into a single paragraph. =item C -Starts a new section. Each section has its own heading and id, which are -written by default into spearate tables. +A line directive that starts a new section. Each section has its own heading +and id, which by default are rendered into spearate tables. =item C -Inserts a heading between two fields. There can only be one heading between -any two fields; the parser will warn you if you try to put two headings right -next to each other. +A line directive that inserts a heading between two fields. There can only be +one heading between any two fields; the parser will warn you if you try to put +two headings right next to each other. =item C -A text note that can be inserted as a row in the form. This is useful for -special instructions at specific points in a long form. +A block directive containing a text note that can be inserted as a row in the +form. This is useful for special instructions at specific points in a long form. +Like L|/!description>, the text content is folded into a single +paragraph. =item C -A list of one or more submit button labels in a comma-separated list. Each label -is a L. Multiple instances of this directive may be used; later -lists are simply appended to the earlier lists. All the submit buttons are -rendered together at the bottom of the form. See L for an +A line directive with one or more submit button labels in a comma-separated list. +Each label is a L. Multiple instances of this directive may be +used; later lists are simply appended to the earlier lists. All the submit buttons +are rendered together at the bottom of the form. See L for an explanation of how the multiple submit buttons work together in a form. @@ -1073,6 +1111,21 @@ =item C -The label for the a reset button at the end of the form. No reset button will be -rendered unless you use this directive. +Line directive giving a label for the a reset button at the end of the form. No +reset button will be rendered unless you use this directive. + +=item C + +The C block directive allows you to include any parameters you want passed +directly to the CGI::FormBuilder constructor. The block should be a hashref of +parameters serialized as L. Be sure to place the closing of the block on +its own line, flush to the left edge, and to watch your indentation. Multiple +C blocks are concatenated, and the result is interpeted as one big chunk +of YAML code. + + !fb{ + method: POST + action: '/custom/action' + javascript: 0 + } =back @@ -1080,8 +1133,7 @@ =head2 Strings -First, a note about multiword strings in the fields. Anywhere where it says -that you may use a multiword string, this means that you can do one of two -things. For strings that consist solely of alphanumeric characters (i.e. -C<\w+>) and spaces, the string will be recognized as is: +Anywhere that it says that you may use a multiword string, this means you can +do one of two things. For strings that consist solely of alphanumeric characters +(i.e. C<\w+>) and spaces, the string will be recognized as is: field_1|A longer label @@ -1257,9 +1309,9 @@ } -You can then include instances of this group using the C directive: - - !field %DATE birthday - -This will create a line in the form labeled ``Birthday'' which contains +You can also use groups in normal field lines: + + birthday|Your birthday:DATE + +This will create a line in the form labeled ``Your birthday'' which contains a month dropdown, and day and year text entry fields. The actual input field names are formed by concatenating the C name (e.g. C) with @@ -1268,10 +1320,12 @@ C, and C. -You can also use groups in normal field lines: - - birthday|Your birthday:DATE - The only (currently) supported pieces of a fieldspec that may be used with a group in this notation are name, label, and hint. + +The old method of using field groups was with the C directive: + + !field %DATE birthday + +This format is now B, and the parser will warn you if you use it. =head2 Comments @@ -1297,10 +1351,4 @@ Make sure that multiple runs of the parser don't share data. -Warn/suggest using the C directive if some uses C? - -Set FB constructor options directly in the formspec (via a C or similar -directive). The major issue here would be what format to use to allow for -array/hash refs. - Pieces that wouldn't make sense in a group field: size, row/col, options, validate. These should cause C to emit a warning before ignoring them. @@ -1325,4 +1373,9 @@ Creating two $parsers in the same script causes the second one to get the data from the first one. + +Placing C in a C directive does not behave as expected (i.e. they +don't show up). This is not a big issue, since you should be defining your fields +in the body of the formspec file, but for completeness' sake I would like to get +this figured out. I'm sure there are more in there, I just haven't tripped over any new ones lately. :-) @@ -1342,5 +1395,5 @@ sections. -And of course, to Nathan Wiger, for giving use CGI::FormBuilder in the +And of course, to Nathan Wiger, for giving us CGI::FormBuilder in the first place. Thanks Nate! Index: trunk/lib/Text/FormBuilder/grammar =================================================================== --- trunk/lib/Text/FormBuilder/grammar (revision 85) +++ trunk/lib/Text/FormBuilder/grammar (revision 87) @@ -40,5 +40,5 @@ %formspec = (); # clear the old formspec data } - (list_def | description_def | group_def | note | unknown_block_directive | line)(s) + (list_def | description_def | group_def | note | fb_params | unknown_block_directive | line)(s) { # grab the last section, if there is any @@ -53,17 +53,18 @@ $return = { - title => $formspec{title}, - author => $formspec{author}, + fb_params => $formspec{fb_params}, + title => $formspec{title}, + author => $formspec{author}, description => $formspec{description}, - lists => \%lists, - patterns => \%patterns, - subs => \%subs, - groups => \%groups, - sections => \@sections, + lists => \%lists, + patterns => \%patterns, + subs => \%subs, + groups => \%groups, + sections => \@sections, ( @submit ? (submit => @submit == 1 ? $submit[0] : \@submit) : () ), - reset => $formspec{reset}, + reset => $formspec{reset}, } } @@ -173,4 +174,8 @@ group_name: /%[A-Z_]+/ +# parameters that get passed to the FB constructor; these are serialized in YAML +fb_params: '!fb' block + { $formspec{fb_params} .= $item{block}; } + field_group: name label(?) hint(?) group_type comment(?) { @@ -189,5 +194,5 @@ # this is the real heart of the thing field: name field_size(?) growable(?) label(?) hint(?) type(?) multi(?) other(?) default(?) option_list(?) validate(?) comment(?) - { + { my $field = { name => $item{name},