softwarefabrica.django.forms 0.9dev-BZR-r43-panta-elasticworld.org-20100224162511-0bctvwyi62hpopdb

.. _topics-overview:

============================
Softwarefabrica Django Forms
============================

.. admonition:: About this document

This document provides an overview of what Softwarefabrica Django Forms is.

.. contents::
:depth: 3

See also the `documentation index`_.

.. _`documentation index`: index.html

What is this?
=============

This is a forms library for `Django`_ projects, which aims at providing increased
functionality and flexibility to the standard `forms library`_ (aka `newforms`).

Your help and feedback is precious. Suggestions and contributions are very much
appreciated. See below on how you can contribute.

If you want to actively collaborate and provide code, documentation, tests or
bug fixes, please feel free to create a new Bazaar branch in Launchpad, and tell
us about it! See the collaboration_ section for more information.

And don't forget to check also our other `Django`_ applications,
`softwarefabrica.django.utils`_, `softwarefabrica.django.crud`_, and
`softwarefabrica.django.wiki`_.

.. _`Django`: http://www.djangoproject.com
.. _`softwarefabrica.django.utils`: http://pypi.python.org/pypi/softwarefabrica.django.utils
.. _`softwarefabrica.django.forms`: http://pypi.python.org/pypi/softwarefabrica.django.forms
.. _`softwarefabrica.django.crud`: http://pypi.python.org/pypi/softwarefabrica.django.crud
.. _`softwarefabrica.django.wiki`: http://pypi.python.org/pypi/softwarefabrica.django.wiki
.. _`sflib`: http://pypi.python.org/pypi/sflib

Feature overview
----------------

- a compatible replacement for the standard ``Form`` class, supporting **templated** form output
- a compatible replacement for the standard ``ModelForm`` class, supporting extended features, like **field ordering**, **advanced widgets**, **templated output**
- a compatible replacement for ``modelform_factory``, which uses the extended ``ModelForm``
- a set of extended fields and widgets:
- compatible replacements for ``DateField`` and ``DateTimeField`` and the associated widgets, using a nice **popup Javascript calendar**
- a new ``DateRangeField``
- compatible replacements for ``ModelChoiceField`` and ``ModelMultipleChoiceField`` using a **popup interface** for selecting the related instance/instances

.. _`Django`: http://www.djangoproject.com
.. _`forms library`: http://docs.djangoproject.com/en/dev/topics/forms/

Pre-requisites and installation
===============================

See the `installation guide document`_.

.. _`installation guide document`: install.html

.. _collaboration:

How can I contribute?
=====================

As said, your help is precious. We'll warmly appreciate any help you'll want to
give. Just using this library is a reward for us, but if you want to become more
actively involved, you are welcome!

The project has a `development home page`_ at `LaunchPad`_:

https://launchpad.net/sf-django-forms

There you can file `bugs`_, suggest `enhancements`_, follow development or ask
to become an active `team`_ member.

You can checkout the development branch using `Bazaar`_:

::

bzr branch lp:sf-django-forms

We'll appreciate very much if you'll want to contribute back any changes. Just
register your branch with `LaunchPad`_ and tell us!

Source code can also be browsed `online`_.

.. _`development home page`: https://launchpad.net/sf-django-forms
.. _`LaunchPad`: http://launchpad.net
.. _`Bazaar`: http://bazaar-vcs.org/
.. _`online`: http://bazaar.launchpad.net/~softwarefabrica/sf-django-forms/trunk/changes
.. _`Softwarefabrica`: https://edge.launchpad.net/softwarefabrica
.. _`team`: https://launchpad.net/~softwarefabrica
.. _`bugs`: https://bugs.launchpad.net/sf-django-forms
.. _`enhancements`: https://bugs.launchpad.net/sf-django-forms


Contacts
========

It's possible to contact the author by e-mail at the following addresses:

m.pantaleoni at softwarefabrica.org

panta at elasticworld.org

marco.pantaleoni at gmail.com


LICENSE
=======

This software is covered by the GNU General Public License version 2.
If you want to use this software in a closed source application, you
need to buy a commercial license from the author.

This open source version is:

Copyright (C) 2007-2008 Marco Pantaleoni. All rights reserved.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2 as
published by the Free Software Foundation.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.


CHANGES
-------

2010-02-24 Marco Pantaleoni <panta@elasticworld.org>

* added SelectCascadeField and SelectCascadePopupField fields
(and the corresponding widgets), which implement cascaded-update
for "slave" select fields.

* refactored widgets to use a common WidgetHelper class for
template-based rendering.

2009-11-10 Marco Pantaleoni <panta@elasticworld.org>

* added html IDs to form rows (with support in the form classes)

2009-10-26 Marco Pantaleoni <panta@elasticworld.org>

* added 'null' and 'include_blank' kwargs to
FormBuilder.FormBuildField().

2009-10-21 Marco Pantaleoni <panta@elasticworld.org>

* integrated sflib.finddata.find_package_data() in setup.py

2009-05-15 Marco Pantaleoni <panta@elasticworld.org>

* softwarefabrica/django/forms/extended.py: added ``BaseForm`` and made
``Form`` its descendant (instead of from forms.Form).
Added FormBuilder.

2009-03-30 Marco Pantaleoni <panta@elasticworld.org>

* softwarefabrica/django/forms/templates/forms/field.html: fixed error
display in fields template for templated forms.

2009-03-29 Marco Pantaleoni <panta@elasticworld.org>

* softwarefabrica/django/forms/extended.py: global_errors is computed only
for bound forms (to avoid a spurious call to is_valid()).

2009-03-20 Marco Pantaleoni <panta@elasticworld.org>

* softwarefabrica/django/forms/extended.py: handled and passed to template
also non-field errors.

2009-03-17 Marco Pantaleoni <panta@elasticworld.org>

* softwarefabrica/django/forms/extended.py fields.py widgets.py: implemented
workaround for Django bug #9473 involing NullBooleanFields in FormWizard
or FormPreview.

2009-03-15 Marco Pantaleoni <panta@elasticworld.org>

* softwarefabrica/django/forms/extended.py: handled case where Meta.fields
is present but None.

2009-03-11 Marco Pantaleoni <panta@elasticworld.org>

* softwarefabrica/django/forms/templates/forms/form.html
softwarefabrica/django/forms/templates/forms/hiddenfield.html: added
hidden fields handling.

* softwarefabrica/django/forms/extended.py: if Meta.fields is specified
in ModelForm, it's also used for the field ordering (by default).

2008-12-19 Marco Pantaleoni <panta@elasticworld.org>

* docs/install.txt: improved installation instructions.

* docs/: fixed some typos.

2008-12-18 Marco Pantaleoni <panta@elasticworld.org>

* fixes to setup.py, .bzrignore and README.txt

* added extensive documentation.

2008-12-16 Marco Pantaleoni <panta@elasticworld.org>

* softwarefabrica/django/forms/fields.py widgets.py: fixed small
bugs in DateField, DateTimeField, DateWidget, DateTimeWidget.

* softwarefabrica/django/forms/extended.py
(extended_formfield_cb): 'required' is forced into fields kwargs,
because in some cases it's not honoured.

2008-12-01 Marco Pantaleoni <panta@elasticworld.org>

* bug fixes.

2008-11-27 Marco Pantaleoni <panta@elasticworld.org>

* Added RelatedItemField, SelectPopupField,
SelectMultiplePopupField fields and corresponding widgets
(RelatedItemWidget, SelectPopupWidget, SelectMultiplePopupWidget
widgets).

2008-11-25 Marco Pantaleoni <panta@elasticworld.org>

* Added extended fields and widgets. Modified form classes to use
new widgets.

* Fixes, added regression tests.

* Created.