stimulus_rails_datatables 0.3.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d508095bbb7cd25e12447b92081260fa8fa373f139be6b065c5eb6f17b3118af
-  data.tar.gz: 9ae1b95a92a6898b2d2b6c55310f06dd7b8ca58902fb55d8f378d1a8605cf5ec
+  metadata.gz: 3c608c879de27fc4bd4b8ddead4a52eb5f425194cbdf5ee3fd598ad754057c36
+  data.tar.gz: 47f4a33a22dcfca000ae5a36761c314ca6d286d351fa2522e5b79b1fbedeb5c7
 SHA512:
-  metadata.gz: fe105aa5f8bc6b0ffcc8bda21fe78c070d75c09b17a211d7e05a217a81ffcf680051e7cd2e5778f864d6735c191a63897ed25b2418e51e7fc9fea3fc14ece080
-  data.tar.gz: c87088b4327210d783377c05291fcf5194f8ae0fcc523408f99d2e678b820fd2ca3c3d465879e9f423d782df255914ef2f6c5bc37f13e640e5430631d301f19f
+  metadata.gz: d5f347f96168ea3599e75a8b8ae8dbf14e99f106d05ba44336c3d5886dfafe0c8b6a76da9141b5b025ff5f293a0fa714e3f7d01467d99c998c04f5f53b44b43a
+  data.tar.gz: 1930559a899f34aefb359a093e2859ab33190460616363854472ab50c001f90433acbe6d3527154d58c9a14303b2cac98906ce04a05258922fb5192e6cbdb4c6

data/README.md

@@ -63,6 +63,20 @@ import 'datatables_config'
 <% end %>
 ```
 
+#### Custom Header Content
+
+Pass a block to render custom HTML in the column header instead of using `title:`.
+
+```ruby
+<%= datatable_for 'users-table', source: users_path do |dt| %>
+  <% dt.column :name, title: 'Name' %>
+
+  <% dt.column class: 'text-center' do %>
+    <div>My Custom Div</div>
+  <% end %>
+<% end %>
+```
+
 #### With Filters
 
 ```ruby
@@ -82,7 +96,7 @@ import 'datatables_config'
       label: 'name',
       value: 'id',
       placeholder: 'Select Role',
-      set_value: 1 
+      set_value: 1
     }
   ) %>
 
@@ -219,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/app/helpers/stimulus_rails_datatables/datatable_helper.rb

@@ -2,7 +2,7 @@
 
 module StimulusRailsDatatables
   module DatatableHelper
-    def datatable_for(id, source:, order: [[2, 'desc']], **options)
+    def datatable_for(id, source:, order: [[2, 'desc']], **options, &block)
       classes = options.fetch(:classes, 'align-middle table w-100')
       searching = options.fetch(:searching, true)
       length_change = options.fetch(:length_change, true)
@@ -10,14 +10,15 @@ module StimulusRailsDatatables
       responsive = options.fetch(:responsive, true)
       columns = []
 
-      yield DatatableBuilder.new(columns)
+      capture(DatatableBuilder.new(self, columns), &block)
+      datatable_columns = columns.map { |column| column.reject { |key, _| key == :header_content } }
 
       data = {
         controller: 'datatable',
         datatable_id_value: id,
         datatable_source_value: source,
         datatable_order_value: order.to_json,
-        datatable_columns_value: columns.to_json,
+        datatable_columns_value: datatable_columns.to_json,
         datatable_searching_value: searching,
         datatable_length_change_value: length_change,
         datatable_state_save_value: state_save,
@@ -29,7 +30,9 @@ module StimulusRailsDatatables
           content_tag(:thead, class: 'table-light align-middle') do
             content_tag(:tr) do
               safe_join(columns.map do |col|
-                content_tag(:th, col[:title] || col[:data].to_s.titleize, class: col[:class])
+                header = col[:header_content] || col[:title] || col[:data].to_s.titleize
+
+                content_tag(:th, header, class: col[:class])
               end)
             end
           end
@@ -40,12 +43,15 @@ module StimulusRailsDatatables
     class DatatableBuilder
       attr_reader :columns
 
-      def initialize(columns)
+      def initialize(view, columns)
+        @view = view
         @columns = columns
       end
 
-      def column(data, **options)
-        @columns << options.merge(data: data)
+      def column(data = nil, **options, &block)
+        header_content = @view.capture(&block) if block
+
+        @columns << options.merge(data: data, header_content: header_content).compact
         nil
       end
     end

data/lib/generators/stimulus_rails_datatables/install/install_generator.rb

@@ -17,7 +17,7 @@ module StimulusRailsDatatables
 
       private
 
-      def readme(filename)
+      def readme(_filename)
         say ''
         say '=' * 80
         say 'StimulusRailsDatatables has been installed!'
@@ -34,7 +34,7 @@ module StimulusRailsDatatables
         say ''
         say "   application.register('datatable', DatatableController)"
         say "   application.register('filter', FilterController)"
-        say "   window.AppDataTable = AppDataTable"
+        say '   window.AppDataTable = AppDataTable'
         say ''
         say '3. Import app/javascript/datatables_config.js in your application.js:'
         say ''

data/lib/stimulus_rails_datatables/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StimulusRailsDatatables
-  VERSION = '0.3.2'
+  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.3.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Den Meralpis
@@ -24,45 +24,45 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.4'
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: importmap-rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8.3'
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8.3'
+        version: '3'
 - !ruby/object:Gem::Dependency
-  name: importmap-rails
+  name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '7.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '8.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '7.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '8.3'
 - !ruby/object:Gem::Dependency
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement