stimulus_rails_datatables 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33857a74b843142081e2c836a7ca6b9ea3478b5de62c641397de780174b3365c
-  data.tar.gz: fc7ceebc44032ec83db84357e9472c981c011f927581d051c5ed75d9de2785a1
+  metadata.gz: 3c608c879de27fc4bd4b8ddead4a52eb5f425194cbdf5ee3fd598ad754057c36
+  data.tar.gz: 47f4a33a22dcfca000ae5a36761c314ca6d286d351fa2522e5b79b1fbedeb5c7
 SHA512:
-  metadata.gz: 496590e1f982a96b81f0c65e4ae6f577f82b9d59bb3a6638e294a3fbeff96d391e92552b1f352316e4864f3c8a70fe4846bf01ae6cd955f046818b111e88d0f7
-  data.tar.gz: 886217d0aab41163e3d282e80c9144ada0f4b025f190753ce95c76fbfb9294ea65791ee1b078f75391b5a0e38b1bef4b4d7d71b4857223969fe20415903cb752
+  metadata.gz: d5f347f96168ea3599e75a8b8ae8dbf14e99f106d05ba44336c3d5886dfafe0c8b6a76da9141b5b025ff5f293a0fa714e3f7d01467d99c998c04f5f53b44b43a
+  data.tar.gz: 1930559a899f34aefb359a093e2859ab33190460616363854472ab50c001f90433acbe6d3527154d58c9a14303b2cac98906ce04a05258922fb5192e6cbdb4c6

data/README.md

@@ -96,7 +96,7 @@ Pass a block to render custom HTML in the column header instead of using `title:
       label: 'name',
       value: 'id',
       placeholder: 'Select Role',
-      set_value: 1 
+      set_value: 1
     }
   ) %>
 
@@ -233,6 +233,40 @@ class UserDatatable < StimulusRailsDatatables::BaseDatatable
 end
 ```
 
+### Additional Data
+
+You can return extra fields alongside the standard DataTables JSON response by defining `additional_data` in your datatable class. This is useful for displaying aggregate stats (e.g. counts, totals) that are scoped to the current filtered result set.
+
+```ruby
+class OrdersDatatable < StimulusRailsDatatables::BaseDatatable
+  def additional_data
+    { unread_orders_count: get_raw_records.where(is_read: false).count }
+  end
+
+  # ...
+end
+```
+
+Any element with a `data-datatable-field` attribute matching a key from `additional_data` will have its text content updated automatically after every draw (page change, sort, filter):
+
+```html
+<span data-datatable-field="unread_orders_count">0</span> unread orders
+```
+
+When you have **multiple datatables on the same page**, scope the element to a specific table using `data-for-datatable`:
+
+```html
+<span data-datatable-field="unread_orders_count" data-for-datatable="orders-table">0</span>
+```
+
+You can also listen for the `datatable:additional-data` event for custom JavaScript handling:
+
+```javascript
+document.addEventListener('datatable:additional-data', (e) => {
+  console.log(e.detail) // { unread_orders_count: 5 }
+})
+```
+
 ### JavaScript API
 
 ```javascript

data/app/assets/javascripts/stimulus_rails_datatables/datatables_controller.js

@@ -127,6 +127,34 @@ export default class extends Controller {
             detail: { table: appDataTable }
           }))
         })
+
+        // Dispatch additional_data returned by the server alongside standard DataTables fields
+        const STANDARD_DT_KEYS = new Set(['draw', 'recordsTotal', 'recordsFiltered', 'data', 'error'])
+        appDataTable.on('xhr', (_e, _settings, json) => {
+          if (!json) return
+          const additionalData = Object.fromEntries(
+            Object.entries(json).filter(([key]) => !STANDARD_DT_KEYS.has(key))
+          )
+          if (Object.keys(additionalData).length === 0) return
+
+          // Dispatch event so consumers can react programmatically
+          this.element.dispatchEvent(new CustomEvent('datatable:additional-data', {
+            bubbles: true,
+            detail: additionalData
+          }))
+
+          // Auto-update elements: <span data-datatable-field="unread_orders_count">
+          // Scope with optional data-for-datatable="<id>" to support multiple tables per page
+          // Single DOM query for all field elements, then group by field name to avoid N queries per key
+          document.querySelectorAll('[data-datatable-field]').forEach(el => {
+            const key = el.dataset.datatableField
+            if (!(key in additionalData)) return
+            const forId = el.dataset.forDatatable
+            if (!forId || forId === datatableId) {
+              el.textContent = additionalData[key]
+            }
+          })
+        })
       }
     }
 

data/lib/stimulus_rails_datatables/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StimulusRailsDatatables
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stimulus_rails_datatables
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Den Meralpis