django-tomselect 0.4.0__tar.gz

django-tomselect-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Actionb, Jack Linke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django-tomselect-0.4.0/PKG-INFO

@@ -0,0 +1,353 @@
+Metadata-Version: 2.1
+Name: django-tomselect
+Version: 0.4.0
+Summary: Django autocomplete widgets and views using Tom Select
+Author-email: Jack Linke <jacklinke@gmail.com>, Philip Becker <yummytea1@gmail.com>
+Project-URL: Source, https://github.com/jacklinke/django-tomselect
+Classifier: Framework :: Django
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# Tom Select for Django
+
+Django autocomplete widgets and views using [Tom Select](https://tom-select.js.org/).
+
+This package provides a Django autocomplete widget and view that can be used
+together to provide a user interface for selecting a model instance from a
+database table.
+
+The package is adapted from the fantastic work of 
+[Philip Becker](https://pypi.org/user/actionb/) in 
+[mizdb-tomselect](https://www.pypi.org/project/mizdb-tomselect/), with the goal 
+of a more generalized solution for Django autocompletion.
+
+<!-- TOC -->
+* [Tom Select for Django](#tom-select-for-django)
+  * [Installation](#installation)
+  * [Usage](#usage)
+  * [Widgets](#widgets)
+    * [TomSelectWidget](#tomselectwidget)
+    * [TomSelectTabularWidget](#tomselecttabularwidget)
+      * [Adding more columns](#adding-more-columns-)
+  * [Function & Features](#function--features)
+    * [Searching](#searching)
+    * [Option creation](#option-creation)
+      * [AJAX request](#ajax-request)
+    * [List View link](#list-view-link)
+    * [Chained Dropdown Filtering](#chained-dropdown-filtering)
+  * [Development & Demo](#development--demo)
+<!-- TOC -->
+
+----
+
+## Installation
+
+Install:
+
+```bash
+pip install -U django-tomselect
+```
+
+## Usage
+
+Add to installed apps:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_tomselect"
+]
+```
+
+Configure an endpoint for autocomplete requests:
+
+```python
+# urls.py
+from django.urls import path
+
+from django_tomselect.views import AutocompleteView
+
+urlpatterns = [
+    # ...
+    path("autocomplete/", AutocompleteView.as_view(), name="my_autocomplete_view")
+]
+```
+
+Use the widgets in a form.
+
+```python
+from django import forms
+
+from django_tomselect.widgets import TomSelectWidget, TomSelectTabularWidget
+from .models import City, Person
+
+
+class MyForm(forms.Form):
+    city = forms.ModelChoiceField(
+        City.objects.all(),
+        widget=TomSelectWidget(City, url="my_autocomplete_view"),
+    )
+
+    # Display results in a table, with additional columns for fields
+    # "first_name" and "last_name":
+    person = forms.ModelChoiceField(
+        Person.objects.all(),
+        widget=TomSelectTabularWidget(
+            Person,
+            url="my_autocomplete_view",
+            search_lookups=[
+                "full_name__icontains",
+            ],
+            # for extra columns pass a mapping of {"model_field": "Column Header Label"}
+            extra_columns={"first_name": "First Name", "last_name": "Last Name"},
+            # The column header label for the labelField column
+            label_field_label="Full Name",
+        ),
+    )
+
+``` 
+
+NOTE: Make sure to include [bootstrap](https://getbootstrap.com/docs/5.2/getting-started/download/) somewhere. For example in the template:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Django Tom Select Demo</title>
+    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/js/bootstrap.bundle.min.js" integrity="sha384-kenU1KFdBIe4zVF0s0G1M5b4hcpxyD9F7jL+jjXkk+Q2h455rYXK/7HAuoJl+0I4" crossorigin="anonymous"></script>
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-rbsA2VBKQhggwzxH7pPCaAqO46MgnOM80zW1RWuH61DGLwZJEdK2Kadq2F9CUG65" crossorigin="anonymous">
+    {{ form.media }}
+</head>
+<body>
+<div class="container">
+    <form>
+        {% csrf_token %}
+        {{ form.as_div }}
+        <button type="submit" class="btn btn-success">Save</button>
+    </form>
+</div>
+</body>
+</html>
+```
+
+----
+
+## Widgets
+
+The widgets pass attributes necessary to make autocomplete requests to the
+HTML element via the dataset property. The Tom Select element is then initialized
+from the attributes in the dataset property.
+
+### TomSelectWidget
+
+Base autocomplete widget. The arguments of TomSelectWidget are:
+
+| Argument       | Default value                                                                                                                                   | Description                                                                                    |
+|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
+| model          | **required**                                                                                                                                    | the model class that provides the choices                                                      |
+| url            | `"autocomplete"`                                                                                                                                | URL pattern name of the autocomplete view                                                      |
+| value_field    | `f"{model._meta.pk.name}"`                                                                                                                      | model field that provides the value of an option                                               |
+| label_field    | `getattr(model, "name_field", "name")`                                                                                                          | model field that provides the label of an option                                               |
+| search_lookups | <code>[<br/>&nbsp;&nbsp;&nbsp;&nbsp;f"{self.value_field}__icontains",<br/>&nbsp;&nbsp;&nbsp;&nbsp;f"{self.label_field}__icontains",<br/>]<code> | the list of lookups to use when filtering the results                                          |
+| create_field   |                                                                                                                                                 | model field to create new objects with ([see below](#ajax-request))                            |
+| multiple       | False                                                                                                                                           | if True, allow selecting multiple options                                                      |
+| listview_url   |                                                                                                                                                 | URL name of the list view for this model ([see below](#list-view-link))                        |
+| add_url        |                                                                                                                                                 | URL name of the add view for this model([see below](#option-creation))                         |
+| filter_by      |                                                                                                                                                 | a 2-tuple defining an additional filter ([see below](#filter-against-values-of-another-field)) |
+
+
+### TomSelectTabularWidget
+
+This widget displays the results in tabular form. A table header will be added
+to the dropdown. By default, the table contains two columns: one column for the choice 
+value (commonly the "ID" of the option) and one column for the choice label (the 
+human-readable part of the choice).
+
+![Tabular select preview](./assets/tomselect_tabular.png "Tabular select preview")
+
+TomSelectTabularWidget has the following additional arguments:
+
+| Argument          | Default value                   | Description                                  |
+|-------------------|---------------------------------|----------------------------------------------|
+| extra_columns     |                                 | a mapping for additional columns             |
+| value_field_label | `f"{value_field.title()}"`      | table header for the value column            |
+| label_field_label | `f"{model._meta.verbose_name}"` | table header for the label column            |
+| label_field_label | `f"{model._meta.verbose_name}"` | table header for the label column            |
+| show_value_field  | `False`                         | show the value field column (typically `id`) |
+
+#### Adding more columns 
+
+To add more columns, pass a dictionary mapping field names to column labels as
+`extra_columns` to the widget's arguments.
+
+```python
+from django import forms
+from django_tomselect.widgets import TomSelectTabularWidget
+from .models import Person
+
+
+class MyForm(forms.Form):
+    person = forms.ModelChoiceField(
+        Person.objects.all(),
+        widget=TomSelectTabularWidget(
+            Person,
+            url="my_autocomplete_view",
+            # for extra columns pass a mapping of {"model_field": "Column Header Label"}
+            extra_columns={"first_name": "First Name", "last_name": "Last Name"},
+        ),
+    )
+
+```
+
+The column label is the header label for a given column in the table.  
+
+The attribute name tells Tom Select what value to look up on a result for the column.
+
+**Important**: that means that the result visible to Tom Select must have an attribute
+or property with that name or the column will remain empty. 
+The results for Tom Select are created by the view calling `values()` on the 
+result queryset, so you must make sure that the attribute name is available
+on the view's root queryset as either a model field or as an annotation.
+
+----
+
+## Function & Features
+
+### Searching
+
+The AutocompleteView filters the result queryset against the `search_lookups`
+passed to the widget. The default value for the lookup is `name__icontains`.
+Overwrite the `AutocompleteView.search` method to modify the search process.
+
+```python
+from django_tomselect.views import AutocompleteView
+
+
+class MyAutocompleteView(AutocompleteView):
+    def search(self, queryset, q):
+        # Filter using your own queryset method:
+        return queryset.search(q)
+```
+
+### Option creation
+
+To enable option creation in the dropdown, pass the URL pattern name of the 
+add page of the given model to the widget. This will add an 'Add' button to the
+bottom of the dropdown.
+
+```python
+# urls.py
+from django.urls import path
+from django_tomselect.views import AutocompleteView
+from django_tomselect.widgets import TomSelectWidget
+from .models import City
+from .views import CityAddView
+
+urlpatterns = [
+    # ...
+    path("autocomplete/", AutocompleteView.as_view(), name="my_autocomplete_view"),
+    path("city/add/", CityAddView.as_view(), name="city_add"),
+]
+
+# forms.py
+widget = TomSelectWidget(City, url="my_autocomplete_view", add_url="city_add")
+```
+
+Clicking on that button sends the user to the add page of the model.
+
+#### AJAX request
+
+If `create_field` was also passed to the widget, clicking on the button will
+create a new object using an AJAX POST request to the autocomplete URL. The
+autocomplete view will use the search term that the user put in on the
+`create_field` to create the object:
+
+```python
+class AutocompleteView:
+    
+    def create_object(self, data):
+        """Create a new object with the given data."""
+        return self.model.objects.create(**{self.create_field: data[self.create_field]})
+```
+
+Override the view's `create_object` method to change the creation process.
+
+### List View link
+
+The dropdown will include a link to the list view of the given model if you
+pass in the URL pattern name of the list view.
+
+```python
+# urls.py
+from django.urls import path
+from django_tomselect.views import AutocompleteView
+from django_tomselect.widgets import TomSelectWidget
+from .models import City
+from .views import CityListView
+
+urlpatterns = [
+    # ...
+    path("autocomplete/", AutocompleteView.as_view(), name="my_autocomplete_view"),
+    path("city/list/", CityListView.as_view(), name="city_listview"),
+]
+
+# forms.py
+widget = TomSelectWidget(City, url="my_autocomplete_view", listview_url="city_listview")
+```
+
+### Chained Dropdown Filtering
+
+Use the `filter_by` argument to restrict the available options of one 
+TomSelectWidget to the value selected in another form field. The parameter must 
+be a 2-tuple:  `(name_of_the_other_form_field, django_field_lookup)`
+
+```python
+# models.py
+from django import forms
+from django.db import models
+from django_tomselect.widgets import TomSelectWidget
+
+
+class Person(models.Model):
+    name = models.CharField(max_length=50)
+    city = models.ForeignKey("City", on_delete=models.SET_NULL, blank=True, null=True)
+
+
+class City(models.Model):
+    name = models.CharField(max_length=50)
+    is_capitol = models.BooleanField(default=False)
+
+
+# forms.py
+class PersonsFromCapitolsForm(forms.Form):
+    capitol = forms.ModelChoiceField(queryset=City.objects.filter(is_capitol=True))
+    person = forms.ModelChoiceField(
+        queryset=Person.objects.all(),
+        widget=TomSelectWidget(Person, filter_by=("capitol", "city_id")),
+    )
+```
+
+This will result in the Person result queryset to be filtered against 
+`city_id` for the currently selected `capitol` formfield value.  
+NOTE: When using `filter_by`, the declaring element now **requires** that the 
+other field provides a value, since its choices are dependent on the other 
+field. If the other field does not have a value, the search will not return any 
+results.
+
+----
+
+## Development & Demo
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+make init
+```
+
+Then see the demo for a preview: `python demo/manage.py runserver`
+
+Run tests with `make test` or `make tox`. To install required browsers for playwright: `playwright install`.
+See the makefile for other commands.