Merge branch 'update-serverside-datatables-docs' into 'master'

[CHANGE] Update serverside datatables docs See merge request allianceauth/allianceauth!1789
2026-02-03 21:56:20 +01:00 · 2026-01-20 08:22:25 +00:00
parent ee132b6e60 df6a25067d
commit c19f7e6e79
11 changed files with 99 additions and 18 deletions
--- a/allianceauth/framework/datatables.py
+++ b/allianceauth/framework/datatables.py
@@ -115,7 +115,7 @@ class DataTablesView(View):
                    _type = str(c["columnControl"]["search"]["type"])
                    if _type == "text":
                        if _logic == "notEmpty":
-                                except_qs |= Q(**{f'{_c}': ""})
+                            except_qs |= Q(**{f'{_c}': ""})
                        elif len(_sv) > 0:
                            if _logic == "notContains":
                                except_qs |= Q(**{f'{_c}__icontains': _sv})
@@ -123,7 +123,7 @@ class DataTablesView(View):
                                except_qs |= Q(**{f'{_c}': _sv})
                    elif _type == "num":
                        if _logic == "notEmpty":
-                                except_qs |= Q(**{f'{_c}__isnull': False})
+                            except_qs |= Q(**{f'{_c}__isnull': False})
                        elif len(_sv) > 0:
                            if _logic == "notEqual":
                                try:
--- a/allianceauth/framework/static/allianceauth/framework/css/auth-framework.css
+++ b/allianceauth/framework/static/allianceauth/framework/css/auth-framework.css
@@ -179,3 +179,34 @@
        border-left-color: var(--bs-warning);
    }
 }
+
+/* DataTables 2
+------------------------------------------------------------------------------------- */
+@media all {
+    /* DataTables Processing Indicator
+    --------------------------------------------------------------------------------- */
+    div.dt-processing {
+        padding-top: 0.5rem !important;
+    }
+
+    div.dt-processing > div {
+        display: none;
+    }
+
+    svg.aa-datatables-process-indicator {
+        width: 2rem;
+        height: 2rem;
+    }
+
+    /* DataTables Extension: ColumnControl
+    --------------------------------------------------------------------------------- */
+    table.dataTable span.dtcc div.dtcc-search > div select {
+        background-color: var(--bs-body-bg);
+        color: var(--bs-body-color);
+        padding: 0.375rem;
+    }
+
+    table.dataTable .dt-column-header div.dtcc-search-title {
+        display: none;
+    }
+}
--- a/allianceauth/framework/templates/framework/datatables/process-indicator.html
+++ b/allianceauth/framework/templates/framework/datatables/process-indicator.html
@@ -0,0 +1,9 @@
+{% load i18n %}
+
+<svg class="aa-datatables-process-indicator">
+    <use href="#aa-loading-spinner"></use>
+</svg>
+
+<p class="my-1">
+    {% translate "Loading …" %}
+</p>
--- a/allianceauth/static/allianceauth/libs/DataTables/Extensions/ColumnControl/1.2.0/css/columnControl.bootstrap5.min.css
+++ b/allianceauth/static/allianceauth/libs/DataTables/Extensions/ColumnControl/1.2.0/css/columnControl.bootstrap5.min.css
--- a/allianceauth/static/allianceauth/libs/DataTables/Extensions/ColumnControl/1.2.0/js/columnControl.bootstrap5.min.js
+++ b/allianceauth/static/allianceauth/libs/DataTables/Extensions/ColumnControl/1.2.0/js/columnControl.bootstrap5.min.js
--- a/allianceauth/static/allianceauth/libs/DataTables/Extensions/ColumnControl/1.2.0/js/dataTables.columnControl.min.js
+++ b/allianceauth/static/allianceauth/libs/DataTables/Extensions/ColumnControl/1.2.0/js/dataTables.columnControl.min.js
--- a/allianceauth/templates/bundles/datatables-2-columncontrol-css-bs5.html
+++ b/allianceauth/templates/bundles/datatables-2-columncontrol-css-bs5.html
@@ -1,3 +1,5 @@
 {% load sri %}

-{% sri_static "allianceauth/libs/DataTables/Plugins/ColumnControl/1.2.0/css/columnControl.bootstrap5.min.css" %}
+<!-- Start DataTables ColumnControl CSS -->
+{% sri_static "allianceauth/libs/DataTables/Extensions/ColumnControl/1.2.0/css/columnControl.bootstrap5.min.css" %}
+<!-- End DataTables ColumnControl CSS -->
--- a/allianceauth/templates/bundles/datatables-2-columncontrol-js-bs5.html
+++ b/allianceauth/templates/bundles/datatables-2-columncontrol-js-bs5.html
@@ -1,4 +1,6 @@
 {% load sri %}

-{% sri_static "allianceauth/libs/DataTables/Plugins/ColumnControl/1.2.0/js/dataTables.columnControl.min.js" %}
-{% sri_static "allianceauth/libs/DataTables/Plugins/ColumnControl/1.2.0/js/columnControl.bootstrap5.min.js" %}
+<!-- Start DataTables ColumnControl JS -->
+{% sri_static "allianceauth/libs/DataTables/Extensions/ColumnControl/1.2.0/js/dataTables.columnControl.min.js" %}
+{% sri_static "allianceauth/libs/DataTables/Extensions/ColumnControl/1.2.0/js/columnControl.bootstrap5.min.js" %}
+<!-- End DataTables ColumnControl JS -->
--- a/allianceauth/templates/bundles/datatables-2-css-bs5.html
+++ b/allianceauth/templates/bundles/datatables-2-css-bs5.html
@@ -1,3 +1,5 @@
 {% load sri %}

+<!-- Start DataTables CSS -->
 {% sri_static "allianceauth/libs/DataTables/2.3.6/css/dataTables.bootstrap5.min.css" %}
+<!-- End DataTables CSS -->
--- a/allianceauth/templates/bundles/datatables-2-js-bs5.html
+++ b/allianceauth/templates/bundles/datatables-2-js-bs5.html
@@ -1,4 +1,6 @@
 {% load sri %}

+<!-- Start DataTables JS -->
 {% sri_static "allianceauth/libs/DataTables/2.3.6/js/dataTables.min.js" %}
 {% sri_static "allianceauth/libs/DataTables/2.3.6/js/dataTables.bootstrap5.min.js" %}
+<!-- End DataTables JS -->
--- a/docs/development/custom/framework/datatables.md
+++ b/docs/development/custom/framework/datatables.md
@@ -37,10 +37,14 @@ Given the `EveCharacter` Model as our model of choice we would define our stubs

 ```django
 {% extends "allianceauth/base-bs5.html" %}
+
 {% load i18n %}
+{% load aa_i18n %}
+
 {% block page_title %}
    {% translate "App Name" %}
 {% endblock page_title %}
+
 {% block content %}
    <table class="table table-striped w-100" id="table">
        <!-- Normal Header Rows -->
@@ -54,26 +58,54 @@ Given the `EveCharacter` Model as our model of choice we would define our stubs
        </thead>
    </table>
 {% endblock content %}
+
 {% block extra_css %}
-    <link rel="stylesheet" href="https://cdn.datatables.net/2.3.6/css/dataTables.bootstrap5.css" />
-    <link href="https://cdn.datatables.net/columncontrol/1.2.0/css/columnControl.bootstrap5.min.css" rel="stylesheet">
+    {% include "bundles/datatables-2-css-bs5.html" %}
+
+    {% comment %} If you don't use the ColumnControl Extension, remove the next line {% endcomment %}
+    {% include "bundles/datatables-2-columncontrol-css-bs5.html" %}
 {% endblock %}
+
 {% block extra_javascript %}
-    <script src="https://cdn.datatables.net/2.3.6/js/dataTables.js"></script>
-    <script src="https://cdn.datatables.net/2.3.6/js/dataTables.bootstrap5.js"></script>
-    <script src="https://cdn.datatables.net/columncontrol/1.2.0/js/dataTables.columnControl.min.js"></script>
+    {% get_datatables_language_static LANGUAGE_CODE as DT_LANG_PATH %}
+
+    {% include "bundles/datatables-2-js-bs5.html" %}
+
+    {% comment %} If you don't use the ColumnControl Extension, remove the next line {% endcomment %}
+    {% include "bundles/datatables-2-columncontrol-js-bs5.html" %}
+
    <script>
-        $(document).ready(function() {
-            $('#table').DataTable({
-                serverSide: true,
-                ajax: '{% url "appname:table" %}',
+        $(document).ready(() => {
+            // Assuming you have a table with the ID 'table'
+            // A jQuery HTML Element `$('#table')` can also be passed instead of a selector string
+            const dt = new DataTable('#table', {
+                language: {
+                    url: '{{ DT_LANG_PATH }}',
+                    // Important: The value for `language.processing` must be passed
+                    // as a JS template string, not as a normal string. This is to
+                    // allow for Django template rendering inside the processing
+                    // indicator.
+                    processing: `{% include "framework/datatables/process-indicator.html" %}`
+                },
+                layout: { // See: https://datatables.net/reference/option/layout
+                    topStart: 'pageLength',
+                    topEnd: 'search',
+                    bottomStart: 'info',
+                    bottomEnd: 'paging'
+                },
+                ordering: { // See: https://datatables.net/reference/option/ordering
+                    handler: true, // Enable ordering by clicking on column headers
+                    indicators: false, // Disable ordering indicators on column headers (important when ColumnControl is used)
+                },
+                processing: true, // Show processing indicator when loading data
+                serverSide: true, // Enable server-side processing
+                ajax: '{% url "appname:data_table_view" %}',
                columnDefs: [
                    {
                        targets: [0],
                        columnControl: [],
                        sortable: false,
                        searchable: false
-
                    },
                    {
                        targets: [1,2,3],
@@ -92,13 +124,12 @@ Given the `EveCharacter` Model as our model of choice we would define our stubs
                order: [
                    [1, "asc"]
                ],
-                pageLength: 10,
+                pageLength: 10, // Override default page length if desired
                responsive : true
            });
        });
    </script>
 {% endblock extra_javascript %}
-
 ```

 ## Add our Views
@@ -148,11 +179,13 @@ class EveCharacterTable(DataTablesView):
    # if you need to do some prefetch or pre-filtering you can overide this function
    def get_model_qs(self, request: HttpRequest):
        qs = self.model.objects
+
        if not request.user.is_superuser:
            # eg only show unlinked characters to non-superusers
            # just an example
            # filtering here will prevent people searching things that may not be visible to them
            qs = qs.filter(character_ownership__isnull=True)
+
        # maybe some character ownership select related for performance?
        return qs.select_related("character_ownership", "character_ownership__user")

@@ -174,7 +207,7 @@ app_name = 'appname'

 urlpatterns = [
    path("list/", views.EveCharacterTable.as_view(), name='eve_character_table'),
-    path("tables/data_table", views.show_table, name='table')
+    path("tables/data_table", views.show_table, name='data_table_view')
 ]
 ```