stimulus_rails_datatables 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37084c381ea6525cd86e4f0e054cd820cad452b1ff5730838a70cc14f882b36c
-  data.tar.gz: 2f42e8db7673ee1dddb56808ff4946498c5162d93351ff44f1d70dbc0dd3dee3
+  metadata.gz: 33857a74b843142081e2c836a7ca6b9ea3478b5de62c641397de780174b3365c
+  data.tar.gz: fc7ceebc44032ec83db84357e9472c981c011f927581d051c5ed75d9de2785a1
 SHA512:
-  metadata.gz: dc8d7d11d3e3d76284f98aef79630dc4ea6a73d7fc04a480438b29e9d4b9ed4c44a3f3f5cf2984d798a6ffeabbbe31e688bf5cd3bea5011a1476d088ea46f02f
-  data.tar.gz: 30c151d855c89c118377506aa1fd88b53a053cbd8fd5e6b33462639d66365fa776bd405ea6b7d89bf7dcda3f65b4a3745d9307ecb637eaaf848896ff9c696f80
+  metadata.gz: 496590e1f982a96b81f0c65e4ae6f577f82b9d59bb3a6638e294a3fbeff96d391e92552b1f352316e4864f3c8a70fe4846bf01ae6cd955f046818b111e88d0f7
+  data.tar.gz: 886217d0aab41163e3d282e80c9144ada0f4b025f190753ce95c76fbfb9294ea65791ee1b078f75391b5a0e38b1bef4b4d7d71b4857223969fe20415903cb752

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
@@ -95,6 +109,92 @@ import 'datatables_config'
 <% end %>
 ```
 
+#### Dependent Location Filters
+
+Use dependent remote selects when one filter should load its options from the value of another filter. The built-in `location` helper creates three filters named `province_id`, `city_id`, and `barangay_id`.
+
+```ruby
+<%= filter_for 'locations-table' do |f| %>
+  <%= f.location(
+    province_url: provinces_path(format: :json),
+    city_url: cities_path(province_id: '{province_id}', format: :json),
+    barangay_url: barangays_path(city_id: '{city_id}', format: :json)
+  ) %>
+<% end %>
+
+<%= datatable_for 'locations-table', source: locations_path(format: :json) do |dt| %>
+  <% dt.column :name, title: 'Name' %>
+  <% dt.column :province_name, title: 'Province' %>
+  <% dt.column :city_name, title: 'City' %>
+  <% dt.column :barangay_name, title: 'Barangay' %>
+<% end %>
+```
+
+The `{province_id}` and `{city_id}` placeholders are replaced in the browser before fetching the next select's options:
+
+- changing province fetches `cities_path(... province_id: selected_province_id)`
+- changing city fetches `barangays_path(... city_id: selected_city_id)`
+- changing any filter reloads the datatable with params such as `filters[province_id]=1&filters[city_id]=2`
+
+Your JSON endpoints should return an array using the keys configured by the helper: `location_id` for the option value and `name` for the label.
+
+```ruby
+class ProvincesController < ApplicationController
+  def index
+    render json: Province.select(:location_id, :name)
+  end
+end
+
+class CitiesController < ApplicationController
+  def index
+    cities = City.where(province_id: params[:province_id])
+    render json: cities.select(:location_id, :name)
+  end
+end
+
+class BarangaysController < ApplicationController
+  def index
+    barangays = Barangay.where(city_id: params[:city_id])
+    render json: barangays.select(:location_id, :name)
+  end
+end
+```
+
+Then apply the selected filters inside your datatable class:
+
+```ruby
+def get_raw_records
+  Location.all.then { |relation| apply_filters(relation) }
+end
+
+def apply_filters(relation)
+  relation = relation.where(province_id: query_filters[:province_id]) if query_filters[:province_id].present?
+  relation = relation.where(city_id: query_filters[:city_id]) if query_filters[:city_id].present?
+  relation = relation.where(barangay_id: query_filters[:barangay_id]) if query_filters[:barangay_id].present?
+  relation
+end
+```
+
+To load the table already filtered from the page URL, use normal nested filter params:
+
+```text
+/locations?filters[province_id]=1&filters[city_id]=2&filters[barangay_id]=3
+```
+
+Pass those params into the datatable source on the initial render:
+
+```ruby
+<% location_filters = params[:filters]&.permit(:province_id, :city_id, :barangay_id) || {} %>
+
+<%= datatable_for 'locations-table',
+  source: locations_path(format: :json, filters: location_filters) do |dt| %>
+  <% dt.column :name, title: 'Name' %>
+  <% dt.column :province_name, title: 'Province' %>
+  <% dt.column :city_name, title: 'City' %>
+  <% dt.column :barangay_name, title: 'Barangay' %>
+<% end %>
+```
+
 ### Backend DataTable Class
 
 ```ruby

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

@@ -17,14 +17,14 @@ export default class extends Controller {
     this.restoreState()
 
     // single delegated listener — saves and triggers dependent populates
-    this.element.addEventListener('change', (event) => {
+    this.element.addEventListener('change', async (event) => {
       if (!event.target.matches('[data-filter-field-name]')) return
 
-      // persist the user's change
-      this.saveState()
+      // if this field has dependents, reset stale child values and re-populate them
+      await this.populateDependents(event.target)
 
-      // if this field has dependents, re-populate them
-      this.populateDependents(event.target, this.currentParams()[this.element.dataset.filterRootKey] || {})
+      // persist the user's change after dependent filters have been cleaned up
+      this.saveState()
 
       // trigger datatable reload
       this.reloadAppDatatable()
@@ -80,7 +80,6 @@ export default class extends Controller {
     let url = select.dataset.filterRemoteUrlValue
     const labelKey = select.dataset.filterLabelKey
     const valueKey = select.dataset.filterValueKey
-    const placeholder = select.dataset.filterPlaceholder || 'Select'
     const set_value = select.dataset.filterSetValue || ''
 
     url = decodeURIComponent(url).replace(/{(\w+)}/g, (_, key) => {
@@ -95,7 +94,7 @@ export default class extends Controller {
       if (!response.ok) throw new Error(`Failed to fetch ${url}`)
       const data = await response.json()
 
-      select.innerHTML = `<option value="">${placeholder}</option>`
+      this.resetSelect(select, false)
       data.forEach(item => {
         const option = document.createElement('option')
         option.value = item[valueKey]
@@ -116,6 +115,19 @@ export default class extends Controller {
     }
   }
 
+  resetSelect(select, disabled = true) {
+    const placeholder = select.dataset.filterPlaceholder || 'Select'
+    const option = document.createElement('option')
+
+    option.value = ''
+    option.textContent = placeholder
+
+    select.innerHTML = ''
+    select.appendChild(option)
+    select.value = ''
+    select.disabled = disabled
+  }
+
   currentParams() {
     const rootKey = this.element.dataset.filterRootKey
     const params = {}
@@ -213,6 +225,13 @@ export default class extends Controller {
     const children = this.selects.filter(s => s.dataset.filterDependsOn === parentKey)
 
     for (const child of children) {
+      this.resetSelect(child)
+
+      if (!parent.value) {
+        await this.populateDependents(child, savedParams)
+        continue
+      }
+
       // populate child using parent's current value substituted by populate()
       await this.populate(child)
       // restore child's saved value if exists

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.1'
+  VERSION = '0.4.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stimulus_rails_datatables
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.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
@@ -141,7 +141,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Rails integration for DataTables with filters and remote data support
 test_files: []