FormEncode
==========

On Intentions And History
-------------------------

I'm the author of FunFormKit_, a form generation and validation
package for Webware_.  I consider FunFormKit (FFK) to be a very
powerful and complete package, with features that few other form
validation packages for Python have (as to other languages, I haven't
researched enough to know).  It supports repeating and compound fields
(which most packages do not), and has a very expressive validation
system.

However, this is not FFK.  In fact, it signals a deprecation of FFK
and does not provide backward compatibility.  Why?

Probably the biggest problem was that FFK didn't support compound
and repeating fields.  Adding them made everything *much* more
difficult -- it was a sort of clever hack (maybe not even clever), and
the result was very hard for anyone else to understand.  Ultimately
hard for me to understand.

Ontop of this was a structure that had too much coupling.  Testing was
difficult.  I only came to like unit testing after FFK had gone
through several revisions (and I won't claim to be an addict or
sufficiently disciplined about unit testing, but at least I'm better
at it now).  FFK was not made with testability in mind.  It's hard to
add later.

Also, I wanted to use pieces of FFK without the entire framework.
Validation without the form generation was the biggest one.  Alternate
kinds of forms also interested me -- making it easier to do highly
granual templating, or non-HTML/HTTP forms.  Alternate data sources,
like SQL or XMLRPC, also seemed important.  All of these were not easy
within the interfaces that FFK used.

So... FormEncode!  FormEncode takes a lot of ideas from FFK, and a lot
of the code is just modified FFK code.  All of it is reviewed and
actively inserted into FormEncode, I'm not transferring anything
wholesale.  

.. _FunFormKit: http://funformkit.sf.net
.. _Webware: http://webware.sf.net

Status
------

The validation in FormEncode is in a state I'm fairly comfortable
with.  The interface is fairly minimal, and the expressiveness is
excellent.  I'm a little worried about repeating fields -- I think
they are an exception where they shouldn't be.

To see the validation, you might look at `Validator` and `Schema`.
`VariableDecode` is also part of it, mapping HTML/HTTP field names to
nested structures (and back again if you like).  `Schema` is
essentially a validator that validates a dictionary of values, both
validating the set and validating each individual field.

The form generation is in flux.  Or should be in more flux than it is
-- I'm stuck.  I'm VERY open to ideas.  Mostly it's a problem of how
best to describe the forms, while also describing validation, but
still making them possible to uncouple.  And expressing other forms
with the same validation.  And HTML fields that have validation
associated with them.  And validators that have default HTML fields.
It's all over the place.

I also want to create validators from object definitions; SQLObject_
classes in particular, of course -- but I don't want the two packages
to be coupled.  I think this fits in with everything else.  Somehow.

.. _SQLObject: http://sqlobject.org

Integration
-----------

FormEncode is not directly integrated with any framework.  It is very
neutral, expecting just a dictionary for input, creating just HTML.

However, some integration beyond that is nice.  An example of
integration with Webware (using servlet components which are also
somewhat experimental) is in `FormComponent`.

To try this example out::

  $ ./AppServer --AppServer.PlugInDirs='["%(WebwarePath)s", "/path/to/Sandbox/ianbicking"]'

Feedback
--------

Bugs?  Sure, but it's alpha, so I'm not really looking for bugs.
Bugs with tests that reveal the bug?  Always!  I'll never turn down a
test.

Ideas?  Absolutely!  I'm looking for ideas.  Use cases.  Low-level
interface suggestions.  Whatever.  I need more ideas!

Contact me at ianb@colorstudy.com

Thanks...

    Ian Bicking