stimulus_rails_datatables 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8fb4d9d9a89a2835c85454e5233bbc7c6c842f3edfc773c66cf989f88a1d7360
+  data.tar.gz: ed4597b08c8d1a00063f48c963a2f11f7ba96a5436260d5a5a3348cd5f99f8f9
+SHA512:
+  metadata.gz: bdc04f63df7a51b0f49b3c179087aa16b9eed8aeea00133806b098a117d455eb1290f615683813cadc49bd45f68112d9282a30aacae1051d28df851ecd095eb4
+  data.tar.gz: eb61a469d12d5ee064556c3d947348067e091449e105be7bb04fa33bed8628c18518c5674d62d57599b459ccbccb2c3e9bb510d02ea4d803b14beb60b28c6743

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+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.1.0] - 2025-11-09
+
+### Added
+- Initial release
+- DataTable helper for creating server-side DataTables
+- Filter helper with advanced filtering capabilities
+- Stimulus controllers for datatables and filters
+- BaseDatatable class for easy backend integration
+- Support for dependent filters and remote data loading
+- LocalStorage state persistence for filters
+- Bootstrap 5 theme support
+- Bundled DataTables.net JavaScript libraries

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Den Meralpis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,147 @@
+# StimulusRailsDatatables
+
+A comprehensive Rails gem that provides DataTables integration with server-side processing, advanced filtering, and Stimulus controllers for modern Rails applications.
+
+## Features
+
+- **Server-side DataTables**: Full integration with ajax-datatables-rails
+- **Advanced Filtering**: Dynamic filters with dependent selects and date ranges
+- **Stimulus Controllers**: Modern JavaScript integration using Hotwire Stimulus
+- **Bootstrap 5 Support**: Beautiful, responsive tables out of the box
+- **LocalStorage State**: Filter and table state persistence
+- **Flexible API**: Easy-to-use Ruby helpers and JavaScript API
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'stimulus_rails_datatables'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+## Usage
+
+### Helpers
+
+#### Basic DataTable
+
+```ruby
+<%= datatable_for 'users-table', source: users_path do |dt| %>
+  <% dt.column :id, title: 'ID' %>
+  <% dt.column :name, title: 'Name' %>
+  <% dt.column :email, title: 'Email' %>
+  <% dt.column :created_at, title: 'Created', orderable: false %>
+<% end %>
+```
+
+#### With Filters
+
+```ruby
+<%= filter_for 'users-table' do |f| %>
+  <%= f.status do |opts| %>
+    <%= opts.option '', 'All Statuses' %>
+    <%= opts.option 'active', 'Active' %>
+    <%= opts.option 'inactive', 'Inactive' %>
+  <% end %>
+
+  <%= f.role(
+    remote: {
+      url: roles_path,
+      label: 'name',
+      value: 'id',
+      placeholder: 'Select Role'
+    }
+  ) %>
+
+  <%= f.duration do |opts| %>
+    <%= opts.option '', 'All Time' %>
+    <%= opts.option 'today', 'Today' %>
+    <%= opts.option 'this_week', 'This Week' %>
+    <%= opts.option 'custom', 'Custom Range' %>
+  <% end %>
+<% end %>
+```
+
+### Backend DataTable Class
+
+```ruby
+class UserDatatable < StimulusRailsDatatables::BaseDatatable
+  def view_columns
+    @view_columns ||= {
+      id: { source: "User.id" },
+      name: { source: "User.name" },
+      email: { source: "User.email" },
+      created_at: { source: "User.created_at" }
+    }
+  end
+
+  def data
+    records.map do |record|
+      {
+        id: record.id,
+        name: record.name,
+        email: record.email,
+        created_at: record.created_at.strftime('%Y-%m-%d')
+      }
+    end
+  end
+
+  def get_raw_records
+    User.all.then { |relation| apply_filters(relation) }
+  end
+
+  private
+
+  def apply_filters(relation)
+    relation = relation.where(status: query_filters[:status]) if query_filters[:status].present?
+    relation = relation.where(role_id: query_filters[:role_id]) if query_filters[:role_id].present?
+    relation
+  end
+end
+```
+
+### JavaScript API
+
+```javascript
+// Reload a specific datatable
+AppDataTable.reload('#users-table')
+
+// Load with new URL
+AppDataTable.load('#users-table', '/users?status=active')
+
+// Reload all datatables on page
+AppDataTable.reloadAll()
+```
+
+## Configuration
+
+The gem automatically registers Stimulus controllers and imports required JavaScript dependencies. The following controllers are available:
+
+- `datatable` - Main DataTable controller
+- `filter` - Filter controller with state management
+
+## Dependencies
+
+- Rails >= 7.0
+- ajax-datatables-rails ~> 1.4
+- importmap-rails
+- @hotwired/stimulus
+- DataTables.net with Bootstrap 5 theme
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/denmarkmeralpis/stimulus_rails_datatables.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

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

@@ -0,0 +1,34 @@
+import DataTable from 'datatables.net-responsive-bs5'
+
+class AppDataTable {
+  constructor(selector, options) {
+    // Initialize the DataTable just like the original one
+    this.table = new DataTable(selector, options)
+    this.id = selector.replace('#', '') // Extract ID from selector
+  }
+
+  // Reload a specific DataTable by ID
+  static reload(datatableID) {
+    const datatable = new AppDataTable(datatableID).table
+
+    if (datatable.context.length === 1) {
+      datatable.ajax.reload(null, false)
+    }
+  }
+
+  // Change the data source & reload
+  static load(datatableID, url) {
+    const datatable = new AppDataTable(datatableID).table
+
+    if (datatable.context.length === 1) {
+      datatable.ajax.url(url).load()
+    }
+  }
+
+  // Reload all DataTables
+  static reloadAll() {
+    DataTable.tables({ api: true }).ajax.reload(null, false)
+  }
+}
+
+export { AppDataTable }

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

@@ -0,0 +1,123 @@
+/* eslint-disable */
+// Disabling eslint since this is a library file and may not conform to all rules
+
+import { AppDataTable } from 'stimulus_rails_datatables/app_datatable'
+import { Controller } from '@hotwired/stimulus'
+
+export default class extends Controller {
+  static values = {
+    id: String,
+    source: String,
+    columns: { type: Array, default: [] },
+    order: { type: Array, default: [[1, 'desc']] },
+    stateSave: { type: Boolean, default: true },
+    serverSide: { type: Boolean, default: true },
+    processing: { type: Boolean, default: true },
+    pagingType: { type: String, default: 'simple_numbers' },
+    searching: { type: Boolean, default: true },
+    lengthChange: { type: Boolean, default: true }
+  }
+
+  connect() {
+    // try to use saved filters if present, else listen for filters:ready
+    const filterEl = document.querySelector('.filter-form[data-filter-root-key]')
+    if (filterEl) {
+      const dtid = filterEl.dataset.filterDatatableId
+      const raw = localStorage.getItem(`filterState:${dtid}`)
+      if (raw) {
+        try {
+          const saved = JSON.parse(raw)
+          this.initializeWithParams(saved)
+          return
+        } catch (e) { /* fallthrough to event listening */ }
+      }
+
+      // if no saved params, wait for filters:ready once
+      document.addEventListener('filters:ready', (e) => {
+        this.initializeWithParams(e.detail.params)
+      }, { once: true })
+
+      // safety fallback: if no filters:ready arrives, init after 2s with normal source
+      this._initFallbackTimer = setTimeout(() => {
+        this.initializeDataTable()
+      }, 2000)
+    } else {
+      // no filter form on page — init normally
+      this.initializeDataTable()
+    }
+  }
+
+  disconnect() {
+    if (this._initFallbackTimer) clearTimeout(this._initFallbackTimer)
+  }
+
+  // e.g. params = { filters: { a: 1, b: 2 } }
+  initializeWithParams(paramsObj) {
+    if (!paramsObj || Object.keys(paramsObj).length === 0) {
+      this.initializeDataTable()
+      return
+    }
+
+    // if fallback timer set, cancel it
+    if (this._initFallbackTimer) {
+      clearTimeout(this._initFallbackTimer)
+      this._initFallbackTimer = null
+    }
+
+    // build query string (supports nested like filters[a]=1)
+    const qs = this.toQuery(paramsObj)
+    const base = this.sourceValue || this.source
+    const ajaxUrl = qs ? `${base}?${qs}` : base
+    this.initializeDataTable(ajaxUrl)
+  }
+
+  initializeDataTable(url = this.sourceValue) {
+    const datatableId = this.idValue
+    const datatableWrapper = document.getElementById(`${datatableId}_wrapper`)
+    let appDataTable = null
+
+    if (datatableWrapper === null) {
+      Turbo.cache.exemptPageFromCache()
+
+      appDataTable = new AppDataTable(`#${datatableId}`, {
+        lengthMenu: [[10, 25, 50, 100], [10, 25, 50, 100]],
+        searching: this.searchingValue,
+        lengthChange: this.lengthChangeValue,
+        processing: this.processingValue,
+        serverSide: this.serverSideValue,
+        stateSave: this.stateSaveValue,
+        ajax: url,
+        pagingType: this.pagingTypeValue,
+        order: this.orderValue,
+        columns: this.columnsValue,
+        responsive: true,
+        language: {
+          processing: '<div class="spinner-border"></div><div class="mt-2">Loading...</div>',
+          lengthMenu: 'show <span class="px-2">_MENU_</span> entries'
+        },
+        layout: {
+          topStart: 'pageLength',
+          topEnd: 'search',
+          bottomStart: 'info',
+          bottomEnd: 'paging'
+        }
+      })
+    }
+
+    return appDataTable
+  }
+
+  // helper to serialize nested object like { filters: { a: 1 } } => filters[a]=1
+  toQuery(obj, prefix) {
+    const pairs = []
+    for (const [key, value] of Object.entries(obj)) {
+      const fullKey = prefix ? `${prefix}[${key}]` : key
+      if (value !== null && typeof value === "object") {
+        pairs.push(this.toQuery(value, fullKey))
+      } else if (value !== "" && value !== null && value !== undefined) {
+        pairs.push(`${encodeURIComponent(fullKey)}=${encodeURIComponent(value)}`)
+      }
+    }
+    return pairs.filter(Boolean).join("&")
+  }
+}

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

@@ -0,0 +1,239 @@
+/* eslint-disable */
+// Disabling eslint since this is a library file and may not conform to all rules
+
+import { Controller } from '@hotwired/stimulus'
+
+export default class extends Controller {
+  static targets = ['select', 'customFields']
+
+  get filterDtId() {
+    const today = new Date()
+    const key = today.toISOString().split('T')[0]
+
+    return `${key}:${this.element.dataset.filterDatatableId}`
+  }
+
+  connect() {
+    // begin restore; it is async but will dispatch filters:ready when done
+    this.restoreState()
+
+    // single delegated listener — saves and triggers dependent populates
+    this.element.addEventListener('change', (event) => {
+      if (!event.target.matches('[data-filter-field-name]')) return
+
+      // persist the user's change
+      this.saveState()
+
+      // if this field has dependents, re-populate them
+      this.populateDependents(event.target, this.currentParams()[this.element.dataset.filterRootKey] || {})
+
+      // trigger datatable reload
+      this.reloadAppDatatable()
+    })
+
+    // collect selects for later use
+    this.selects = Array.from(this.element.querySelectorAll('select[data-filter-remote-url-value]'))
+
+    // 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
+      }
+    })
+  }
+
+  toQuery(obj, prefix) {
+    const pairs = []
+
+    for (const [key, value] of Object.entries(obj)) {
+      const fullKey = prefix ? `${prefix}[${key}]` : key
+
+      if (value !== null && typeof value === 'object') {
+        pairs.push(this.toQuery(value, fullKey))
+      }
+      else if (value !== '' && value !== null && value !== undefined) {
+        pairs.push(`${encodeURIComponent(fullKey)}=${encodeURIComponent(value)}`)
+      }
+    }
+
+    return pairs.join('&')
+  }
+
+  // reloadAppDatatable reloads the datatable with current params
+  async reloadAppDatatable() {
+    var id = this.element.dataset.filterDatatableId
+
+    if (!id) {
+      return
+    }
+    else {
+      const datatable = new AppDataTable(`#${id}`).table
+      const datatableUrl = datatable.ajax.url().split('?')[0]
+      const params = this.toQuery(this.currentParams())
+
+      datatable.ajax.url(`${datatableUrl}?${params}`).load(null, false)
+    }
+
+  }
+
+  // async populate returns when options appended
+  async populate(select) {
+    let url = select.dataset.filterRemoteUrlValue
+    const labelKey = select.dataset.filterLabelKey
+    const valueKey = select.dataset.filterValueKey
+    const placeholder = select.dataset.filterPlaceholder || 'Select'
+
+    url = decodeURIComponent(url).replace(/{(\w+)}/g, (_, key) => {
+      const input = this.element.querySelector(`[data-filter-field-name='${key}']`)
+      return input ? input.value : ''
+    })
+
+    if (!url) return
+
+    try {
+      const response = await fetch(url)
+      if (!response.ok) throw new Error(`Failed to fetch ${url}`)
+      const data = await response.json()
+
+      select.innerHTML = `<option value="">${placeholder}</option>`
+      data.forEach(item => {
+        const option = document.createElement('option')
+        option.value = item[valueKey]
+        option.textContent = item[labelKey]
+        select.appendChild(option)
+      })
+
+      select.disabled = false
+    } catch (e) {
+      console.error('[Filter] fetch error:', e)
+      select.disabled = false
+    }
+  }
+
+  currentParams() {
+    const rootKey = this.element.dataset.filterRootKey
+    const params = {}
+
+    this.element.querySelectorAll('[data-filter-field-name]').forEach(el => {
+      if (el.value) params[el.dataset.filterFieldName] = el.value
+    })
+
+    const clean = Object.entries(params).reduce((acc, [k, v]) => {
+      if (v !== '' && v !== null && v !== undefined) acc[k] = v
+      return acc
+    }, {})
+
+    return { [rootKey]: clean }
+  }
+
+  saveState() {
+    const state = this.currentParams()
+    // deterministic storage key that datatable can read
+    try {
+      localStorage.setItem(`filterState:${this.filterDtId}`, JSON.stringify(state))
+    } catch (e) {
+      // ignore quota errors
+    }
+  }
+
+  loadState() {
+    try {
+      const raw = localStorage.getItem(`filterState:${this.filterDtId}`)
+      return raw ? JSON.parse(raw) : {}
+    } catch (e) {
+      return {}
+    }
+  }
+
+  // restoreState waits for all remote populates+restore to finish,
+  // then dispatches "filters:ready" with { params: currentParams() }
+  async restoreState() {
+    const saved = this.loadState()
+    const rootKey = this.element.dataset.filterRootKey
+    const savedParams = saved[rootKey] || {}
+
+    // restore simple (non-remote) fields immediately
+    Object.entries(savedParams).forEach(([key, value]) => {
+      const el = this.element.querySelector(`[data-filter-field-name='${key}']`)
+      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)
+
+    // 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]
+      if (sv) root.value = sv
+      // cascade down children
+      await this.populateDependents(root, savedParams)
+    }))
+
+    // restore start_date/end_date fields if duration was 'custom'
+    if (savedParams['duration'] === 'custom') {
+      this.durationChanged({ target: this.element.querySelector('[data-filter-field-name="duration"]') })
+      if (savedParams['start_date']) {
+        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
+    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) {}
+  }
+
+  // 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)
+
+    for (const child of children) {
+      // 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
+      // recurse deeper
+      await this.populateDependents(child, savedParams)
+    }
+  }
+
+  // duration handler (unchanged)
+  durationChanged(event) {
+    const select = event.target
+
+    if (select.value === 'custom') {
+      const fromDate = `<input type="date"
+               name="${select.name.replace('[duration]', '[start_date]')}"
+               class="textbox-n form-control form-control-sm mx-2 customDurationField"
+               data-filter-field-name="start_date" />`
+
+      const toDate = `<input type="date"
+              name="${select.name.replace('[duration]', '[end_date]')}"
+              class="textbox-n form-control form-control-sm customDurationField"
+              data-filter-field-name="end_date" />`
+
+      select.insertAdjacentHTML('afterend', toDate)
+      select.insertAdjacentHTML('afterend', fromDate)
+    } else {
+      document.querySelectorAll('.customDurationField').forEach(el => el.remove())
+    }
+  }
+}

data/app/datatables/stimulus_rails_datatables/base_datatable.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module StimulusRailsDatatables
+  class BaseDatatable < AjaxDatatablesRails::ActiveRecord
+    def current_page
+      params.fetch(:start, 0).to_i
+    end
+
+    def query_filters
+      (filters || {}).symbolize_keys.compact_blank!
+    end
+
+    private
+
+    # Filters according to the provided arguments with OR condition.
+    # @param [Hash{Class => Array<Symbol>] **arguments Filtering objects based on columns.
+    # @return [Proc] A lambda function that filters the records based on the provided arguments.
+    # :nocov:
+    def or_search_by_fields(**arguments)
+      lambda do |column, _|
+        conditions = []
+
+        arguments.each do |model, fields|
+          arel_table = model.arel_table
+          fields.each do |field|
+            conditions << arel_table[field].matches("%#{column.search.value}%")
+          end
+        end
+
+        conditions.reduce { |combination, condition| combination.or(condition) }
+      end
+    end
+    # :nocov:
+
+    def filters
+      filter_hash = params[:filters]
+      filter_hash.permit!.to_h if filter_hash
+    end
+  end
+end

data/app/helpers/stimulus_rails_datatables/datatable_helper.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module StimulusRailsDatatables
+  module DatatableHelper
+    def datatable_for(id, source:, order: [[2, 'desc']], **options)
+      classes = options.fetch(:classes, 'align-middle table w-100')
+      searching = options.fetch(:searching, true)
+      length_change = options.fetch(:length_change, true)
+      columns = []
+
+      yield DatatableBuilder.new(columns)
+
+      data = {
+        controller: 'datatable',
+        datatable_id_value: id,
+        datatable_source_value: source,
+        datatable_order_value: order.to_json,
+        datatable_columns_value: columns.to_json,
+        datatable_searching_value: searching,
+        datatable_length_change_value: length_change
+      }
+
+      content_tag(:div, data: data) do
+        content_tag(:table, class: classes, id: id) do
+          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])
+              end)
+            end
+          end
+        end
+      end
+    end
+
+    class DatatableBuilder
+      attr_reader :columns
+
+      def initialize(columns)
+        @columns = columns
+      end
+
+      def column(data, **options)
+        @columns << options.merge(data: data)
+        nil
+      end
+    end
+  end
+end