Go to file
blag 2ae21035e5
Merge pull request #135 from karolyi/master
Fix when selecting with an MSFList
2024-05-24 12:39:58 -07:00
.github/workflows Removing EOL'd Django 4.1 tests 2024-05-24 19:39:42 +02:00
example Fixing broken patch for selecting with MSFLists 2024-05-24 19:39:42 +02:00
multiselectfield Fixing broken patch for selecting with MSFLists 2024-05-24 19:39:42 +02:00
.coveragerc Structure of the tests 2013-11-26 19:20:19 +01:00
.gitignore Fixing tests 2019-09-25 07:42:08 +02:00
.travis.yml Fix problem in travis with django/python version (#122) 2021-02-14 16:49:14 +01:00
CHANGES.rst Update CHANGES.rst 2024-05-24 19:39:42 +02:00
COPYING.LGPLv3 Support to python 3, improvements in the readme and fix a little detail 2013-09-11 10:49:03 +02:00
MANIFEST.in Windows OS compatibility 2014-04-04 09:46:07 +02:00
multiselect-work.code-workspace Update version 2020-02-20 06:57:53 +01:00
README.rst Update info for release 2019-10-02 06:33:33 +02:00
setup.py Removing stuff that's requested 2024-05-24 19:39:42 +02:00
tox.ini Support django 3 (#103) 2019-12-19 07:20:48 +01: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

.. image:: https://badge.fury.io/py/django-multiselectfield.png
    :target: https://badge.fury.io/py/django-multiselectfield

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.

This egg is inspired by this `snippet <http://djangosnippets.org/snippets/1200/>`_.

Supported Python versions: 2.7, 3.4+

Supported Django versions: 1.4-2.0+


Install with pip

.. code-block:: bash

    $ pip install django-multiselectfield

Configure your models.py

.. code-block:: python

    from multiselectfield import MultiSelectField

    # ...

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

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

    class MyModel(models.Model):

        # .....

        my_field = MultiSelectField(choices=MY_CHOICES)
        my_field2 = MultiSelectField(choices=MY_CHOICES2,

In your settings.py

Only you need it, if you want the translation of django-multiselectfield

.. code-block:: python




Customizing templates

It is possible to customize the HTML of this widget in your form template. To do so, you will need to loop through ``form.{field}.field.choices``. Here is an example that displays the field label underneath/after the checkbox for a ``MultiSelectField`` called ``providers``:

.. code-block:: HTML+Django

    {% for value, text in form.providers.field.choices %}
      <div class="ui slider checkbox">
        <input id="id_providers_{{ forloop.counter0 }}" name="{{ form.providers.name }}" type="checkbox" value="{{ value }}"{% if value in checked_providers %} checked="checked"{% endif %}>
        <label>{{ text }}</label>
    {% endfor %}

Django REST Framework

Django REST Framework comes with a ``MultipleChoiceField`` that works perfectly with this:

.. code-block:: python

    from rest_framework import fields, serializers

    from myapp.models import MY_CHOICES, MY_CHOICES2

    class MyModelSerializer(serializers.HyperlinkedModelSerializer):
        # ...
        my_field = fields.MultipleChoiceField(choices=MY_CHOICES)
        my_field2 = fields.MultipleChoiceField(choices=MY_CHOICES2)
        # ...

Known Bugs and Limitations

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.

   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.

   See `issue #40 <https://github.com/goinnn/django-multiselectfield/issues/40>`_ for discussion about this bug.


You can get the last bleeding edge version of django-multiselectfield by doing a clone
of its git repository:

.. code-block:: bash

    git clone https://github.com/goinnn/django-multiselectfield

Example project

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:

.. code-block:: bash

    python manage.py migrate  # or python manage.py syncdb --noinput
    python manage.py loaddata app_data
    python manage.py runserver