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

[CHANGE] Update serverside datatables docs

See merge request allianceauth/allianceauth!1789

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;
+    }
+}

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>

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 -->

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" %}
+<!-- Start DataTables ColumnControl JS -->
-{% sri_static "allianceauth/libs/DataTables/Plugins/ColumnControl/1.2.0/js/columnControl.bootstrap5.min.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 -->

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 -->

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 -->

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" />
+    {% include "bundles/datatables-2-css-bs5.html" %}
-    <link href="https://cdn.datatables.net/columncontrol/1.2.0/css/columnControl.bootstrap5.min.css" rel="stylesheet">
+
+    {% 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>
+    {% get_datatables_language_static LANGUAGE_CODE as DT_LANG_PATH %}
-    <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>
+    {% 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() {
+        $(document).ready(() => {
-            $('#table').DataTable({
+            // Assuming you have a table with the ID 'table'
-                serverSide: true,
+            // A jQuery HTML Element `$('#table')` can also be passed instead of a selector string
-                ajax: '{% url "appname:table" %}',
+            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')
 ]
 ```