django-multiselectfield/README.rst

118 lines
3.9 KiB
ReStructuredText
Raw Normal View History

2012-09-27 12:08:07 +00:00
django-multiselectfield
=======================
2013-11-26 18:22:24 +00:00
.. image:: https://travis-ci.org/goinnn/django-multiselectfield.png?branch=master
:target: https://travis-ci.org/goinnn/django-multiselectfield
.. image:: https://coveralls.io/repos/goinnn/django-multiselectfield/badge.png?branch=master
:target: https://coveralls.io/r/goinnn/django-multiselectfield
2013-09-11 08:51:10 +00:00
.. image:: https://badge.fury.io/py/django-multiselectfield.png
:target: https://badge.fury.io/py/django-multiselectfield
2016-09-22 20:12:56 +00:00
A new model field and form field. With this you can get a multiple select from a choices. Stores to the database as a CharField of comma-separated values.
2012-09-27 14:03:17 +00:00
2016-09-22 20:12:56 +00:00
This egg is inspired by this `snippet <http://djangosnippets.org/snippets/1200/>`_.
2012-09-27 14:03:17 +00:00
2016-09-23 11:55:08 +00:00
Supported Python versions: 2.6, 2.7, 3.3+
2016-11-28 12:04:00 +00:00
Supported Django versions: 1.4-1.10+
2016-09-23 11:55:08 +00:00
2012-09-27 14:03:17 +00:00
Installation
============
Install with pip
----------------
.. code-block:: bash
$ pip install django-multiselectfield
Configure your models.py
------------------------
2012-09-27 14:03:17 +00:00
2016-09-22 20:12:56 +00:00
.. code-block:: python
2012-09-27 14:03:17 +00:00
from multiselectfield import MultiSelectField
2016-09-22 20:12:56 +00:00
# ...
2013-11-26 18:03:02 +00:00
MY_CHOICES = (('item_key1', 'Item title 1.1'),
('item_key2', 'Item title 1.2'),
('item_key3', 'Item title 1.3'),
('item_key4', 'Item title 1.4'),
('item_key5', 'Item title 1.5'))
2016-09-22 20:12:56 +00:00
2013-11-26 18:03:02 +00:00
MY_CHOICES2 = ((1, 'Item title 2.1'),
(2, 'Item title 2.2'),
(3, 'Item title 2.3'),
(4, 'Item title 2.4'),
(5, 'Item title 2.5'))
2016-09-22 20:12:56 +00:00
2012-09-27 14:03:17 +00:00
class MyModel(models.Model):
2016-09-22 20:12:56 +00:00
# .....
2013-11-26 18:03:02 +00:00
my_field = MultiSelectField(choices=MY_CHOICES)
my_field2 = MultiSelectField(choices=MY_CHOICES2,
max_choices=3,
max_length=3)
2012-09-27 14:03:17 +00:00
In your settings.py
-------------------
Only you need it, if you want the translation of django-multiselectfield
2016-09-22 20:12:56 +00:00
.. code-block:: python
INSTALLED_APPS = (
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.sites',
'django.contrib.admin',
#.....................#
'multiselectfield',
)
2016-09-22 20:12:56 +00:00
Known Bugs and Limitations
==========================
2016-09-23 11:55:08 +00:00
All tests pass on Django 1.4, 1.5, and 1.8+, so if you can, use a modern version of Django. However, if you must use Django 1.6 or 1.7 there are two known issues you will need to be aware of:
1. `Named groups <https://github.com/goinnn/django-multiselectfield/pull/30#issue-52149983>`_ do not render properly in Django 1.6. The workaround is to manually render the field in your form or use a custom widget. If your workaround is suitably generic, please submit a pull request with it.
2. Only in Django 1.6 and 1.7, due to `Django bug #9619 <https://code.djangoproject.com/ticket/9619>`_, passing a MultiSelectField to ``values()`` or ``values_list()`` will return the database representation of the field (a string of comma-separated values). The workaround is to manually call ``.split(',')`` on the result.
2016-09-22 20:12:56 +00:00
2016-09-23 11:55:08 +00:00
The Django bug was introduced in Django 1.6 and is fixed in Django 1.8 and onward, so ``values()`` and ``values_list()`` return a vanilla Python list of values for Django <= 1.5 and Django >= 1.8.
2016-09-22 20:12:56 +00:00
2016-09-23 11:55:08 +00:00
See `issue #40 <https://github.com/goinnn/django-multiselectfield/issues/40>`_ for discussion about this bug.
2016-09-22 20:12:56 +00:00
2012-09-27 14:03:17 +00:00
Development
===========
You can get the last bleeding edge version of django-multiselectfield by doing a clone
2016-09-22 20:12:56 +00:00
of its git repository:
.. code-block:: bash
2012-09-27 14:03:17 +00:00
2016-09-22 20:12:56 +00:00
git clone https://github.com/goinnn/django-multiselectfield
2013-11-30 19:19:05 +00:00
Example project
===============
2016-09-23 11:55:08 +00:00
There is a fully configured example project in the `example directory <https://github.com/goinnn/django-multiselectfield/tree/master/example/>`_. You can run it as usual:
2013-11-30 19:19:05 +00:00
2016-09-22 20:12:56 +00:00
.. code-block:: bash
2013-11-30 19:19:05 +00:00
2016-09-23 11:55:08 +00:00
python manage.py migrate # or python manage.py syncdb --noinput
python manage.py loaddata app_data
2013-11-30 19:19:05 +00:00
python manage.py runserver