stimulus_rails_datatables 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a6c48a66c1fdfb21381c809b19c6a920f370a0c5840de680a698aa613e6ec82
-  data.tar.gz: 9020cb07384fcbd8edb98d6070ec6732cc14a2160ba6468ba13d9292799882e0
+  metadata.gz: d508095bbb7cd25e12447b92081260fa8fa373f139be6b065c5eb6f17b3118af
+  data.tar.gz: 9ae1b95a92a6898b2d2b6c55310f06dd7b8ca58902fb55d8f378d1a8605cf5ec
 SHA512:
-  metadata.gz: 7963d1211951e6bd536001f24cbee70710b073efaf00ccbd1c151769ab8534e4aa6d66503d34cc2630ef30197bef31609abb4442904c81e320b72e684d0c3e4e
-  data.tar.gz: 115e262ea157c6ac4dc3b1756dc146d17d7c82d5b9e6801074cebed0d542833178938d45c0c605f7f9653f6b7a53118511575623092d387d2f1c91fb5ec28df3
+  metadata.gz: fe105aa5f8bc6b0ffcc8bda21fe78c070d75c09b17a211d7e05a217a81ffcf680051e7cd2e5778f864d6735c191a63897ed25b2418e51e7fc9fea3fc14ece080
+  data.tar.gz: c87088b4327210d783377c05291fcf5194f8ae0fcc523408f99d2e678b820fd2ca3c3d465879e9f423d782df255914ef2f6c5bc37f13e640e5430631d301f19f

data/README.md

@@ -73,13 +73,16 @@ import 'datatables_config'
     <%= opts.option 'inactive', 'Inactive' %>
   <% end %>
 
+# If set_value matches, it will be mark as selected
+# When set_value is present, localStorage restoration is skipped
+# so the default is not overridden on page reload.
   <%= f.role(
     remote: {
       url: roles_path,
       label: 'name',
       value: 'id',
       placeholder: 'Select Role',
-      set_value: 1 # If set_value matches, it will be mark as selected
+      set_value: 1 
     }
   ) %>
 
@@ -92,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

@@ -9,7 +9,6 @@ export default class extends Controller {
   get filterDtId() {
     const today = new Date()
     const key = today.toISOString().split('T')[0]
-
     return `${key}:${this.element.dataset.filterDatatableId}`
   }
 
@@ -18,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()
@@ -81,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) => {
@@ -96,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]
@@ -117,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 = {}
@@ -176,7 +187,9 @@ export default class extends Controller {
       await this.populate(root)
       // after root options exist, restore saved root value (if any)
       const sv = savedParams[root.dataset.filterFieldName]
-      if (sv) root.value = sv
+      const set_value = root.dataset.filterSetValue || ''
+
+      if (sv && !set_value) root.value = sv
       // cascade down children
       await this.populateDependents(root, savedParams)
     }))
@@ -212,11 +225,22 @@ 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
       const childSaved = savedParams[child.dataset.filterFieldName]
-      if (childSaved) child.value = childSaved
+      const set_value = child.dataset.filterSetValue || ''
+
+      if (childSaved && !set_value) {
+        child.value = childSaved
+      }
       // recurse deeper
       await this.populateDependents(child, savedParams)
     }

data/lib/stimulus_rails_datatables/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StimulusRailsDatatables
-  VERSION = '0.3.0'
+  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.0
+  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: 3.6.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Rails integration for DataTables with filters and remote data support
 test_files: []