Type converter "list" is undocumented

[jugmac00]

"list" is not listed at
https://zope.readthedocs.io/en/latest/zdgbook/ObjectPublishing.html#argument-conversion

For example you can use list for a select element when multiple values are allowed.

<select name="colors:list" multiple="multiple">

The list converter is used a couple of times in the document, also in the caveats section, but it does not show up in the argument conversion section.

I stumpled upon this as I debugged strange behaviour in my company's app when a search function sometimes returned wrong results.

Turned out Zope returns

• a string, when one element is selected
• a list, when multiple elements are selected
  for a select field, even though the "multiple" attribute was set.

I prevented this by using the list converter.

[ghiodor]

it's documented here: https://zope.readthedocs.io/en/latest/zopebook/ScriptingZope.html#passing-parameters-to-scripts

[d-maurer]

@jugmac00
I am responsible for this: formerly, ZPublisher has named all its request parameter processing directives "type converters", even though there are quite different directive kinds. I have changed the naming (partly in preparation of #648): what formerly was named "type converter" is now called "directive"; there are different kinds of directives, among them "converter"s and "aggregator"s. A "converter" operates on a single request parameter and processes its value; an "aggregator" (logically) operates on multiple request parameters and aggregates them into a single "request variable". If you read section 4.2.15.2 of "https://zope.readthedocs.io/en/latest/zdgbook/ObjectPublishing.html", you will find that list is documented as an aggregator.

list is a bit special. Logically, it is an aggregator as it operates on several request parameters and combines them into a single request variable with a list value. However, because this is the default if there are several parameters with the same name, you usually use it explicitly only as a converter (when there is a single parameter and you want nevertheless a list value for the corresponding request variable). Nevertheless, I feel that list is better classified as "aggregator".

Note, that the implementation has always made the distinction between "converter" and "aggregator": the converters are implemented by the module ZPublisher.Converters (also used by OFS.PropertyManager), aggregators are implemented by the method ZPublisher.HTTPRequest.HTTPRequest.processInputs and list is implemented there. Thus, my documentation change brings the documentation more in line with the implementation. This will further improve when #648 is merged.

[jugmac00]

@ghiodor Thank you - I did not think of the Zope book when looking for this info, as I recalled it was in the Zope Developer's book.

@d-maurer Thanks Dieter! This makes a lot of sense.

P.S.: Huh, I even was a reviewer for the pull request which introduced these changes. #640