softwarefabrica.django.crud 1.0dev-BZR-r88-panta-elasticworld.org-20091111104606-5frfch9m65s5r595

.. _topics-overview:

===========================
Softwarefabrica Django CRUD
===========================

.. admonition:: About this document

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

.. contents::
:depth: 3

See also the `documentation index`_.

.. _`documentation index`: index.html

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

This library provides flexible and advanced CRUD generic views for applications
developed with the `Django`_ web framework.

By default the generic views make use of the advanced form classes made
available through `softwarefabrica.django.forms`_, thus automatically using
the optional template-based form rendering, the advanced widgets for date,
time, foreign-key and many-to-many fields, etc.
However it's easy to switch back to `Django`_ default forms and widgets if
desired.

Generic views are a backward-compatible drop-in replacement for those offered by
`Django`_, it's just a matter of importing them from
`softwarefabrica.django.crud.crud` instead of from `django.views.generic`.

In addition, a more flexible set of **Object Oriented views** is available.
Just subclass them as you like, instantiate them and put the instances inside
your URLconf, as if they were regular function views.
In the majority of cases you won't even need to subclass them, since you can go
a long way just by passing the proper parameters to the constructor.

In fact, Object oriented views are so powerful and flexible that plain
functional views are actually instances. They are implemented by the library in
this way:

::

create_object = CreateObjectView()
update_object = UpdateObjectView()
delete_object = DeleteObjectView()
object_detail = DetailObjectView()
object_list = ListObjectView()

.. _`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

Feedback
--------

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.forms`_, 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

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-crud

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-crud

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-crud
.. _`LaunchPad`: http://launchpad.net
.. _`Bazaar`: http://bazaar-vcs.org/
.. _`online`: http://bazaar.launchpad.net/~softwarefabrica/sf-django-crud/trunk/changes
.. _`Softwarefabrica`: https://edge.launchpad.net/softwarefabrica
.. _`team`: https://launchpad.net/~softwarefabrica
.. _`bugs`: https://bugs.launchpad.net/sf-django-crud
.. _`enhancements`: https://bugs.launchpad.net/sf-django-crud


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
-------

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

* [BIG CHANGE]: view call state is now encapsulated in a ViewCall
instance. This should make all views perfectly thread-safe (and
cleaner).

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

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

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

* crud.py: added request, request full path, absolute URI, GET, POST
and query string to default context for generic views.

2009-04-14 Marco Pantaleoni <panta@elasticworld.org>

* crud.py: added a compiled template caching mechanism to OO views.

2009-03-27 panta <panta@localhost>

* crud.py: added a reasonable post_delete_redirect support to
DeleteObjectView.

2009-03-16 panta <panta@localhost>

* crud.py: added basic auth/perm checking to crud OO views.

2009-02-21 panta <panta@localhost>

* crud.py: fixed a bug in POPUP_VARIABLE (``_popup``) handling.

2009-01-25 panta <panta@localhost>

* crud.py: renamed ``append_to_context`` to ``populate_context``.

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

* crud.py: added class/instance defaults for view parameters.

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

* crud.py: added ``pre_call()`` method.

2009-01-18 Marco Pantaleoni <panta@elasticworld.org>

* crud.py: made ``<app_label>/<model_name>_edit.html`` and its variations
the default template name for create/update generic views. The old
``_form.html`` versions are still used, but as a last resort.

* crud.py: added support for softwarefabrica.django.common generic
templates to generic views.

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

* version.py: modernized.

* crud.py (GenericView): added ``instance_save_args()`` to let
customization of the instance save() arguments in derived views.

* crud.py (GenericView): added pre_ and post_ methods to save_instance(),
delete_instance(). Added ``request`` parameter to save_form(),
save_instance() and delete_instance().

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

* crud.py (View.append_to_context): fixed return address bug.

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

* added extensive documentation.

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

* bug fixes.

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

* softwarefabrica/django/crud/crud.py: integrated ForeignKey and
ManyToManyField popup handling.

* Turned into a standalone setuptools distribution
('softwarefabrica.django.crud').

2008-10-29 Marco Pantaleoni <panta@elasticworld.org>

* crud.py: added - Object-Oriented generic views and respective
functional support adapters. Also present classes that add
'fieldorder' support to ModelForms and templated forms.