Feature Proposal: VarFORMFIELD is missing a default parameter option when the field is not instantiated in the topic

Motivation

VarFORMFIELD needs a way to return a default parameter when the field is not instantiated in the topic.

Description and Documentation

Examples

Impact

is there a more sane approach than a third default parameter?

if not, what to call the other other default parameter?

WhatDoesItAffect:

%WHATDOESITAFFECT%

edit

Implementation

-- Contributors: WillNorris - 08 Jun 2009

Discussion

In my opinion the parameter names for the other two default values do not reflect their intention. I would suggest otherdefault for this third param. Or we create new names/aliases: nodef, noinit and novalue.

-- OliverKrueger - 08 Jun 2009

Today there is a default and an alttext

%FORMFIELD{"rubbishname" default="show default" alttext="show alttext"}% gives show alttext

%FORMFIELD{"TopicSummary" default="show default" alttext="show alttext"}% gives VarFORMFIELD is missing a default parameter option when the field is not instantiated in the topic

%FORMFIELD{"PlannedFor" default="show default" alttext="show alttext"}% gives show default

%FORMFIELD{"BugTracking" default="show default" alttext="show alttext"}% gives Tasks.Item1722

What is missing?

The names of the two parameters may not be elegant but too late to change now. They have been there since 2005 or so. But I think we have the right features. I can have one behavior when the field is not defined. And another when the field is blank. All we need to make sure is that the value 0 does not mean the same as blank. And as you can see from above it works as it should.

So the only 3rd thing would be an option which is defined in a form but not yet on the topic because the topic was saved before the new field was added. But do we really need that?

-- KennethLavrsen - 12 Jun 2009

To make it short: FORMFIELD's default parameter is totally fucked up, does not match the docu and in no way consistent with other default params in Foswiki, e.g. URLPARAM.

Common sense is that a value of a variable is not defined if the variable holding it is not declared. In Foswiki we can't define a variable without assigning a value to it at the same time. A default param would then be used to jump in when a variable is not declared (and thus the value is undefined).

Unfortunately, this is not how FORMFIELD's default parameter works. As things are default will only take effect if (a) the named formfield exists and (b) the value of this formfield is the empty string (length zero). This contradicts common sense (and the docu) because a variable holding the empty string is defined: it has got the value empty string.

2004 someone found out that the current semantics of default is not very useful and added alttext which is what default should have been right from the start.

Is it too late to clean up this cruft? Maybe. Maybe some of this can be weeded out by adding a compatibility or deprecation parameter that switches on a legacy macro API. Just an idea.

-- MichaelDaum - 12 Jun 2009

To illustrate what Michael means, I have marked valid expansions with data, expansions that use default or alttext appropriately.

1. No form is attached to the topic, or there is a form attached but the field is not defined
   1. ...and there is no META:FIELD for the field in the topic alttext
   2. ...and there is a META:FIELD for the field
      1. ...and there is a value= in the META:FIELD
         1. ...and the value is non-empty alttext
         2. ...and the value is empty alttext
      2. ...and there is no value= in the META:FIELD (the value is undef) alttext
2. A form is attached, and the field is defined in the form.
   1. ...and there is a value= in the META:FIELD
      1. ...and the value is non-empty data
      2. ...and the value is empty default
   2. ...and there is no value= in the META:FIELD (the value is undef) default

These 'rules' are largely undocumented and are (IMHO) counter-intuitive. However they are unit tested based on the behaviour of the code in Cairo, after I got roasted for trying to make sense of it once before.

BTW default and alttext are documented as:

• default="..." Text shown when no value is defined for the field
• alttext="..." Text shown when field is not found in the form

The problem is really that wording: Text shown when no value is defined for the field. IME the empty string is a valid value.

-- CrawfordCurrie - 12 Jun 2009

Interesting conversation here but I hardly understand anything

Does data means that it is the only correct expansion? What ever correct means...

-- CarloSchulz - 12 Jun 2009

Don't worry too much, this is only relevant to those who care about accurate, consistent and useful specification (geeks).

Yes, data marks the only case where there is actually a valid value to display. The other cases all illustrate conditions where default or alttext are used.

-- CrawfordCurrie - 12 Jun 2009

I still cannot see the problem.

And I find the

• default="..." Text shown when no value is defined for the field
• alttext="..." Text shown when field is not found in the form

perfectly describing to a normal user what they do.

The default="..." is used when you make a wiki application where you want to display a text or value when the user has not put a value in the formfield. An example could be displaying what is in a feature proposal. If the user has not put anything in the TopicSummary field the application shows a default text like "(no title)"

The alttext="..." is used more in the error handling situation and typically used to display some error text like "No such formfield defined".

So I can create something like %FORMFIELD{"TopicSummary" default="(no title)" alttext="no title formfield defined"}%

It is extremely important that the value "0" remains a an actual value.

It is also extremely important that the default value for "default" is the empty string. Otherwise people will run into problems with fields that are empty and should be empty. %FORMFIELD{"Commenttext"}% should return an empty string by default when Commenttext field is either empty or not there at all.

If the code has some deviations from this that I have not noticed it is a bug.

All the special cases where META:FIELD contains garbage I do not worry too much about. Any META:FIELD that is created through normal creation and editing of topics always contain the right attributes. If META:FIELD misses content it is because your own plugins are buggy or you have some other code hacking/creating topics. How the code handles these cases is not important.

I do not think there need to be any different behaviour for all the many causes of a missing META:FIELD. It can be missing because the topic was saved before the field was added to the form. It can be because the form never had the field. It can be the form is not on the topic. It can be because there is no such form at all. The FORMFIELD should only care about the META:FIELD in the topic. Anything else is a mess. And if the META:FIELD is not there the alttext should be displayed.

How the special cases of wrongly formatted META:FIELD is handled I have no opinion about.

-- KennethLavrsen - 13 Jun 2009

VarFORMFIELD needs a way to return a default parameter when the field is not instantiated in the topic. this can occur when a new field has been added to a form when there are existing instantiated forms in topics. sometimes, this can be months or years after the initial form deployment. this seems like a likely scenario that needs to be accomodated, no?

in my case, i was able to simply regenerate my test data topics. so, it was not a big deal to me and it did not stop my progress. i am not asking for this to fix a condition i have, i have worked my way out of it. instead, i thought it would be a good issue to raise to discuss the "general case".

perhaps this issue doesn't occur when using %FORMFIELDS% to render the form values? i don't know; i'm using == itself to generate a custom rendering.

-- WillNorris - 13 Jun 2009

when the field is not instantiated in the topic

That is exactly what alttext does. For what you were doing you could have used alttext.

The only thing alttext does not know today is the difference between when field defined in a form used in a topic is not yet instantiated in the topic and the field does not exist in the form definition and is not in the topic

But why would you need to know this difference? I can only imagine very speculative situations where you would need a value for this case.

And if we suddenly change FORMFIELD so it has to both read the topic AND the form definition topic, then we will face a performance hit that hits each and every time you view a topic with a form. Today the form topic is only used when editing the topic.

I have the feeling that the original proposal comes from the fact that the alttext feature was not understood correctly. For your exact situation, Will, you could have used alttext to define a default value for those topics where the field had not yet been instantiated.

I believe the correct corrective action on this is to document the default and alttext better in VarFORMFIELD. I believe we do have the feature we need but even experienced developers seem to struggle to understand the documentation.

-- KennethLavrsen - 13 Jun 2009

As Kenneth says, the very fact that experienced developers are still confused over the behaviour of these defaults does rather suggest that the 'specification' is just plain wrong. My giess from reading the code is that the author who added alttext did so because they were afraid to change the existing implementation of default, an implementation which was recognisably wrong even back in 2004 (BDFL == Bad Definition, F***ed for Life)

Picking through the discussion here, my conclusion is that the major problem with the current implementation is that it used the default string in place of an "empty value". In other cases where we use the term "default" we mean "if this isn't defined, then use the default". For FORMFIELD, we are saying, "if the value isn't defined, then use alttext. If it is defined, but is defined to be the empty string, then use =default=". Hence the confusion.

There seems to be an acceptance that we need two types of "default" for FORMFIELD, one that reflects the fact that the field isn't defined in the topic, and another that reflects that it is defined, but is empty.

Because of the impact of removing parameters on existing applications, I don't suggest we change the current definitions of default and alttext. Instead I recommend that we deprecate them, and implement and document the following:

undefined="..."	String to use if the field is not defined in the topic (even if it exists in the form)
empty="..."	String to use if the field is defined, but has an empty value ""

-- CrawfordCurrie - 14 Jun 2009

We have used default and alttext for FORMFIELD for many many years now and our topics are full of them everywhere. For people maintaining applications made by others years ago it is important that the default and alttext are still documented. So deprecating means still documented but with the deprecation specified.

And then two new settings whos names are probably as bad as the old. What does empty mean?? Why is empty better than default???

This FORMFIELD macro is extremely simple. It is not like SEARCH with many many options. FORMFIELD has few options. The table that describe them is the easiest thing to overview.

All we have to do is add a little more text in the table to explain more clearly what the two options do. Adding additional two is not going to make things better. On the contrary. It will be worse.

As as try to write better documentation I can see that the example below the table has a severe error in the text. It says alttext="ProjectName field found" which is rubbish. It should have a "NOT" so it says alttext="ProjectName field not found". I bet this is the main cause why people do not understand the feature. The example says the exact opposite of what the feature does.

I think this docu will do it. And if noone screams I will check that in later today. It is for sure better than what we have today and improving the docu for 1.0.6 is not going to prevent further changes later.

FORMFIELD{"fieldname"} -- renders a field in the form attached to some topic

• Syntax: %FORMFIELD{"fieldname"}%
• Supported parameters:

Parameter:	Description:	Default:
"fieldname"	The name of a Data form field	required
topic="..."	Topic where form data is located. May be of the form Web.TopicName	Current topic
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.	"$value"
default="..."	Text shown when a field is defined in the form of a topic, but the field is empty (noone typed anything in the field or deleted the content).	""
alttext="..."	Text shown when field is not found in the form of a topic (even if it exists in the topic that defines the form).	""

• Example: %FORMFIELD{"ProjectName" topic="Projects.SushiProject" default="(no project name given)" alttext="ProjectName field not found in form"}%
• Related: SEARCH

-- KennethLavrsen - 14 Jun 2009

I think we can live with the 2 existing parameters.

For FormFieldListPlugin (that offers more display options than FORMFIELD), I have documented the 2 params as follows:

Parameter	Comment	Default value	Example
alttext	Alternative text if no field is found in the topic form.	none	alttext="--field not found--"
default	Alternative text if no field value is set.	none	default="(Field $name not set)"

-- ArthurClemens - 14 Jun 2009

There remains the issue of distinguishing the case where a form field is defined but has an undef value, and the case where it is defined to be the empty string. Logically alttext should apply to the former and default only to the latter, but that's not how it currently works.

Arthur, while you description is more readable, it still isn't correct. Kenneth, your description is correct, though the English could do with a bit of massaging:

default="..."	Text shown if the field is defined in the topic, but the field value is empty. For example, a text field for which all the content has been deleted.	""
alttext="..."	Text shown if the field is not defined in the topic (even if it is specified in the form definition). For example, this is used when a field exists in the form definition, but the referring topic hasn't been edited since it was added.	""

Making the mods in the doc.

-- CrawfordCurrie - 15 Jun 2009