Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

#73 FormEncode documentation doesn't explain Bool() well

open
nobody
None
5
2009-02-19
2009-02-19
Marius Gedminas
No

(This is supposed to be a concrete suggestion and not mere whinery, but I'm not sure my language skills will express that well enough.)

I'm new to Pylons and FormEncode. I spent a couple of hours reading all the available documentation, yet couldn't figure out two things:

- what's the difference between Bool() and StringBool()

- how to declare <input type="submit"> buttons in my form schema so I won't get unknown field errors (without disabling the unknown field safety net altogether)

It was only after reading a lot of source code that I understood how my two problems solve each other: I should declare each submit button as a Bool() field, and use StringBool() for things like yes/no dropdowns (and probably checkboxes? haven't played with those yet).

I suggest the following changes to the FormEncode documentation:

* in both Bool() and StringBool() docstrings mention the existence of the other one, and enumerate which HTML controls should be used with which converter. I *think* Bool() works with <input type="checkbox"> and <input type="submit">, while StringBool() works with <input type="radio"> and <select>.

* in the introduction section about schemas add a submit button to the schema, explicitly declared as a Bool() field, and mention in the text that this is so formencode won't complain when it sees an unknown field in the POST data. Also perhaps mention that this allows you to figure out which one of several submit buttons was pressed.

Discussion