Metadata-Version: 1.0
Name: zeam.form.base
Version: 1.2.3
Summary: Grok based form framework
Home-page: http://pypi.python.org/pypi/zeam.form.base
Author: Sylvain Viollon
Author-email: thefunny@gmail.com
License: BSD
Description: ==============
        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.12, 2.13 and Grok 1.4). 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.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
        
Keywords: grok form framework
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
