[Grok-doc] form tutorial needs z3c.widget which needs unpublished z3c.javascript

[Jean Daniel]

> I think it would be possible to rewrite the tutorial to less pretty
> but working out-of-the-box widget. We'd lose a bit of tutorial content
> as .custom_widget isn't demonstrated, so perhaps we can find another
> widget library to replace z3c.widget. I think thanks to
> z3c.autoinclude we could also reduce some of the stuff talking about
> ZCML.


Hello,

I did not know where to start to make a workable bug report
about z3c.widget not being installable. Also, I was hesitating about
changing radically the article to be consistent with the examples
of the tutorial and requiring to adapt the code accordingly or
change the article incrementally to make it work first.

What this article is about is

- using schema for build forms,
- working with validation,
- and it is about powerful widgets.

I think I can make a smaller article which only presents
schema and validation and leave the widgets out, for now.

Also, depending on the audience we are targeting, either I explain the
zope.schema and zope.interface, or I consider it a prerequisite. I
chose to explain the basic things (in a basic way).


Here is what I had in mind :

Generating forms from schemas
=============================

introduction
------------

.. context

Web forms are a very common way to request input from the user. In a
blog application for example, a form to add an article contains the
title, date and body fields with the 'Ok' button at the bottom, which
submit the details of the article back to the server. Because an
article needs to be written, modified and finally published and read,
the blog application needs three Web pages with few differences: the
page to add, to display and to edit: both the edit and add pages are
forms.

.. what the issue is:  where grok really helps in the area of forms

Given a definition of the article object, Grok simplifies the work of
the developer by generating the three pages. The definition of an
application object is defined in Grok thanks to a **schema**. It is
defined by the developer via the powerful ``zope.schema`` and
``zope.interface`` packages, and these, as the name suggests, are part
of the Zope Toolkit.

Validation of user input is also a hot topic of forms. Grok leverage
the schema's attribute properties to indicate to the user a field
input error like a typo in an email, in a date, etc.

Widgets represent form fields in a way which guides and facilitates
user input. For example, a date field can be represented with a
tooltip calendar widget, an article body can be presented for editing
with a rich text editor widget. Grok can add various widgets to a Web
application.

.. an overview of the article ( overview of the table of content)

Part one introduces schemas manipulation, by hand, on the command
line, and then inside a grok project, viewed through the browser. Part
two introduces the schema's *constraints* and *invariants* which
decide whether the form is correctly filled. Part three describes how
to add of a calendar widget to a form, as well as the addition of the
powerful TinyMCE rich editor widget.

.. prerequisite for the article

To follow this howto, it is easier if you have completed followed the
Grok tutorial.  You need to be familiar with the *buildout*,
*setup.py*, *app.py*.


Schema describes the application objects
----------------------------------------

Let's design the main class of our blog application, the article
interface class. Interfaces are introduced early to simplify future
swap between multiple implementation class of the article
interface. You can think about it this way, interfaces are *what* you
need, while implementation classes of interface are *how* you want
it. Even if I am not planning to develop multiple implementations, it
usually happens, interfaces are a safe development practice and they
does not hurt much now. A schema *is a* zope.interface class and *has*
its attributes specified by *fields* from the zope.schema module::

  from zope import interface, schema

  class IArticle( interface.Interface ):
      name = schema.TextLine(title="Name")
      birth = schema.Date(title="Birth")
      description = schema.Text(title="Description")

The IPerson class attributes are defined with zope.schema
datatypes. There plenty of datatypes available such as Float,
TextLine, Dict, Password, etc. See `this page
<http://wiki.zope.org/zope3/schema.html>`_ for a full list.

 [ ... ]

Constraints and Invariants are expressive validators
----------------------------------------------------

 [ ... ]

Conclusion
-----------

 [ ... ]