Z3c-form

------------------

Features
~~~~~~~~

- KGS 3.4 compatibility. This is a real hard thing, because `z3c.form` tests
use `lxml` >= 2.1.1 to check test output, but KGS 3.4 has `lxml`
1.3.6. Therefore we agree on that if tests pass with all package versions
nailed by KGS 3.4 but `lxml` overridden to 2.1.1 then the `z3c.form` package
works with a plain KGS 3.4.

- Removed hard `z3c.ptcompat` and thus `z3c.pt` dependency. If you have
`z3c.ptcompat` on the Python path it will be used.

- Added nested group support. Groups are rendered as fieldsets. Nested
fieldsets are very useful when designing forms.

WARNING: If your group did have an `applyChanges()` (or any added(?)) method
the new one added by this change might not match the signature.

- Added `labelRequired` and `requiredInfo` form attributes. This is useful for
conditional rendering a required info legend in form templates. The
`requiredInfo` label depends by default on a given `labelRequired` message
id and will only return the label if at least one widget field is required.

- Add support for refreshing actions after their execution. This is useful
when button action conditions are changing as a result of action
execution. All you need is to set the `refreshActions` flag of the form to
`True` in your action handler.

- Added support for using sources. Where it was previosly possible to use a
vocabulary it is now also possible to use a source. This works both for
basic and contextual sources.

**IMPORTANT:** The `ChoiceTerms` and `CollectionTerms` in `z3c.form.term`
are now simple functions that query for real `ITerms` adapters for field's
`source` or `value_type` respectively. So if your code inherits the old
`ChoiceTerms` and `CollectionTerms` classes, you'll need to review and adapt
it. See the `z3c.form.term` module and its documentation.

- The new `z3c.form.interfaces.NOT_CHANGED` special value is available to
signal that the current value should be left as is. It's currently handled
in the `z3c.form.form.applyChanges()` function.

- When no file is specified in the file upload widget, instead of overwriting
the value with a missing one, the old data is retained. This is done by
returning the new `NOT_CHANGED` special value from the
`FileUploadDataConvereter`.

- Preliminary support for widgets for the `schema.IObject` field has been
added. However, there is a big caveat, please read the ``object-caveat.txt``
document inside the package.

A new `objectWidgetTemplate` ZCML directive is provided to register widget
templates for specific object field schemas.

- Implemented the `MultiWidget` widget. This widget allows you to use simple
fields like `ITextLine`, `IInt`, `IPassword`, etc. in a `IList` or `ITuple`
sequence.

- Implemented `TextLinesWidget` widget. This widget offers a text area element
and splits lines in sequence items. This is usfull for power user
interfaces. The widget can be used for sequence fields (e.g. `IList`) that
specify a simple value type field (e.g. `ITextLine` or `IInt`).

- Added a new flag `ignoreContext` to the form field, so that one can
individually select which fields should and which ones should not ignore the
context.

- Allow raw request values of sequence widgets to be non-sequence values,
which makes integration with Javascript libraries easier.

- Added support in the file upload widget's testing flavor to specify
'base64'-encoded strings in the hidden text area, so that binary data can be
uploaded as well.

- Allow overriding the `required` widget attribute using `IValue` adapter just
like it's done for `label` and `name` attributes.

- Add the `prompt` attribute of the `SequenceWidget` to the list of adaptable
attributes.

- Added benchmarking suite demonstrating performance gain when using
``z3c.pt``.

- Added support for ``z3c.pt``. Usage is switched on via the "PREFER_Z3C_PT"
environment variable or via ``z3c.ptcompat.config.[enable/diable]()``.

- The `TypeError` message used when a field does not provide `IFormUnicode`
now also contains the type of the field.

- Add support for internationalization of `z3c.form` messages. Added Russian,
French, German and Chinese translations.

- Sphinx documentation for the package can now be created using the new `docs`
script.

- The widget for fields implementing `IChoice` is now looked up by querying
for an adapter for ``(field, field.vocabulary, request)`` so it can be
differentiated according to the type of the source used for the field.

- Move `formErrorsMessage` attribute from `AddForm` and `EditForm` to the
`z3c.form.form.Form` base class as it's very common validation status
message and can be easily reused (especially when translations are
provided).

Refactoring
~~~~~~~~~~~

- Removed compatibility support with Zope 3.3.

- Templates now declare XML namespaces.

- HTML output is now compared using a modified version of the XML-aware output
checker provided by `lxml`.

- Remove unused imports, adjust buildout dependencies in `setup.py`.

- Use the `z3c.ptcompat` template engine compatibility layer.

Fixed Bugs
~~~~~~~~~~

- **IMPORTANT** - The signature of `z3c.form.util.extractFileName` function
changed because of spelling mistake fix in argument name. The
`allowEmtpyPostFix` is now called `allowEmptyPostfix` (note `Empty` instead
of `Emtpy` and `Postfix` instead of `PostFix`).

- **IMPORTANT** - The `z3c.form.interfaces.NOVALUE` special value has been
renamed to `z3c.form.interfaces.NO_VALUE` to follow the common naming
style. The backward-compatibility `NOVALUE` name is still in place, but the
`repr` output of the object has been also changed, thus it may break your
doctests.

- When dealing with `Bytes` fields, we should do a null conversion when going
to its widget value.

- `FieldWidgets` update method were appending keys and values within each
update call. Now the `util.Manager` uses a `UniqueOrderedKeys`
implementation which will ensure that we can't add duplicated manager
keys. The implementation also ensures that we can't override the
`UniqueOrderedKeys` instance with a new list by using a decorator. If this
`UniqueOrderedKeys` implementation doesn't fit for all use cases, we should
probably use a customized `UserList` implementation. Now we can call
``widgets.update()`` more then one time without any side effect.

- `ButtonActions` update where appending keys and values within each update
call. Now we can call ``actions.update()`` more then one time without any
side effect.

- The `CollectionSequenceDataConverter` no longer throws a ``TypeError:
'NoneType' object is not iterable`` when passed the value of a non-required
field (which in the case of a `List` field is `None`).

- The `SequenceDataConverter` and `CollectionSequenceDataConverter` converter
classes now ignore values that are not present in the terms when converting
to a widget value.

- Use ``nocall:`` modifier in `orderedselect_input.pt` to avoid calling list
entry if it is callable.

- `SingleCheckBoxFieldWidget` doesn't repeat the label twice (once in ``<div
class="label">``, and once in the ``<label>`` next to the checkbox).

- Don't cause warnings in Python 2.6.

- `validator.SimpleFieldValidator` is now able to handle
`interfaces.NOT_CHANGED`. This value is set for file uploads when the user
does not choose a file for upload.

------------------

- Feature: Use the ``query()`` method in the widget manager to try extract a
value. This ensures that the lookup is never failing, which is particularly
helpful for dictionary-based data managers, where dictionaries might not
have all keys.

- Feature: Changed the ``get()`` method of the data manager to throw an error
when the data for the field cannot be found. Added ``query()`` method to
data manager that returns a default value, if no value can be found.

- Feature: Deletion of widgets from field widget managers is now possible.

- Feature: Groups now produce detailed `ObjectModifiedEvent` descriptions like
regular edit forms do. (Thanks to Carsten Senger for providing a patch.)

- Feature: The widget manager's ``extract()`` method now supports an optional
``setErrors`` (default value: True) flag that allows one to not set errors
on the widgets and widget manager during data extraction. Use case: You want
to inspect the entered data and handle errors manually.

- Bug: The ``ignoreButtons`` flag of the ``z3c.form.form.extends()`` method
was not honored. (Thanks to Carsten Senger for providing a patch.)

- Bug: Group classes now implement ``IGroup``. This also helps with the
detection of group instantiation. (Thanks to Carsten Senger for providing a
patch.)

- Bug: The list of changes in a group were updated incorrectly, since it was
assumed that groups would modify mutually exclusive interfaces. Instead of
using an overwriting dictionary ``update()`` method, a purely additive merge
is used now. (Thanks to Carsten Senger for providing a patch.)

- Bug: Added a widget for ``IDecimal`` field in testing setup.

- Feature: The ``z3c.form.util`` module has a new function, ``createCSSId()``
method that generates readable ids for use with css selectors from any
unicode string.

- Bug: The ``applyChanges()`` method in group forms did not return a changes
dictionary, but simply a boolean. This is now fixed and the group form
changes are now merged with the main form changes.

- Bug: Display widgets did not set the style attribute if it was
available, even though the input widgets did set the style attribute.

------------------

- Bug: Display Widgets added spaces (due to code indentation) to the displayed
values, which in some cases, like when displaying Python source code, caused
the appearance to be incorrect.

- Bug: Prevent to call ``__len__`` on ``ITerms`` and use ``is None`` for check
for existence. Because ``__len__`` is not a part of the ITerms API and ``not
widget.terms`` will end in calling ``__len__`` on existing terms.

------------------

- Bug: Fixed a bug that prohibited groups from having different contents than
the parent form. Previously, the groups contents were not being properly
updated. Added new documentation on how to use groups to generate
object-based sub-forms. Thanks to Paul Carduner for providing the fix and
documentation.

------------------

- Feature: Implemented ``IDisplayForm`` interface.

- Feature: Added integration tests for form interfaces. Added default class
attribute called ``widgets`` in form class with default value ``None``. This
helps to pass the integration tests. Now, the ``widgets`` attribute can also
be used as a indicator for updated forms.

- Feature: Implemented additional ``createAndAdd`` hook in ``AddForm``. This
allows you to implement create and add in a single method. It also supports
graceful abortion of a create and add process if we do not return the new
object. This means it can also be used as a hook for custom error messages
for errors happen during create and add.

- Feature: Add a hidden widget template for the ``ISelectWidget``.

- Feature: Arrows in the ordered select widget replaced by named entities.

- Feature: Added ``CollectionSequenceDataConverter`` to ``setupFormDefaults``.

- Feature: Templates for the CheckBox widget are now registered in
``checkbox.zcml``.

- Feature: If a value cannot be converted from its unicode representation to a
field value using the field's ``IFromUnicode`` interface, the resulting type
error now shows the field name, if available.

- Bug: ``createId`` could not handle arbitrary unicode input. Thanks to
Andreas Reuleaux for reporting the bug and a patch for it. (Added
descriptive doctests for the function in the process.)

- Bug: Interface invariants where not working when not all fields needed for
computing the invariant are in the submitted form.

- Bug: Ordered select didn't submit selected values.

- Bug: Ordered select lists displayed tokens instead of value,

- Bug: ``SequenceWidget`` displayed tokens instead of value.

------------------

- Feature: Implemented ``ImageButton``, ``ImageAction``, ``ImageWidget``, and
``ImageFieldWidget`` to support imge submit buttons.

- Feature: The ``AttributeField`` data manager now supports adapting
the content to the fields interface when the content doesn't implement
this interface.

- Feature: Implemented single checkbox widget that can be used for boolean
fields. They are not available by default but can be set using the
``widgetFactory`` attribute.

- Bug: More lingual issues have been fixed in the documentation. Thanks to
Martijn Faassen for doing this.

- Bug: When an error occurred during processing of the request the
widget ended up being security proxied and the system started
throwing `TraversalError`-'s trying to access the `label` attribute of
the widget. Declared that the widgets require the `zope.Public`
permission in order to access these attributes.

- Bug: When rendering a widget the ``style`` attribute was not honored. Thanks
to Andreas Reuleaux for reporting.

- Bug: When an error occurred in the sub-form, the status message was not set
correctly. Fixed the code and the incorrect test. Thanks to Markus
Kemmerling for reporting.

- Bug: Several interfaces had the ``self`` argument in the method
signature. Thanks to Markus Kemmerling for reporting.