MultiSelectField¶

MultiSelectField provides Multi Selecting features. It internally by default stores in a TextField and the values are seperated by ,.

Parameters

It accepts all the django model parameters. Below are the additional parameters or special behaviour for a parameter.

• seperator

  The default is ,. This value will be used as a delimiter while storing the selected values.

• max_length

  Default is null. If this is set, then varchar(max_length) will be used for storage by default TextField is used for storage.

• choices

  The choices used for storage. This field is optional as the choices can be from an ajax class

• ajax_source

  The key name used while registering inherited admin_kit.ajax.Ajax class. The return of its run method will be used as choices.

• ajax_target

  This will be of the form key_name:target_field. On every change in its input, it hits the inherited admin_kit.ajax.Ajax class mapped to the specified key_name. If target_field is specified then it sets the value of specified model field to api’s return value.

  The selected values will be passed as q[] query list parameter.

  Example

  # ajax.py
  
  import admin_kit
  
  class SelectedGenresAjax(admin_kit.ajax.Ajax):
      response_type = 'text'
  
      def run(self, request):
          query = request.GET.getlist('q[]')
          response = ','.join(query)
          return response
  
  admin_kit.site.register('selected-genres', SelectedGenresAjax)
  

  This ajax class, joins query list q[] values with , and returns it in text format.

  # models.py
  
  from admin_kit.models import MultiSelectField
  
  class Book(models.Model):
      name = models.CharField(max_length=100)
      GENRES = (
          ('thriller', 'thriller'),
          ('sci-fi', 'sci-fi'),
          ('fictional', 'fictional'),
          ('fantasy', 'fantasy'),
          ('philosophy', 'philosophy')
      )
  
      genres = MultiSelectField(verbose_name='Valid Genres', choices=GENRES,
                                ajax_target='selected-genres:selectedValues')
      selectedValues = models.TextField(verbose_name='Selected Values')
  

  Hence for every change in genres field, the selected values will be sent to ajax class mapped to key: selected-genres which is SelectedAjax and its return will be filled to selectedValues field.

  As you can notice the target_field of ajax_target parameter need not be from admin_kit.models module.

• ajax_subscribe

  This parameter is paired with ajax_source parameter and is set to False. If it is True, then this field is linked to every other field with its ajax_source value same as its linked ajax_target value.

  But it wont be linked to fields which have target_field specified in its ajax_target parameter.

  Example

  # ajax.py
  
  class GenresAjax(ajax.Ajax):
      def run(self, request):
          query = request.GET.getlist('q[]')
          response = list(zip(query, query))
          return response
  

  This ajax class zips the selected query and returns it back.

  # models.py
  
  class Book(models.Model):
      ...
      genres = MultiSelectField(verbose_name='Valid Genres', choices=GENRES,
                              ajax_target='genres')
      chosen_fields = MultiSelectField(seperator=',', ajax_source='genres',
                                       ajax_subscribe=True)
  

  Here chosen fields will have choices dynamically filled whenever genres field is modified. And the choices for chosen_fields will be from return of the GenresAjax class.

• kit_config

  This defaults to None. Instead of passing ajax_source, ajax_target and ajax_subscribe seperately, one can specify them in a dictionary and can be passed to this parameter.

  Example

  # models.py
  
  class Book(models.Model):
      ...
      genres = MultiSelectField(verbose_name='Valid Genres',
                                ajax_source='genres', ajax_subscribe=True,
                                ajax_target='selected-genres:selectedValues')
  

  Is equivalent to

  # models.py
  
  class Book(models.Model):
      ...
      kit_config = {
          'ajax-source': 'genres',
          'ajax-subscribe': True,
          'ajax-target': 'selected-genres:selectedValues'
      }
      genres = MultiSelectField(verbose_name='Valid Genres', choices=GENRES,
                                kit_config=kit_config)
  

  Note

  Make sure the key names are hiphen seperated and not underscore seperated.

SelectField¶

SelectField provides Selecting features. It has similar behaviour as MultiSelectField. So below are the valid parameters

Parameters

• max_length
• choices
• ajax_source
• ajax_target
• ajax_subscribe
• kit_config

MultiSelect Form Field¶

MultiSelectField provides Multi Selecting features. It is same as models.MultiSelectField, but is used in Django Admin Forms

Parameters

• seperator

  The default is ,. This value will be used as a delimiter while storing the selected values.

• choices

  The choices used for rendering. This field is optional as the choices can be from an ajax class

• ajax_source

  The key name used while registering inherited admin_kit.ajax.Ajax class. The return of its run method will be used as choices.

• ajax_target

  This will be of the form key_name:target_field. On every change in its input, it hits the inherited admin_kit.ajax.Ajax class mapped to the specified key_name. If target_field is specified then it sets the value of specified model field to api’s return value.

  The selected values will be passed as q[] query list parameter.

• ajax_subscribe

  This parameter is paired with ajax_source parameter and is set to False. If it is True, then this field is linked to every other field with its ajax_source value same as its linked ajax_target value.

  But it wont be linked to fields which have target_field specified in its ajax_target parameter.

• kit_config

  This defaults to None. Instead of passing ajax_source, ajax_target and ajax_subscribe seperately, one can specify them in a dictionary and can be passed to this parameter.

  Example

  # admin.py
  
  ...
  from admin_kit.fields import MultiSelectField
  
  class BookForm(forms.ModelForm):
      model = Book
      selected_fields = MultiSelectField(ajax_source='genres', ajax_subscribe=True)
      fields = ('name', 'genres')
  
   class BookAdmin(nested_admin.NestedStackedInline):
      model = Book
      form = BookForm
  

  is equivalent to

  # admin.py
  
  ...
  from admin_kit.fields import MultiSelectField
  
  class BookForm(forms.ModelForm):
      model = Book
      kit_config = {
              'ajax-source': 'genres',
              'ajax-subscribe': True
      }
      selected_fields = MultiSelectField(kit_config=kit_config)
      fields = ('name', 'genres')
  
  class BookAdmin(nested_admin.NestedStackedInline):
      model = Book
      form = BookForm
  

  Note

  Make sure the key names are hiphen seperated.

Select Form Field¶

SelectField provides Selecting features. It is similar to MultiSelectField, but provides a single value to select.

Parameters

• choices
• ajax_source
• ajax_target
• ajax_subscribe
• kit_config

SelectMultipleWidget¶

MultiSelectField is the widget used for Multi Select. It inherits Django SelectMultiple Widget class.

The widget doesnt take any new parameters. It just adds the initial value of that widget to data-kit-config attribute.

SelectWidget¶

SelectWidget is the widget used for Select. It inherits Django Select Widget class. This widget is similar to MultiSelectField.

Attributes¶

• response_type¶

  The response type of the ajax class. Its defaults to json, where its jsonifies the output python object. It also accepts text where it converts the output to a string and is sent as the response.

• unique¶

  It defaults to False, if its True then the key will be unique to a class. Hence different Ajax classes with the same key can be registered.

Methods¶

• run(self, request)¶

  The main method that will be executed for generating response for an Ajax request. This is method should be overided by the child class.

• format_response(self, output)¶

  This method formats the return value of run method based on response_type attribute. If it is json, then it converts the output to json, else it renders it in text format.

• route(self, request)¶

  This is the core function, that calls run method and then passes the output to format_response method and returns it. This method is executed when the admin_kit site figures out the ajax_class based on the request.

• classmethod generate_key(cls, key)¶

  Generates the key based on the configuration of Ajax Class. If the unique attribute is set , it prepends the key with the slug form of its class name.

  This method is called in the register function for key and ajax_class mapping.

  Example

  # ajax.py
  
  from admin_kit import ajax
  
  class TestAjax(ajax.Ajax):
      ...
  
  class UniqueTestAjax(ajax.Ajax):
      unique = True
      ...
  
  TestAjax.generate_key('key')
  # `key`
  
  UniqueTestAjax.generate_key('key')
  # `unique-test-ajax-key`
  

  To access this Ajax class in models, Its slugged key name has to be used. In the above Example to map to UniqueTestAjax class, unique-test-ajax-key key should be used in models file.

Site Methods¶

• register(key, ajax_class)¶

  key :: str

  This is the key that will be used in models for binding

  ajax_class :: class

  The ajax class that inherits admin_kit.ajax.Ajax

  This method is used to bind an ajax_class to a key.

  Note

  If unique attribute of ajax_class is True, remember to prepend its slugname to the key.