Add EncryptedModelAdmin for encrypted fields

Paginator not working yet.

Author: aclark4life

django_mongodb_backend/admin.py

@@ -0,0 +1,32 @@
+from django.contrib import admin
+from django.contrib.admin.views.main import ChangeList
+
+
+class EncryptedPaginator:
+    # TODO: Implement pagination for encrypted data. This paginator
+    # currently returns all results in a single page.
+    def __init__(self, queryset, per_page):
+        self.queryset = queryset
+        self.per_page = per_page
+
+    def page(self, number):
+        results = list(self.queryset)
+        has_next = False
+        return results, has_next
+
+
+class EncryptedChangeList(ChangeList):
+    def get_results(self, request):
+        paginator = EncryptedPaginator(self.queryset, self.list_per_page)
+        self.result_list, _ = paginator.page(self.page_num + 1)
+
+        self.result_count = len(self.result_list)
+        self.full_result_count = self.result_count
+
+        self.can_show_all = True
+        self.multi_page = False
+
+
+class EncryptedModelAdmin(admin.ModelAdmin):
+    def get_changelist(self, request, **kwargs):
+        return EncryptedChangeList

docs/howto/queryable-encryption.rst

@@ -294,5 +294,26 @@ settings:
         },
     }
 
+Configuring the ``EncryptedModelAdmin``
+=======================================
+
+When using the :doc:`the Django admin site <django:ref/contrib/admin/index>`
+with models that have encrypted fields, use the :class:`EncryptedModelAdmin`
+class to ensure that encrypted fields are handled correctly. To do this, inherit
+from :class:`EncryptedModelAdmin` in your admin classes instead of the standard
+:class:`~django.contrib.admin.ModelAdmin`.
+
+.. code-block:: python
+
+    # myapp/admin.py
+    from django.contrib import admin
+    from .models import Patient
+    from django_mongodb_backend.admin import EncryptedModelAdmin
+
+
+    @admin.register(Patient)
+    class PatientAdmin(EncryptedModelAdmin):
+        pass
+
 You are now ready to :doc:`start developing applications
 </topics/queryable-encryption>` with Queryable Encryption!

docs/ref/contrib/admin.rst

@@ -0,0 +1,53 @@
+=====
+Admin
+=====
+
+Django MongoDB Backend supports the Django admin interface. To enable it, ensure
+that you have :ref:`specified the default pk field
+<specifying the-default-pk-field>` for the
+:class:`~django.contrib.admin.apps.AdminConfig` class as described in the
+:doc:`Getting Started </intro/configure>` guide.
+
+``EncryptedModelAdmin``
+=======================
+
+.. class:: EncryptedModelAdmin
+
+    .. versionadded:: 5.2.3
+
+    A :class:`~django.contrib.admin.ModelAdmin` subclass that supports models
+    with encrypted fields. Use this class as a base class for your model's admin
+    class to ensure that encrypted fields are handled correctly in the admin
+    interface.
+
+    Define a model with encrypted fields:
+
+    .. code-block:: python
+
+        # myapp/models.py
+        from django.db import models
+        from django_mongodb_backend.fields import EmbeddedModelField
+
+
+        class Patient(models.Model):
+            patient_name = models.CharField(max_length=255)
+            patient_id = models.BigIntegerField()
+            patient_record = EmbeddedModelField("PatientRecord")
+
+            def __str__(self):
+                return f"{self.patient_name} ({self.patient_id})"
+
+    Register it with the Django admin using the ``EncryptedModelAdmin`` as shown
+    below:
+
+    .. code-block:: python
+
+        # myapp/admin.py
+        from django.contrib import admin
+        from django_mongodb_backend.admin import EncryptedModelAdmin
+        from .models import Patient
+
+
+        @admin.register(Patient)
+        class PatientAdmin(EncryptedModelAdmin):
+            pass

docs/ref/contrib/index.rst

@@ -7,4 +7,5 @@ Notes for Django's :doc:`django:ref/contrib/index` live here.
 .. toctree::
    :maxdepth: 1
 
+   admin
    gis

docs/ref/utils.rst

@@ -49,13 +49,14 @@ following parts can be considered stable.
     But for maximum flexibility, construct :setting:`DATABASES` manually as
     described in :ref:`configuring-databases-setting`.
 
-.. versionadded:: 5.2.3
 
 ``model_has_encrypted_fields()``
 =================================
 
 .. function:: model_has_encrypted_fields(model)
 
+    .. versionadded:: 5.2.3
+
     Returns ``True`` if the given Django model has any fields that use
     encrypted models.