stimulus_rails_datatables 0.5.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbb9263b496e3deed5f28f35c19530d54cdc311a032da2eeeefb60c0c9dfa07d
-  data.tar.gz: 613bcfbd3ce0dd842d0bf1a3067b91ddb24cb5d773340726ae2851cd17040a15
+  metadata.gz: 6c52d575fdf1e4bf88eb1cdf3b581ed80ec4c6956b1d5f0c3a60b90f99d2e3f2
+  data.tar.gz: 9bf301decccb7e7490972346183d73fa25d659088383521ff8b825b6bc83ac5e
 SHA512:
-  metadata.gz: 5619dd1eff78003687b588989cad96c353f52309eb184830764a5a42504033a61b5832bfc31fce8ef3fc856af7c4df30ebebc6554c3cfc1bb041b8a8b1c73ca7
-  data.tar.gz: d24f5d85abafab0b8dd73fd9ca3be0832efad5bdfc60caa98b2f0aa44990390792211432a46124ec6169fc54474787477dcbcb3e3fe282190c9b8d29fe1b6244
+  metadata.gz: 61e84f397c85ad598f98b47f7451e454fa6fae7e8e707fee9b9281829feecab1e151be8a387d4ea19cad63ac3d71f3e3c301f756dc2f20f07f9b7948a0f830ea
+  data.tar.gz: 780dddf9239013c1fb8444a0d2ffeaab370829cfbffcd0827d23f5545f8e082d3740403b8e4854e52ed0185cf8eccd683decd3eb9d6353e2b8e327ac7113c73d

data/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2026-09-25
+
+### Added
+- `resetPaging` global config option (`window.datatablesConfig` or `setDatatablesConfig`) to go back to the first page when filters change; defaults to `false`
+- `reset_paging` option for the `datatable_for` helper, which overrides the global `resetPaging` value per datatable
+
+## [0.6.0] - 2026-08-03
+
+### Added
+- Tom-Select support for remote filter selects via the `tomselect` option
+- `multiple` option for remote filter selects, sending the selected values as array params (`filters[key][]=`)
+- `set_values` remote option to preselect multiple values
+- Summary label showing the number of selected items on Tom-Select multi-selects
+
+### Changed
+- The `location` filter's barangay select is now a Tom-Select multi-select
+- The filter controller imports `tom-select`, so the host app must pin it in its importmap
+
 ## [0.5.1] - 2026-07-28
 
 ### Changed

data/README.md

@@ -335,10 +335,25 @@ window.datatablesConfig = {
   },
 
   // Length menu options
-  lengthMenu: [[10, 25, 50, 100], [10, 25, 50, 100]]
+  lengthMenu: [[10, 25, 50, 100], [10, 25, 50, 100]],
+
+  // Go back to the first page when filters change (default: false)
+  resetPaging: true
 }
 ```
 
+### Resetting Pagination on Filter Change
+
+By default, changing a filter reloads the datatable and keeps the current page. Set `resetPaging: true` in `window.datatablesConfig` to jump back to the first page for every datatable, or override it per table with `reset_paging:`:
+
+```ruby
+<%= datatable_for 'users-table', source: users_path, reset_paging: false do |dt| %>
+  <% dt.column :name %>
+<% end %>
+```
+
+Leave `reset_paging:` out to use the global value. Restoring saved filters on page load never resets the page, so the page kept by `state_save` is not lost.
+
 ### Available Stimulus Controllers
 
 The gem automatically registers the following Stimulus controllers:

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

@@ -30,7 +30,10 @@ let datatablesConfig = {
   },
 
   // Length menu options
-  lengthMenu: [[10, 25, 50, 100], [10, 25, 50, 100]]
+  lengthMenu: [[10, 25, 50, 100], [10, 25, 50, 100]],
+
+  // Go back to the first page when filters change (override per table with datatable_for reset_paging:)
+  resetPaging: false
 }
 
 // Function to let the app override defaults

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

@@ -17,7 +17,8 @@ export default class extends Controller {
     pagingType: { type: String, default: 'simple_numbers' },
     searching: { type: Boolean, default: true },
     lengthChange: { type: Boolean, default: true },
-    responsive: { type: Boolean, default: true }
+    responsive: { type: Boolean, default: true },
+    resetPaging: Boolean
   }
 
   connect() {
@@ -89,7 +90,8 @@ export default class extends Controller {
       const config = {
         language: { ...defaultConfig.language, ...(userConfig.language || {}) },
         layout: { ...defaultConfig.layout, ...(userConfig.layout || {}) },
-        lengthMenu: userConfig.lengthMenu || defaultConfig.lengthMenu
+        lengthMenu: userConfig.lengthMenu || defaultConfig.lengthMenu,
+        resetPaging: userConfig.resetPaging ?? defaultConfig.resetPaging
       }
 
       const responsiveValue = this.responsiveValue
@@ -107,6 +109,9 @@ export default class extends Controller {
         responsive: this.responsiveValue,
         language: config.language,
         layout: config.layout,
+        // Not a DataTables option; the filter controller reads it back via datatable.init()
+        // Per-table value (datatable_for reset_paging:) wins over the global config
+        resetPaging: this.hasResetPagingValue ? this.resetPagingValue : !!config.resetPaging,
         initComplete: function() {
           if (responsiveValue === false) {
             // Add overflow-x only to the table wrapper (not the whole layout) this is alternative of scrollX

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

@@ -2,6 +2,7 @@
 // Disabling eslint since this is a library file and may not conform to all rules
 
 import { Controller } from '@hotwired/stimulus'
+import TomSelect from 'tom-select'
 
 export default class extends Controller {
   static targets = ['select', 'customFields']
@@ -13,6 +14,45 @@ export default class extends Controller {
   }
 
   connect() {
+    this.tomSelects = new Map()
+    this.remoteSelects = Array.from(
+      this.element.querySelectorAll('select[data-filter-remote-url-value]')
+    )
+
+    this.remoteSelects.forEach(select => {
+      if (select.dataset.filterTomselect !== 'true') return
+
+      const isMultiple = select.multiple
+      const ts = new TomSelect(select, {
+        maxItems: isMultiple ? null : 1,
+        placeholder: select.dataset.filterPlaceholder || 'Select',
+        create: false,
+        hideSelected: isMultiple ? false : undefined,
+        render: isMultiple ? { item: () => '<div class="ts-hidden-item"></div>' } : {}
+      })
+
+      if (isMultiple) {
+        const originalOnOptionSelect = ts.onOptionSelect.bind(ts)
+        ts.onOptionSelect = (evt, option) => {
+          const value = option.dataset.value
+          if (ts.items.includes(value)) {
+            evt.preventDefault()
+            ts.removeItem(value)
+            ts.refreshOptions(false)
+          } else {
+            originalOnOptionSelect(evt, option)
+          }
+        }
+        this.updateSummaryLabel(select, ts)
+        ts.on('item_add', () => this.updateSummaryLabel(select, ts))
+        ts.on('item_remove', () => this.updateSummaryLabel(select, ts))
+      }
+
+      this.tomSelects.set(select, ts)
+
+      if (select.dataset.filterDependsOn) ts.disable()
+    })
+
     // begin restore; it is async but will dispatch filters:ready when done
     this.restoreState()
 
@@ -29,16 +69,50 @@ export default class extends Controller {
       // trigger datatable reload
       this.reloadAppDatatable()
     })
+  }
 
-    // collect selects for later use
-    this.selects = Array.from(this.element.querySelectorAll('select[data-filter-remote-url-value]'))
+  disconnect() {
+    this.tomSelects?.forEach(ts => ts.destroy())
+    this.tomSelects?.clear()
+  }
 
-    // if there are top-level remote selects we want them available for manual changes
-    this.selects.forEach(select => {
-      if (select.dataset.filterDependsOn) {
-        select.disabled = true
-      }
-    })
+  // --- helpers: single source of truth for reading/writing a field, Tom-Select-aware ---
+  getFieldValue(el) {
+    const ts = this.tomSelects.get(el)
+    return ts ? ts.getValue() : el.value
+  }
+
+  isValueEmpty(value) {
+    return Array.isArray(value) ? value.length === 0 : !value
+  }
+
+  setFieldValue(el, value, silent = true) {
+    const ts = this.tomSelects.get(el)
+    if (ts) ts.setValue(value, silent)
+    else el.value = value
+  }
+
+  updateSummaryLabel(select, ts) {
+    const count = ts.items.length
+    const placeholder = select.dataset.filterPlaceholder || 'Select'
+
+    let label = ts.control.querySelector('.ts-summary-label')
+    if (!label) {
+      label = document.createElement('div')
+      label.className = 'ts-summary-label'
+      ts.control.prepend(label)
+    }
+
+    const hasSelection = count > 0
+    label.textContent = hasSelection ? `${count} Barangay${count > 1 ? 's' : ''} selected` : ''
+    label.style.display = hasSelection ? 'block' : 'none'
+
+    if (hasSelection) {
+      ts.control_input.style.setProperty('display', 'none', 'important')
+    } else {
+      ts.control_input.style.removeProperty('display')
+      ts.control_input.setAttribute('placeholder', placeholder)
+    }
   }
 
   toQuery(obj, prefix) {
@@ -47,7 +121,10 @@ export default class extends Controller {
     for (const [key, value] of Object.entries(obj)) {
       const fullKey = prefix ? `${prefix}[${key}]` : key
 
-      if (value !== null && typeof value === 'object') {
+      if (Array.isArray(value)) {
+        value.forEach(v => pairs.push(`${encodeURIComponent(fullKey)}[]=${encodeURIComponent(v)}`))
+      }
+      else if (value !== null && typeof value === 'object') {
         pairs.push(this.toQuery(value, fullKey))
       }
       else if (value !== '' && value !== null && value !== undefined) {
@@ -59,7 +136,8 @@ export default class extends Controller {
   }
 
   // reloadAppDatatable reloads the datatable with current params
-  async reloadAppDatatable() {
+  // pass resetPaging true/false to force it, otherwise the datatable's resetPaging setting is used
+  async reloadAppDatatable(resetPaging) {
     var id = this.element.dataset.filterDatatableId
 
     if (!id) {
@@ -70,17 +148,20 @@ export default class extends Controller {
       const datatableUrl = datatable.ajax.url().split('?')[0]
       const params = this.toQuery(this.currentParams())
 
-      datatable.ajax.url(`${datatableUrl}?${params}`).load(null, false)
-    }
+      if (typeof resetPaging !== 'boolean') resetPaging = datatable.init()?.resetPaging === true
 
+      datatable.ajax.url(`${datatableUrl}?${params}`).load(null, resetPaging)
+    }
   }
 
   // async populate returns when options appended
   async populate(select) {
+    const ts = this.tomSelects.get(select)
     let url = select.dataset.filterRemoteUrlValue
     const labelKey = select.dataset.filterLabelKey
     const valueKey = select.dataset.filterValueKey
-    const set_value = select.dataset.filterSetValue || ''
+    const setValues = (select.dataset.filterSetValues || select.dataset.filterSetValue || '')
+      .split(',').map(v => v.trim()).filter(Boolean)
 
     url = decodeURIComponent(url).replace(/{(\w+)}/g, (_, key) => {
       const input = this.element.querySelector(`[data-filter-field-name='${key}']`)
@@ -94,38 +175,54 @@ export default class extends Controller {
       if (!response.ok) throw new Error(`Failed to fetch ${url}`)
       const data = await response.json()
 
-      this.resetSelect(select, false)
-      data.forEach(item => {
-        const option = document.createElement('option')
-        option.value = item[valueKey]
-        option.textContent = item[labelKey]
-
-        // If set_value matches, mark as selected
-        if (set_value && item[valueKey] == set_value) {
-          option.selected = true
+      if (ts) {
+        ts.clear(true)            // clear current selection (silent — no change event)
+        ts.clearOptions()         // wipe stale option list
+        if (!select.multiple) {
+          const placeholder = select.dataset.filterPlaceholder || 'All'
+          ts.addOption({ value: '', text: placeholder })
         }
-
-        select.appendChild(option)
-      })
-
-      select.disabled = false
+        ts.addOptions(data.map(item => ({ value: String(item[valueKey]), text: item[labelKey] })))
+        if (setValues.length) this.setFieldValue(select, select.multiple ? setValues : setValues[0])
+        ts.enable()
+        if (select.multiple) this.updateSummaryLabel(select, ts)
+      } else {
+        select.innerHTML = ''
+
+        const placeholder = select.dataset.filterPlaceholder || 'All'
+        const blankOption = document.createElement('option')
+        blankOption.value = ''
+        blankOption.textContent = placeholder
+        select.appendChild(blankOption)
+
+        data.forEach(item => {
+          const option = document.createElement('option')
+          option.value = item[valueKey]
+          option.textContent = item[labelKey]
+          if (setValues.includes(String(item[valueKey]))) option.selected = true
+          select.appendChild(option)
+        })
+        select.disabled = false
+      }
     } catch (e) {
       console.error('[Filter] fetch error:', e)
-      select.disabled = false
+      if (ts) ts.enable()
+      else select.disabled = false
     }
   }
 
   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
+    const ts = this.tomSelects.get(select)
+    if (ts) {
+      ts.clear(true)
+      ts.clearOptions()
+      disabled ? ts.disable() : ts.enable()
+    } else {
+      const placeholder = select.dataset.filterPlaceholder || 'Select'
+      select.innerHTML = `<option value="">${placeholder}</option>`
+      select.value = ''
+      select.disabled = disabled
+    }
   }
 
   currentParams() {
@@ -133,20 +230,15 @@ export default class extends Controller {
     const params = {}
 
     this.element.querySelectorAll('[data-filter-field-name]').forEach(el => {
-      if (el.value) params[el.dataset.filterFieldName] = el.value
+      const value = this.getFieldValue(el)
+      if (!this.isValueEmpty(value)) params[el.dataset.filterFieldName] = value
     })
 
-    const clean = Object.entries(params).reduce((acc, [k, v]) => {
-      if (v !== '' && v !== null && v !== undefined) acc[k] = v
-      return acc
-    }, {})
-
-    return { [rootKey]: clean }
+    return { [rootKey]: params }
   }
 
   saveState() {
     const state = this.currentParams()
-    // deterministic storage key that datatable can read
     try {
       localStorage.setItem(`filterState:${this.filterDtId}`, JSON.stringify(state))
     } catch (e) {
@@ -176,21 +268,13 @@ export default class extends Controller {
       if (el && !el.dataset.filterRemoteUrlValue) el.value = value
     })
 
-    // collect remote selects (as an array)
-    this.selects = Array.from(this.element.querySelectorAll('select[data-filter-remote-url-value]'))
-
-    // find root remote selects (no depends_on)
-    const roots = this.selects.filter(s => !s.dataset.filterDependsOn)
+    const roots = this.remoteSelects.filter(s => !s.dataset.filterDependsOn)
 
-    // populate each root -> then recursively populate dependents and restore values
     await Promise.all(roots.map(async (root) => {
       await this.populate(root)
-      // after root options exist, restore saved root value (if any)
       const sv = savedParams[root.dataset.filterFieldName]
-      const set_value = root.dataset.filterSetValue || ''
-
-      if (sv && !set_value) root.value = sv
-      // cascade down children
+      const hasSetValue = root.dataset.filterSetValue || root.dataset.filterSetValues
+      if (sv && !hasSetValue) this.setFieldValue(root, sv)
       await this.populateDependents(root, savedParams)
     }))
 
@@ -201,52 +285,50 @@ export default class extends Controller {
         const sd = this.element.querySelector('[data-filter-field-name="start_date"]')
         if (sd) sd.value = savedParams['start_date']
       }
-
       if (savedParams['end_date']) {
         const ed = this.element.querySelector('[data-filter-field-name="end_date"]')
         if (ed) ed.value = savedParams['end_date']
       }
     }
 
-    // emit event (use document, bubbles already) so any listener can catch
+    // emit event so any listener can catch
     const payload = this.currentParams()
     this.element.dispatchEvent(new CustomEvent('filters:ready', { detail: { params: payload }, bubbles: true }))
 
-    // also update deterministic storage (in case other code reads it)
     try {
       localStorage.setItem(`filterState:${this.filterDtId}`, JSON.stringify(payload))
     } catch (e) {}
+
+    // restoring saved filters is not a filter change, so keep the page restored by stateSave
+    if (Object.keys(payload[rootKey] || {}).length > 0) {
+      this.reloadAppDatatable(false)
+    }
   }
 
   // recursively populate children of parent, restore each child's saved value, then recurse
   async populateDependents(parent, savedParams = {}) {
-    this.selects = this.selects || Array.from(this.element.querySelectorAll('select[data-filter-remote-url-value]'))
     const parentKey = parent.dataset.filterFieldName
-    const children = this.selects.filter(s => s.dataset.filterDependsOn === parentKey)
+    const children = this.remoteSelects.filter(s => s.dataset.filterDependsOn === parentKey)
 
     for (const child of children) {
       this.resetSelect(child)
 
-      if (!parent.value) {
+      const parentValue = this.getFieldValue(parent)
+      if (this.isValueEmpty(parentValue)) {
         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
+
       const childSaved = savedParams[child.dataset.filterFieldName]
-      const set_value = child.dataset.filterSetValue || ''
+      const hasSetValue = child.dataset.filterSetValue || child.dataset.filterSetValues
+      if (childSaved && !hasSetValue) this.setFieldValue(child, childSaved)
 
-      if (childSaved && !set_value) {
-        child.value = childSaved
-      }
-      // recurse deeper
       await this.populateDependents(child, savedParams)
     }
   }
 
-  // duration handler (unchanged)
   durationChanged(event) {
     const select = event.target
 
@@ -267,4 +349,4 @@ export default class extends Controller {
       document.querySelectorAll('.customDurationField').forEach(el => el.remove())
     }
   }
-}
+}

data/app/helpers/stimulus_rails_datatables/datatable_helper.rb

@@ -8,6 +8,7 @@ module StimulusRailsDatatables
       length_change = options.fetch(:length_change, true)
       state_save = options.fetch(:state_save, true)
       responsive = options.fetch(:responsive, true)
+      reset_paging = options[:reset_paging] # nil falls back to the global resetPaging config
       columns = []
 
       capture(DatatableBuilder.new(self, columns), &block)
@@ -22,7 +23,8 @@ module StimulusRailsDatatables
         datatable_searching_value: searching,
         datatable_length_change_value: length_change,
         datatable_state_save_value: state_save,
-        datatable_responsive_value: responsive
+        datatable_responsive_value: responsive,
+        datatable_reset_paging_value: reset_paging
       }
 
       content_tag(:div, data: data) do

data/app/helpers/stimulus_rails_datatables/filter_helper.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+
 module StimulusRailsDatatables
   module FilterHelper
     def filter_for(datatable_id, root_key: 'filters', &)
@@ -39,6 +40,7 @@ module StimulusRailsDatatables
         else
           remote = options[:remote] || {}
           depends_on = options[:depends_on]
+          multiple = options[:multiple] || false
 
           attrs = {
             filter_field_name: name,
@@ -47,16 +49,22 @@ module StimulusRailsDatatables
             filter_value_key: remote[:value],
             filter_depends_on: depends_on&.to_s,
             filter_placeholder: remote[:placeholder] || 'Select an option',
-            filter_set_value: remote[:set_value]
+            filter_set_value: remote[:set_value],
+            filter_set_values: remote[:set_values],
+            filter_tomselect: options[:tomselect] 
+
           }
 
           select_options = {
             data: attrs,
-            class: html_class
+            class: html_class,
+            multiple: multiple
           }
 
           # Only disable if it depends on another field
           select_options[:disabled] = true if depends_on.present?
+          field_name = "#{field_name}[]" if multiple
+
 
           @view.select_tag(field_name, @view.options_for_select([]), **select_options)
         end
@@ -94,6 +102,8 @@ module StimulusRailsDatatables
             placeholder: 'All Barangays'
           },
           depends_on: :city_id,
+          multiple: true,
+          tomselect: true,
           class: html_class
         )
 

data/lib/generators/stimulus_rails_datatables/install/templates/datatables_config.js

@@ -41,5 +41,8 @@ window.datatablesConfig = {
   },
 
   // Length menu options
-  lengthMenu: [[10, 25, 50, 100], [10, 25, 50, 100]]
+  lengthMenu: [[10, 25, 50, 100], [10, 25, 50, 100]],
+
+  // Go back to the first page when filters change (override per table with datatable_for reset_paging:)
+  resetPaging: false
 }

data/lib/stimulus_rails_datatables/version.rb

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

metadata

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