zeam.form.composed 1.3.3
Composed form support for zeam.form
License: BSD
Keywords: zeam form composed

==================
zeam.form.composed
==================

This package let you defines forms containing other forms in
`zeam.form.base`_.

.. contents::

Example
=======

Here a simple example. Let's define a setting form::

  from zeam.form import composed, base
  from zope.interface import Interface


  class Setting(composed.ComposedForm):
      composed.context(Interface)

      label = u"Settings"


After, a module can add some mail settings on that screen::

  class MailSetting(composed.SubForm):
      composed.context(MyApplication)
      composed.view(Setting)
      composed.order(99)

      label = u"Mail delivery settings"
      ...

And publications of that application could add some publication
settings::

  class PublicationSetting(composed.SubForm):
      composed.context(MyPublications)
      composed.view(Setting)
      composed.order(10)

      label = u"Publication settings"
      ...


Some default templates are included as well, but you can replace like
you will do in `zeam.form.base`_.

API
===

Classes
-------

``ComposedForm``
    This class define a form which able to contain other forms. It
    behave like a ``zeam.form.base`` Form, but does use its fields.
    A usefull method can give you back a given subform :
    ``getSubForm(identifier)``.

``SubForm``
    This class represent a form which is contained inside a
    ``ComposedForm``. This form behave exactly like a
    ``zeam.form.base`` Form to which you add:

    - a method ``available()`` which is called before anything else to
      know if the form shoud still be included in the ``ComposedForm``.

    - a method ``getComposedForm()`` that gives you back the composed
      form in which this form is rendered.

``SubFormGroup``
    This class let you group ``SubForm`` together. They are rendered within
    the group template, and prefixed by the group name. Like a ``SubForm``
    they have an ``available()`` and a ``getComposedForm()`` method. It as
    well have a ``getSubForm(identifier)`` method.

Directives
----------

All those directives comes from Grokcore component. Please refer to
the `Grok documentation <http://grok.zope.org>`_ for more information.

``context``
    Define for which object the form/sub form is available.

``layer``
    Define the skin for which the form/sub form is aviable.

``require``
    Define a permission need to access the form.

``template``
    Define a Grok-like template for the form. After you done that, the
    Grok template will be look up and used. You can't use anymore a
    ``megrok.pagetemplate`` template, unless you set ``template=None``
    again on your form class.

``view``
    On a sub form, define for which form the sub form is available.

``order``
    Let you specify a number to sort your sub form afterwards using
    that setting.

.. _zeam.form.base: http://pypi.python.org/pypi/zeam.form.base

Changelog
=========

1.3.3 (2019/01/15)
------------------

* Updated versions of GTK packages.

1.3.2 (2012/05/02)
------------------

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

1.3.1 (2012/04/27)
------------------

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

1.3 (2011/11/08)
----------------

* Fix various stupid bugs.

* Fix available issue after executing actions.

* Properly support zeam.form.base 1.2 (actions return the sub form on
  which the action have been executed).

* Updates tests.

1.2 (2010/10/19)
----------------

* Add the concept of groups : subforms in a composed one can be grouped
  with them : they act as a composed form to the subform, and a subform
  to the composed form.

* Update default templates to reflect changes in  ``zeam.form.base``.

1.1 (2010/07/16)
----------------

* Default templates now use Chameleon.

* Call ``update`` for all subforms when the ``update`` of the composed
  form is called.

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

* Initial release.