FORMFIELD does not expand $name, $attributes, $type, $size and $definingTopic, although it is documented to do so.

Also, it is missing $n, $nop, $quot, $percnt & $dollar (as in formatted search). The $n is particularly annoying right now; I want to emit a
when a form field is non-null.

I looked at Render.pm, where FORMFIELD is rendered.

1. $name is easy to add.
2. $definingTopic - We can do this, given the (documented) restriction of only one form per topic. If the restriction is lifted, doing it efficiently would require backpointers in the metadata.
3. $attributes, $type, $size - I assume the intent is to work back to the topic that defines the form. I don't think we can do this without adding metadata. Only the form defintion topic has this information. We can find that, but we don't know what revision was used when the form was attached. I think this needs to be considered and handled by someone with more time & context.
4. The literal tokens are trivial.

Here is an example of why $n is useful. There are several chunks of optional attribute data that are materialized when present. They want their own paragraphs - but not whitespace when missing. Before suggesting %<nop>IF, clearly one really only wants to evaluate (much less type!) something like this once. (The example looks nonsensical because I have replaced sensitive variable names. The intent here is to show structure.)

%FORMFIELD{"LeaveType" topic="%INCLUDINGTOPIC%" format="$n%FORMFIELD{"PronounHe" topic="%INCLUDINGTOPIC%"}% took leave $value%FORMFIELD{"LeavePlace" topic="%INCLUDINGTOPIC%" format=" in $value"}%%FORMFIELD{"LeaveDate" topic="%INCLUDINGTOPIC%" format=" on $value"  }%." }%

Here is a patch for items 1, 2, and 4. After due consideration, someone else needs to either fix item 3 or correct the documentation.

--- lib/TWiki/Render.pm~        2008-09-11 23:41:58.000000000 -0400
+++ lib/TWiki/Render.pm 2008-12-22 12:53:20.000000000 -0500
@@ -842,10 +842,23 @@
                 $found = 1;
                 my $value = $field->{value};
                 if (length $value) {
                     $text = $format;
+                   $text =~ s/\$name/$field->{name}/g;
+                   if( $format =~ m/\$definingTopic/ ) {
+                       my @defform = $meta->find('FORM');
+                       my $form = $defform[0];  #TWiki only supports one form per topic
+                       my $fname = $form->{name};
+                       $text =~ s/\$definingTopic/$fname/g;
+
+                   }
+                   $text =~ s/\$n/\%BR\%/g;
+                   $text =~ s/\$quot/\"/g;
+                   $text =~ s/\$percnt/\%/g;
+                   $text =~ s/\$dollar/\$/g;
+
                     $text =~ s/\$value/$value/go;
                 } elsif ( defined $default ) {
                     $text = $default;
                 }
                 last; #one hit suffices

-- TWiki:Main/TimotheLitt - 22 Dec 2008

There's a form on this topic, so we can test it here (view using http://trunk.foswiki.org/Tasks/Item549 for the trunk code)

• %FORMFIELD{"Summary" format="$value expands to the field value, and $title expands to the fieldname (also expands $name, $attributes, $type, $size and $definingTopic"}%
  • FORMFIELD plugin does not render documented format variables; missing literal tokens expands to the field value, and Summary expands to the fieldname (also expands Summary, $attributes, $type, $size and $definingTopic

I agree with your analysis, and with your observations about item 3. I think $definingTopic is a terrible key for the form, so will use $form.

Note that $n, $quot, $dollar and $percnt must be handled by a call to Foswiki::expandStandardEscapes

-- CrawfordCurrie - 22 Dec 2008

Documentation now reads (view in http://trunk.foswiki.org/Tasks/Item549 for the fixed code):

• %FORMFIELD{"Summary" format="Format string. $value expands to the field value, and $name expands to the field name, $title to the field title, $form to the name of the form the field is in. The standard format tokens are also expanded."}%
  • Format string. FORMFIELD plugin does not render documented format variables; missing literal tokens expands to the field value, and Summary expands to the field name, Summary to the field title, ItemTemplate to the name of the form the field is in. The standard format tokens are also expanded.

-- CrawfordCurrie - 22 Dec 2008

Thanks for the fix. However, I looked at your changeset and would like to point out a difference between your change and my suggestion that may not be optimal.

You call expandStandardEscapes on the result string. I carefully expanded escapes before the formfield's value was substituted.

The difference is that any escapes in the form field's value are now expanded. I thought that the form data should be unaltered - its a form, not a program, and I don't like the idea that a user can change program behavior by putting these escapes in a field value. Certainly, a user should not have to escape escapes when filling out a form.

So I think you may want to reconsider how you coded your change...For me, at least, your fix doesn't obey the principle of least astonishment

[I guess I'm supposed to set the state back to 'new' after making this sort of observation.]

• better to set it to "Waiting for Feedback" and set the person to Crawford, which i have now done for you -- WillNorris

-- TimotheLitt - 28 Dec 2008

You are quite right, and the expandStandardEscapes call should be moved up to account for this.

• CrawfordCurrie - 02 Jan 2009