Metadata-Version: 1.2
Name: django-dynamic-form-fields
Version: 0.3.2
Summary: Dynamically update choice fields based on dependent fields in django
Home-page: https://gitlab.com/dannosaur/django-dynamic-form-fields
Author: dannosaur
Author-email: me@dannosaur.com
License: UNKNOWN
Description: ==========================
        django-dynamic-form-fields
        ==========================
        
        -----
        Usage
        -----
        
        * ``pip install django-dynamic-form-fields``
        * Add ``dynamic_fields`` to ``INSTALLED_APPS``
        * Add to your form as a widget:
        
        .. code-block:: python
        
          from typing import Type
          from dynamic_fields.fields import DynamicChoicesWidget
        
          from myapp.models import MyModel, Item
        
          def get_item_choices(model: Type[Item], value: int):
              choices = []
        
              item = model.objects.get(id=value)
        
              for thing in item.things:
                  # do something with item
                  choices.append({
                      'value': thing.id,
                      'label': thing.name,
                 })
        
              return choices
        
        
          class MyForm(forms.ModelForm):
              class Meta:
                  model = MyModel
                  fields = ('item', 'dependent_item')
                  widgets = {
                      'dependent_item': DynamicChoicesWidget(
                          depends_field='item',
                          model=Item,
                          callback=get_item_choices,
                          no_value_disable=True,
                          include_empty_choice=True,
                          empty_choice_label="Please choose an option",
                      )
                  }
        
        * Ensure that form media is included with the rest of your view's media
        
        ------------
        Requirements
        ------------
        
        * Django 1.11-2.2
        * Python 3.5+ (built/tested with 3.6.2)
        * jQuery (built/tested with 1.12.4)
        
        -----------------
        How does it work?
        -----------------
        
        A view is injected into the project's urlpatterns which is the handler
        for the ajax callback when the dependent field changes. When the
        DynamicChoicesWidget template is rendered, it serializes the various
        provided values into Python dotted strings to send to the template.
        It uses HTML5 data attributes in the markup to pass these values to
        the Javascript in order to send to the view to tell it what to do next.
        
        The model is serialized into ``app.model``, and the ``callback`` is
        serialized into the full dotted path to the method within your code,
        e.g; ``app.form.my_form.get_choices``. When the dependent field's value
        is changed, the ajax calls the view with the relevant information
        from above, then this goes and imports the path, grabs the model
        class for what was provided from django's model loader, then calls
        your method with the class itself, and the value provided by the
        dependent field. The output of the callback method is serialized
        back into JSON, returned to the Javascript making the call, which
        iterates over the options and resets the select box's options to
        those provided.
        
        These can be chained (theoretically) for as many fields as required.
        It should also (though untested) work with multiple select boxes.
        
        ----------
        Change Log
        ----------
        
        0.3.2
        -----
        
        * No changes.
        
        0.3.1
        -----
        
        * Changing formatting of documentation since PyPI doesn't like bog-standard markdown
          these days.
        
        0.3.0
        -----
        
        * Bump allowed django to 2.2+
        
        * Fixed issue found in django 2.2 where the choices JS was being called twice,
          causing multiple loads and the selected value to not persist across page reloads.
        
        0.1.0/0.2.0
        -----------
        * Initial version
Platform: UNKNOWN
Requires-Python: >=3.5
