zeam.form.base 1.4.1
Grok based form framework
License: BSD
Keywords: grok form framework

==============
zeam.form.base
==============

Summary
=======

``zeam.form.base`` is a form framework for Zope. It has common goals
and purposes with ``formlib`` or ``z3c.form`` but tries to:

- define small sane and reusable components : you don't
  need a full flavored form to render and display only few widgets in
  your application,

- be easily customizable without using hundreds of adapters: most
  of settings are set with properties on your form/fields,

- prevent ZCML declarations by using Grok to register the few needed
  adapters (widgets and widgets value extractors),

- always keep the context untouched: the form works on a content
  that can be something else than the context, it can even be a
  dictionnary. That means everywhere in the form, including in
  widgets, and actions, you can either access the context as the real
  context of the form, and have a way to access the content that the
  form is working on. This helps greatly if you have complicated
  widgets working, including when they are embedded in other widgets
  (like in a list or a table),

- let people easily change form templates, by using
  ``megrok.pagetemplate`` by default, selecting which fields goes
  where they want,

- let people define easily their widgets, and use them,

- be able to create complex forms, like composed or table
  forms, where each form can modify the data it needs without having
  to hack-o-refresh other sub-forms: *all* actions are executed before
  any widget compute its value to render,

By default, it is unware of things like Zope-schema. Generating fields
from a Zope-schema would be done with the help of ``zeam.form.ztk``.

It work with Python 2.6, 2.7 (tested in Zope 2.13 and Grok 1.5). Older
versions works for older versions of Zope 2 and Grok.


Example
=======

Let's define a quick example. Actions can be defined standalone::

  from zeam.form.base import Action, SUCCESS

  class MailAction(Action):

     def available(self, form):
         return form.context.haveMailHost()

     def __call__(self, form):
         # Send a mail
         form.status = u"Mail sent"
         return SUCCESS


And included as attributes to the form::

  class MailForm(Form):
     label = u"Send a mail"
     description = u"to people"
     fields = Fields(Field(u'Name'), Field(u'E-mail'), Field(u'Message'))
     actions = Actions(MailAction(u'Send mail'))


(A decoractor can be used on a form method as well if you don't need
lot of code for your action).


For more information
====================

You can refer to the functional and doctest included in the
package. Since it tries to be composed of small components, there is
many way to put them together.

Changelog
=========

1.4.1 (2020-08-25)
------------------

* Fixed 'url' method as it was faulty. Added tests accordingly.


1.4.0 (2020-08-20)
------------------

* Python3.6+ only. Python2 support was dropped.


1.3.2 (2019-01-15)
------------------

* Added the defaultFactory handling (needs testing)

* Updated to newer versions of the GTK packages

* Switch tests to zope.testbrowser.wsgi


1.3.1 (2012/11/19)
------------------

* Improve actions ``htmlAttributes`` to reflect fields API.

* Improve and fix ``constrainValue`` validation on fields.


1.3 (2012/10/12)
----------------

* Fields now support more options. There is a ``constrainValue``
  method that can be used in addition to ``validate`` (to be
  compatible with ``zope.schema`` fields). An option ``interface`` had
  been added as well, and can be used by other zeam.form components to
  group fields.

* Fields can be created with more options given through their
  constructor.

* Fields and widget now support extra ``htmlAttributes``. They can be
  given to the field constructor, and are rendered automatically by
  the widget.

* Actions supports ``htmlAttributes`` too.

* Update translations.

* Add some backward compatiblity helpers.

1.2.3 (2012/09/24)
------------------

* ``grokcore.chameleon`` is able to negociate i18n by himself. Remove
  the ``i18nLanguage`` attribute that was an hack.

* Refactor how the widgets and extractors are created. This is now
  done via the form data, and is customizable.

1.2.2 (2012/05/02)
------------------

* Update to use the latest ``grokcore.component`` and ``grokcore.view``.

1.2.1 (2012/04/27)
------------------

* Improve the sorting support on components (fields, actions, widgets).

* Add a ``delete`` method to the data manager.

* Now use ``grokcore.chameleon`` instead of ``megrok.chameleon``.

* Add the missing ``static`` to a form default_namespace template.

1.2 (2011/11/08)
----------------

* This version no longer support Zope 2 before 2.12.

* And an helper to know if a field is hidden (so you don't display the
  label).

* Support a callable to know if a field is required (the callable
  takes the form as parameter).

* Add the HTML 5 attribute required by default in the widgets. Use
  novalidate attribute on your form tag if you want to disable it.

* Improve error reporting. A widget can now return a collection of
  error (usefull is the widget is composed of more sub-widgets).

* Extend API for ``dataValidator`` and widget ``prepareRequestValue``.

* Add support for CompoundActions (actions implemented by different
  action collections).

* ``updateActions`` now return the form on which the action have been
  executed. This is usefull in case of sub-forms.


1.1 (2011/02/01)
----------------

* ``zeam.form.base`` now uses the latest ``grokcore.view`` template
  grokker.

* Dependencies have been updated for the latest grokcore and megrok
  packages.


1.0 (2010/10/19)
----------------

* Translation have been completed and reviewed in Dutch, French and
  German.

* An infrastructure to write generic validatators on all fields have
  been added (``dataValidators`` on a ``FormData``).

* Field ``getDefaultValue`` and ``defaultValue`` now take a
  parameter, the form itself. It allows you to compute a default value
  that needs the context.

* Some extraction issues have been fixed: a field which is not
  available is no longer extracte and the ``extractData`` method can
  now be called multiple times with different collection of fields.

* Some options have been added to Actions: a ``postOnly`` flag that
  requires the form to be submitted via the `POST` method only, and a
  ``description`` and ``accesskey`` properties. The ``postOnly``
  option is also available at the form level.

* Actions return a status flag for the success or the failure.

* Some helpers have been added to a form: ``haveRequiredFields`` and
  ``htmlId``. Default forms as well have a ``static`` attribute like
  Grok views do.

* Changed the attribute formError to formErrors which now  a list of errors
  instead of a single error. Because it's possible to have more then one
  main error in a form (eg. invariants).

* Changed the formtemplate to display the new formError in an <ul>
  <li> structure instead of the ... tal:replace ... for a single
  error.

* Added the ``sort`` and ``reverse`` methods on the `Collection`
  component. Tests have been added accordingly.

* Provided a `cmp` function to order components in a
  `Collection`. This is now thoroughly tested and demonstrated.


1.0rc2 (2010/07/16)
-------------------

* The marker to allow extraction affect as well processing them redisplaying
  values coming from the request.

* DataManager API is exported by default.

* DecoratedAction can be extended. You can provide your own implementation
  with the ``factory`` parameter of the decorator.


1.0rc1 (2010/07/05)
-------------------

* The `ExtractData` method has been splitted in two, with the
  introduction of the `validateData` method, that allows the form to
  override the global form validation process. This lets the
  fields validation at the very same place, and only involves
  the general form validation process.

* Created a new marker subclass for the form modes. This marker class
  defines a boolean allowing or not the extraction of the affected
  component, while the form is processed. Added tests for it.

* Look for entry points ``zeam.form.components`` before adapting items
  into components in collection. This let you register adapters before
  they are used.


1.0b4 (2010/06/22)
------------------

* Now the 'Errors' class can be used as a logical grouping of 'Error'
  and it stacks, in this case. Added tests to demonstrate and fix the
  behavior.


1.0b3 (2010/06/04)
------------------

* Fixed the way the identifiers are generated. Now, empty prefixes are
  no longer generating malformed ids/names. Added tests to fix that
  behavior.


1.0b2 (2010/05/13)
------------------

* Fix a bug in FormData initialization.

* Add a NO_CHANGE marker.


1.0b1 (2010/05/03)
------------------

* Initial release