widget referencs

Author: bckohan

doc/source/reference/fields.rst

@@ -9,8 +9,7 @@ Fields
 .. note::
 
    :class:`~django_enum.fields.EnumField` automatically determines the most appropriate database
-   column type based on the :class:`~enum.Enum` subclass it is assigned to. It is not recommended to
-   use the specialized field types listed here directly.
+   column type based on the :class:`~enum.Enum` subclass it is assigned to.
 
 .. automodule:: django_enum.fields
    :members:

doc/source/reference/forms.rst

@@ -2,12 +2,9 @@
 
 .. _forms_ref:
 
-=====
-Forms
-=====
-
-Fields
-------
+===========
+Form Fields
+===========
 
 .. autoclass:: django_enum.forms.ChoiceFieldMixin
    :members:
@@ -24,34 +21,3 @@ Fields
 .. autoclass:: django_enum.forms.EnumMultipleChoiceField
    :members:
    :show-inheritance:
-
-Widgets
--------
-
-.. autoclass:: django_enum.forms.NonStrictSelect
-   :members:
-   :show-inheritance:
-
-.. autoclass:: django_enum.forms.NonStrictSelectMultiple
-   :members:
-   :show-inheritance:
-
-.. autoclass:: django_enum.forms.FlagSelectMultiple
-   :members:
-   :show-inheritance:
-
-.. autoclass:: django_enum.forms.FlagCheckbox
-   :members:
-   :show-inheritance:
-
-.. autoclass:: django_enum.forms.NonStrictFlagSelectMultiple
-   :members:
-   :show-inheritance:
-
-.. autoclass:: django_enum.forms.NonStrictFlagCheckbox
-   :members:
-   :show-inheritance:
-
-.. autoclass:: django_enum.forms.NonStrictRadioSelect
-   :members:
-   :show-inheritance:

doc/source/reference/index.rst

@@ -18,6 +18,7 @@ Reference
    choices
    filters
    forms
+   widgets
    query
    DRF
    urls

doc/source/reference/widgets.rst

@@ -0,0 +1,73 @@
+.. include:: ../refs.rst
+
+.. _widgets_ref:
+
+=======
+Widgets
+=======
+
+The widgets below provide example renderings using these enums:
+
+.. _color_ex:
+.. literalinclude:: ../../../tests/examples/enums/color.py
+    :lines: 5-
+
+.. _permissions_ex:
+.. literalinclude:: ../../../tests/examples/enums/permissions.py
+    :lines: 5-
+
+
+Django's builtin :class:`~django.forms.Select` widget is the default widget used for
+:class:`~django_enum.fields.EnumField` fields. It renders a simple drop down select box.
+For example:
+
+.. code-block:: Python
+
+   class Model(models.Model):
+       color = EnumField(Color, default=Color.RED)
+
+   Model.objects.create()
+
+.. image:: ../widgets/Select.png
+   :alt: Select widget
+
+.. autoclass:: django_enum.forms.NonStrictSelect
+   :members:
+   :show-inheritance:
+
+.. autoclass:: django_enum.forms.NonStrictSelectMultiple
+   :members:
+   :show-inheritance:
+
+.. autoclass:: django_enum.forms.FlagSelectMultiple
+   :members:
+   :show-inheritance:
+
+.. autoclass:: django_enum.forms.FlagCheckbox
+   :members:
+   :show-inheritance:
+
+.. autoclass:: django_enum.forms.NonStrictFlagSelectMultiple
+   :members:
+   :show-inheritance:
+
+.. autoclass:: django_enum.forms.NonStrictFlagCheckbox
+   :members:
+   :show-inheritance:
+
+.. autoclass:: django_enum.forms.NonStrictRadioSelect
+   :members:
+   :show-inheritance:
+
+
+Mixins
+------
+
+.. autoclass:: django_enum.forms.NonStrictMixin
+   :members:
+
+.. autoclass:: django_enum.forms.FlagMixin
+   :members:
+
+.. autoclass:: django_enum.forms.NonStrictFlagMixin
+   :members:

doc/source/widgets/FlagCheckbox.png

@@ -42,6 +42,9 @@
     "EnumChoiceField",
     "EnumMultipleChoiceField",
     "EnumFlagField",
+    "NonStrictMixin",
+    "FlagMixin",
+    "NonStrictFlagMixin",
 ]
 
 
@@ -123,15 +126,42 @@ def render(self, *args, **kwargs):
 
 class NonStrictSelect(NonStrictMixin, Select):
     """
-    This widget renders a select box that includes an option for each value on the
-    enumeration.
+    **This is the default widget used for** :class:`~django_enum.fields.EnumField`
+    **fields that have** ``strict`` **set to** ``False``.
+
+    This widget will render a drop down select field that includes an option for each
+    value on the enumeration, but if the field is set to a value outside of the
+    enumeration it will be included and selected in the drop down:
+
+    For example, using our :ref:`Color <color_ex>` enumeration:
+
+    .. code-block:: python
+
+        class Model(models.Model):
+            color = EnumField(Color, strict=False, max_length=12)
+
+        Model.objects.create(color="YELLOW")
+
+    .. image:: ../widgets/NonStrictSelect.png
     """
 
 
 class NonStrictRadioSelect(NonStrictMixin, RadioSelect):
     """
-    This widget renders a radio select field that includes an option for each value on
-    the enumeration and for any non-value that is set.
+    This widget will render a radio button select field that includes an option for each
+    value on the enumeration, but if the field is set to a value outside of the
+    enumeration it will be included and selected:
+
+    For example, using our :ref:`Color <color_ex>` enumeration:
+
+    .. code-block:: python
+
+        class Model(models.Model):
+            color = EnumField(Color, strict=False, max_length=12)
+
+        Model.objects.create(color="YELLOW")
+
+    .. image:: ../widgets/NonStrictRadioSelect.png
     """
 
 
@@ -148,7 +178,7 @@ def __init__(self, enum: t.Optional[t.Type[Flag]] = None, **kwargs):
 
     def format_value(self, value):
         """
-        Return a list of the flag's values.
+        Return a list of the flag's values, unpacking it if necessary.
         """
         if value is None:
             return []
@@ -174,15 +204,41 @@ def format_value(self, value):
 
 class FlagSelectMultiple(FlagMixin, SelectMultiple):
     """
+    **This is the default widget used for** :class:`~django_enum.fields.FlagField`
+    **fields.**
+
     This widget will render :class:`~enum.IntFlag` types as a multi select field with
-    an option for each flag value.
+    an option for each flag value. Values outside of the enumeration will not be
+    displayed.
+
+    For example, using our :ref:`Permissions <permissions_ex>` enumeration:
+
+    .. code-block:: python
+
+        class Model(models.Model):
+            permissions = EnumField(Permissions)
+
+        Model.objects.create(permissions=Permissions.READ | Permissions.EXECUTE)
+
+    .. image:: ../widgets/FlagSelectMultiple.png
     """
 
 
 class FlagCheckbox(FlagMixin, CheckboxSelectMultiple):
     """
     This widget will render :class:`~enum.IntFlag` types as checkboxes with a checkbox
     for each flag value.
+
+    For example, using our :ref:`Permissions <permissions_ex>` enumeration:
+
+    .. code-block:: python
+
+        class Model(models.Model):
+            permissions = EnumField(Permissions)
+
+        Model.objects.create(permissions=Permissions.READ | Permissions.EXECUTE)
+
+    .. image:: ../widgets/FlagCheckbox.png
     """
 
 
@@ -201,6 +257,17 @@ class NonStrictFlagSelectMultiple(NonStrictFlagMixin, FlagSelectMultiple):
 
     Options for extra bits only appear if they are set. You should pass choices to the
     form field if you want additional options to always appear.
+
+    .. code-block:: python
+
+        class Model(models.Model):
+            permissions = EnumField(Permissions, strict=False)
+
+        Model.objects.create(
+            permissions=Permissions.READ | Permissions.EXECUTE | ( 1 << 4 )
+        )
+
+    .. image:: ../widgets/NonStrictFlagSelectMultiple.png
     """
 
 
@@ -211,6 +278,19 @@ class NonStrictFlagCheckbox(NonStrictFlagMixin, FlagCheckbox):
 
     Checkboxes for extra bits only appear if they are set. You should pass choices to
     the form field if you want additional checkboxes to always appear.
+
+    For example, using our :ref:`Permissions <permissions_ex>` enumeration:
+
+    .. code-block:: python
+
+        class Model(models.Model):
+            permissions = EnumField(Permissions, strict=False)
+
+        Model.objects.create(
+            permissions=Permissions.READ | Permissions.EXECUTE | ( 1 << 4 )
+        )
+
+    .. image:: ../widgets/NonStrictFlagCheckbox.png
     """
 
 

doc/source/widgets/FlagCheckbox_nulls.png

@@ -1,6 +1,15 @@
 import sys
 from django.contrib import admin
-
+from django.forms import ModelForm, Select, RadioSelect
+from django_enum.forms import (
+    NonStrictRadioSelect,
+    FlagSelectMultiple,
+    FlagCheckbox,
+    NonStrictFlagCheckbox,
+    NonStrictFlagSelectMultiple,
+    NonStrictSelect,
+    NonStrictSelectMultiple
+)
 from tests.examples.models import (
     Map,
     BasicExample,
@@ -9,7 +18,12 @@
     StrictExample,
     PropertyExample,
     ChoicesWithProperties,
-    TextChoicesExample
+    TextChoicesExample,
+    WidgetDemoStrict,
+    WidgetDemoNonStrict,
+    WidgetDemoRadiosAndChecks,
+    WidgetDemoRadiosAndChecksNonStrict,
+    WidgetDemoRadiosAndChecksNulls
 )
 
 admin.site.register(Map)
@@ -20,3 +34,77 @@
 admin.site.register(FlagExample)
 admin.site.register(ChoicesWithProperties)
 admin.site.register(TextChoicesExample)
+
+
+class WidgetDemoStrictAdminForm(ModelForm):
+    class Meta:
+        model = WidgetDemoStrict
+        fields = "__all__"
+        widgets = {
+            "color": Select,
+            "permissions": FlagSelectMultiple,
+        }
+
+
+class WidgetDemoStrictAdmin(admin.ModelAdmin):
+    form = WidgetDemoStrictAdminForm
+
+
+admin.site.register(WidgetDemoStrict, WidgetDemoStrictAdmin)
+
+
+class WidgetDemoNonStrictAdminForm(ModelForm):
+    class Meta:
+        model = WidgetDemoNonStrict
+        fields = "__all__"
+        widgets = {
+            "color": NonStrictSelect,
+            "permissions": NonStrictFlagSelectMultiple,
+        }
+
+
+class WidgetDemoNonStrictAdmin(admin.ModelAdmin):
+    form = WidgetDemoNonStrictAdminForm
+
+
+
+admin.site.register(WidgetDemoNonStrict, WidgetDemoNonStrictAdmin)
+
+
+class WidgetDemoRadiosAndChecksAdminForm(ModelForm):
+    class Meta:
+        model = WidgetDemoRadiosAndChecks
+        fields = "__all__"
+        widgets = {
+            "color": RadioSelect,
+            "permissions": FlagCheckbox,
+        }
+
+
+class WidgetDemoRadiosAndChecksAdmin(admin.ModelAdmin):
+    form = WidgetDemoRadiosAndChecksAdminForm
+
+
+class WidgetDemoRadiosAndChecksNullsAdmin(admin.ModelAdmin):
+    form = WidgetDemoRadiosAndChecksAdminForm
+
+
+admin.site.register(WidgetDemoRadiosAndChecks, WidgetDemoRadiosAndChecksAdmin)
+admin.site.register(WidgetDemoRadiosAndChecksNulls, WidgetDemoRadiosAndChecksNullsAdmin)
+
+
+class WidgetDemoRadiosAndChecksNonStrictAdminForm(ModelForm):
+    class Meta:
+        model = WidgetDemoRadiosAndChecksNonStrict
+        fields = "__all__"
+        widgets = {
+            "color": NonStrictRadioSelect,
+            "permissions": NonStrictFlagCheckbox,
+        }
+
+
+class WidgetDemoRadiosAndChecksNonStrictAdmin(admin.ModelAdmin):
+    form = WidgetDemoRadiosAndChecksNonStrictAdminForm
+
+
+admin.site.register(WidgetDemoRadiosAndChecksNonStrict, WidgetDemoRadiosAndChecksNonStrictAdmin)