Go to file
Kumi 7f511ea1af
feat(setup.py): bump version to 0.2.0 for Django
Multiselectfield

This update marks the transition from a pre-release, Django 4 specific
version (0.1.12-django4-1-1) to a more stable release (0.2.0). The
change signifies not just the increment in functionality but also better
compatibility and bug fixes that are relevant to all Django versions,
not just Django 4. This version bump responds to the community feedback
for a more stable and broadly compatible version of the Django
Multiselectfield package.

By moving to a semantically significant versioning, we aim to provide
clearer expectations about the maintenance and stability of the package
to developers. This change encourages wider adoption and more reliable
integration into Django projects.
2024-03-24 16:48:30 +01:00
example Fix problem in travis with django/python version (#122) 2021-02-14 16:49:14 +01:00
multiselectfield Make compatible with Django 4.1 (hopefully) 2022-09-07 15:58:06 +00: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 Fix reStructuredText 2020-02-20 07:12:28 +01: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
README.rst Update info for release 2019-10-02 06:33:33 +02:00
multiselect-work.code-workspace Update version 2020-02-20 06:57:53 +01:00
setup.py feat(setup.py): bump version to 0.2.0 for Django 2024-03-24 16:48:30 +01:00
tox.ini Support django 3 (#103) 2019-12-19 07:20:48 +01:00

README.rst

django-multiselectfield
=======================

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

Installation
============


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,
                                     max_choices=3,
                                     max_length=3)


In your settings.py
-------------------

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

.. code-block:: python

    INSTALLED_APPS = (
        'django.contrib.auth',
        'django.contrib.contenttypes',
        'django.contrib.sessions',
        'django.contrib.sites',
        'django.contrib.admin',

        #.....................#

        'multiselectfield',
    )


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>
      </div>
    {% 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.


Development
===========

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