[TransWarp] Use cases/design goals/scope for peak.web forms (part 1)

[Phillip J. Eby]

Form Types/Scenarios
====================


Add/View/Edit Forms
-------------------

The common case, representing maybe half the forms in an application.  It 
should be trivial to create these, preferably by adaptation from the 
peak.model class.  Our default decorator for model.Element should 
incorporate a binding that automatically creates or looks up a form (via 
something like 'StdFormFor(Class)'?)  Features in peak.model will probably 
want to carry some "hints" to help default widget selection.

Use of these forms should be so simple that no specific decorator code 
should need to be written to take advantage of them.  In other words, I 
should in principle be able to take something like a UML or MOF model and 
just "start using" it in peak.web, with an auto-generated user interface 
for these basic functions.  The default layout of the form should come from 
a "stylesheet"-like template, e.g.:

<form blah=blah...  pwt:domlet="form:foo">
    ...
    <tr pwt:define="widget">...
    <tr pwt:define="widget:select">...
    <tr pwt:define="field:bar">...

The idea here is that like Roche's original proposal, you would use a 
define block to standardize the layout of a widget, but you would also be 
able to define override patterns for specific kinds of widgets or specific 
fields.  The "stylesheet" would presumably also use the "layout framework" 
so that it would insert the form into a standard page layout for the site/app.

Of course, if I have need of customization of a particular form, I should 
be able to be as specific as I want, without giving up any features I want 
to keep from the main forms framework.


"Method" Forms
--------------

Method forms are forms used to collect data to invoke operations other than 
the standard 'add/edit/view'.  But, they can't be generated automatically 
(at least from code) because Python method signatures don't contain enough 
metadata.  Also, method forms are much more likely to need an 
individually-tailored custom layout, as they are often placed in sidebars 
or boxes surrounding the main body of a page.  But, they should still by 
default be able to use a "stylesheet" and "standard layout".

Typically a "method" form just collects data, with a single submit 
operation that invokes the desired method.


"Wizards" and "Builders"
------------------------

"Wizards" and "Builders" are complex forms that require multiple 
submissions to perform the desired operation.  They may be a multi-page 
"wizard" form series, or perhaps a "builder" or "editor" that manipulates 
displayed data until the user is ready to submit it.  (For example, an 
outline editor with buttons to move items in a listbox up, down, left, and 
right, or a report builder that lets you add and remove columns from a 
listbox and change their order.)

"Wizards" typically have only one submit button, but it must be used more 
than once.  "Builders" typically have multiple submit buttons, which 
perform different functions.  The framework should readily support both 
types of form, ideally by simply subclassing an appropriate base class, and 
defining methods for each submit button.  It should be easy to designate in 
the form's metadata or layout, what buttons correspond to what methods in 
the class.


"Management" UIs
----------------

Efficiency in a web UI often means supporting a variety of functions from a 
single view, to minimize server round-trips.  For example, Zope's 
management interface lets you select items using checkboxes, then select an 
action to perform on multiple items.  Similarly, an invoice entry 
application may wish to support entry or editing of multiple line items at 
once.

Even when dealing with a single object, it can be useful to offer a variety 
of buttons to perform immediate operations.  For example, Yahoo!Groups 
gives a moderator the ability to approve, reject, or delete a post with a 
single button click, and also the option to remove the member from the 
group, and/or ban their e-mail address from posting.

The framework should support display and entry of data for multiple objects 
within a single form, as well as the ability to select multiple objects and 
perform an action upon them.  It should also support duplicating controls 
at the top and bottom of a list of managed items, for convenient access.



"Portal Page" UIs
-----------------

"Portal" applications like "My Yahoo" allow a user to assemble a web page 
from individual component instances.  Such components may contain forms, 
especially when in an "edit" mode.  In such an application, it should be 
possible for an individual component or "portlet" to manage forms in its 
portion of the page, without any conflict with form data intended for 
another "portlet", even if the other "portlet" is another instance of the 
same type and uses fields with the same names.


Stateless Forms
---------------

All of the above functionality must be supported without requiring 
"sessions", "cookies", or other "stateful" processing.  All "state" of a 
form must be contained entirely within a given HTTP request, so that by 
default, the browser "back" button will work normally.  (It really ticks me 
off when a website breaks my "back"!)



Form Processing
===============

Optimistic Edit-lock Support
----------------------------

There should be an easy way to support optimistic edit-locking, by 
including a hidden version ID in a form, so that upon submission it can be 
detected if another user has already changed the target object.  If this 
occurs, the form should be redisplayed, ideally with warnings about the 
changed fields.  (To support this well, the underlying system would need to 
know what fields had been changed and what their original values were, so 
this needs a bit more thought.)


Confirmation and Validation Messages
------------------------------------

Confirmation ("Changes made!") and validation ("Invalid account ID") 
messages should be able to be displayed.  If a validation problem occurs, 
the form should be redisplayed with the user's entries still present - it 
should not be necessary for the user to back up or re-enter their data in 
order to proceed.