stimulus_rails_datatables 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37084c381ea6525cd86e4f0e054cd820cad452b1ff5730838a70cc14f882b36c
-  data.tar.gz: 2f42e8db7673ee1dddb56808ff4946498c5162d93351ff44f1d70dbc0dd3dee3
+  metadata.gz: d508095bbb7cd25e12447b92081260fa8fa373f139be6b065c5eb6f17b3118af
+  data.tar.gz: 9ae1b95a92a6898b2d2b6c55310f06dd7b8ca58902fb55d8f378d1a8605cf5ec
 SHA512:
-  metadata.gz: dc8d7d11d3e3d76284f98aef79630dc4ea6a73d7fc04a480438b29e9d4b9ed4c44a3f3f5cf2984d798a6ffeabbbe31e688bf5cd3bea5011a1476d088ea46f02f
-  data.tar.gz: 30c151d855c89c118377506aa1fd88b53a053cbd8fd5e6b33462639d66365fa776bd405ea6b7d89bf7dcda3f65b4a3745d9307ecb637eaaf848896ff9c696f80
+  metadata.gz: fe105aa5f8bc6b0ffcc8bda21fe78c070d75c09b17a211d7e05a217a81ffcf680051e7cd2e5778f864d6735c191a63897ed25b2418e51e7fc9fea3fc14ece080
+  data.tar.gz: c87088b4327210d783377c05291fcf5194f8ae0fcc523408f99d2e678b820fd2ca3c3d465879e9f423d782df255914ef2f6c5bc37f13e640e5430631d301f19f

data/README.md

@@ -95,6 +95,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/lib/stimulus_rails_datatables/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StimulusRailsDatatables
-  VERSION = '0.3.1'
+  VERSION = '0.3.2'
 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.3.2
 platform: ruby
 authors:
 - Den Meralpis
@@ -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: []