custom_table 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 56a21b7978279adb93168f5879fbf85c9953cd90561b3eaffe12fb834039311c
+  data.tar.gz: 5ea82cf638892d34ed8c5dab7dd30c9b4c9d6ea5eacaf954acaa874131dd62dd
+SHA512:
+  metadata.gz: f0bbd84de0dcd118e79935abf955dc93ddd3161a4871321945644bdf0ce04b14f5705f93e81e68f97f73d602f4ca0fad55dbabcacc06fa10c76501200d619d22
+  data.tar.gz: d3ce8670c0d36f426f129a44a541932210986438657c1eeaaf76c7fe2ebca5f389c2ae958d4b6eb9b5d1d3bfb8d3b75fd2dde19a4413006265ae40136292ca7a

data/README.md

@@ -0,0 +1,210 @@
+# Custom Table
+
+Provides powerful set of functionality for showing tables of data:
+* Generated table and filter panel for any model
+* Declare fields that should be displayed, filtered or sorted
+* Customize visible fields for each user
+* Exporting table to XLSX
+
+## Setup
+
+* Run ```rails generate custom_table install``` to create User migration and Initializer
+* Generate base helpers
+* Add CustomTable engine routes
+* Add concern to controllers
+* Add CSS import to your application.css: ```@import 'custom_table/table.css';```
+* Add concern to User model
+* Declare your first model
+
+## Declaring fields
+
+The most important part of using this gem is to correctly declare fields available for showing in table.
+
+This should be declared in helper named by this pattern: 
+
+```{singular_model_name}_custom_table_fields```
+
+And shold return hash of field definitions:
+
+e.g.
+
+    def vegetable_custom_table_fields
+      fields = {}
+      fields[:color] = { search: { q: :color_eq, type: :text }, appear: :default }
+      return fields
+    end
+
+Use attribute name as key if possbile. Table will try to get most of options automatically from model if you pass regular attribute.
+
+### Fields declaration options
+
+* ```label``` adds label to the field. Will try to find human attribute name by default
+* ```search``` contains search parameters. Skip this if search is not available for this fields
+* * ```q``` ransack's "q" search marcher which is used to search by the field. For range use array of two elements, e.g. ```[:created_at_gteq, :created_at_lteq]```
+* * ```type``` type of search element to draw
+* ```appear``` controls visibility of the field. Default value is hidden if not specially selected
+* * ```default``` will appear by default
+* * ```always``` will always appear
+* * ```export``` will appear only in XLSX export
+* ```link_to_show``` if true, this fields will have link to show page of item
+* ```sort``` controls sorting ability for the fields (disabled by default). Use ```true``` or ```{default_order: :asc|:desc}```
+* ```amount``` if true, applies number-specific formatting to cells (right align)
+* ```helper``` helper name (will be used instead default, see below)
+* ```total_scope``` scope which will be applied to collection to count total for rows. By defalt it takes sum(:field)
+
+## Controller setup
+
+Add ```CustomTableConcern``` to your controller to get easy index page solution.
+
+This gem provides custom_table method for your controller which does Ransack search and Kaminari pagination for you:
+
+    def index
+      @q = @vegetables.ransack(params[:q])
+      @q.sorts = 'created_at desc' if @q.sorts.empty? # Sets default sorting for ransack
+
+      @vegetables = @q.result(distict: true)
+      @vegetables = @vegetables.page(params[:page]).per(params[:per] || 25)
+    end
+
+Is equivalent to:
+
+    def index
+      @vegetables = custom_table(@vegetables)
+    end
+
+Optional parameters are:
+
+* ```default_sorts``` - ```string``` sorting order if user not selected it (default to ```created_at desc```)
+* ```default_query``` - default ransack ```q``` object. Default is empty 
+
+## Rendering tables
+
+Invoke this in your index to display table:
+```custom_table_data collection: @vegetables```
+
+Options available are:
+
+* Second parameter is variant (can be skipped if you dont use variants)
+* ```collection``` is the only required option. Contains paged collection from your controller
+* ```parent``` parent resource for inherited routes
+* ```skip_fields``` array of field names as symbols. Removes specific fields from table
+* ```skip_actions``` removes all actions
+* ```skip_default_actions``` removes default actions
+* ```actions``` helper name for custom actions. Table also looks for ```{singular_model_name}_custom_table_actions``` helper presence
+* ```totals``` object of fields to show totals. Use symbols as keys and pass value or left nil to let table try to count total based on raw/field value
+* ```paginate``` set to false to skip pagination
+* ```last_page``` set to false to disable last page count request for performance
+* ```quick_filter``` set to true to enable simple full-text client-side search
+* ```with_select``` allows to add checkboxes toggler. Pass helper name which has (item, position) as parameters
+* ```tree``` set to true if you have parent-child relation and you want to show records grouped by parent. Be sure to disable pagination as it will only group current page records 
+* ```group_by``` set to helper name to group records by result of it. Be sure to disable pagination as it will only group current page records 
+* ```expanded``` expand grouped or trees by default
+
+## Rendering search panel
+
+Use this helper in order to show filter panel:
+
+```custom_table_filter search_model: Vegetable```
+
+Options:
+
+* ```search_model``` model class to use with this filter. The only required parameter.
+* ```hide_customization``` hides customization button
+* ```fields``` if you want to have pre-defined fields, not from model definition
+
+## Displaying custom fields
+
+You can declare fields which your model doesn't have. In this case table can't render field value so you have to provide helpers for rendering the field. Table renderer will try to look for these helpers in prioritizing order:
+
+* ```#{singular_model_name}_#{field}_field``` to avoid naming collisions
+* ```#{singular_model_name}_#{field}``` best choise for most projects
+* ```#{singular_model_name}_#{field}_raw``` use this to produce non-decorated raw data which can be used in tables
+
+If helper is not accessible table will try to render item via following methods:
+
+* Association via ```to_s``` method
+* Numeric attribute via ```amount``` helper which formats number
+* Raw text attributes
+* Boolean attribute via ```boolean_icon``` helper. Uses bootstrap icons and can be overriden
+
+If you use variant, following helper will have the priority over all options:
+* ```#{singular_model_name}_#{variant}_#{field}_field```
+* ```#{singular_model_name}_#{variant}_#{field}```
+
+## Displaying custom actions
+
+
+
+## Customizing user columns
+
+Add CustomTable as engine to your routes:
+
+And ```custom_table``` attribute as text to your model
+
+Search Settings button will show up automatically if you have at least one customizable field.
+
+You can also use settings button separatelly. It uses Rails turbo and you need to declare ```turbo-modal``` Turbo Tag within your HTML body.
+
+## Variants
+
+For each table you can declare additional variants (set of parameters to be saved to user customization).
+
+Important to note that you need to explicitly set list of available variants. Declare the following helper function:
+
+```{singular_model_name}_custom_table_fields```
+
+Which returns the array of available variant.
+
+Then just pass variant to filter and data helpers.
+
+## Table Stimulus helper
+
+
+
+
+## Downloading data as XLSX table
+
+This gem also provide partial for exporting all available columns as XLSX file via CAXLSX gem:
+
+    wb = xlsx_package.workbook
+    wb.add_worksheet(name: "Aircrafts") do |sheet|
+      render 'custom_table/table', sheet: sheet, collection: @aircrafts.except(:limit, :offset)
+    end
+
+## Using fieldset helper for show actions
+
+You can use the same fields declared for table within show views.
+This also can be used without any table fields declaration and setup.
+
+The simpliest case here is (haml):
+
+    = fieldset @instance do |fs|
+      = fs.field :name
+
+It will produce bootstrap fieldset formatting as well as value logic from tables.
+
+Fieldset formatting can be overriden via views (custom_table/_fieldset and custom_table/field)
+
+By default fieldset is integrated with ```turbo_editable``` gem and each field is wrapped with it. You can disable it by passing ```editable: false``` as param to fieldset of field.
+
+Options available are:
+
+* ```label``` - if it cannot be received via field definition 
+* ```editable_params``` - hash of params to be passed to editable
+
+All options from fieldset are proxied to field. So you can declare it once if suitable.
+
+You can declare how each field is displayed. Just add it as block within field:
+
+    = fieldset @instance do |fs|
+      = fs.field :name do
+        = @instance.name.upcase
+
+## Testing
+
+Use ```custom_table_use_all_fields``` GET param with any value to show all available fields in your feature tests
+
+## Development
+
+Running tests: rspec
+

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/assets/config/custom_table_manifest.js

@@ -0,0 +1 @@
+//= link_directory ../stylesheets/custom_table .css

data/app/assets/stylesheets/custom_table/application.scss

@@ -0,0 +1 @@
+@import "table.scss";

data/app/assets/stylesheets/custom_table/table.scss

@@ -0,0 +1,89 @@
+
+table.custom-table {
+
+  td.actions {
+    white-space: nowrap;
+    width: 85px;
+  }
+  a.sort_link {
+    text-decoration: none !important;
+    white-space: nowrap;
+  }
+  td.selected {
+    border: 2px solid rgb(26, 179, 26) !important;
+  }
+
+  tr {
+    .action {
+      visibility: hidden;
+      &.btn-sm {
+        padding: 2px 4px !important;
+      }
+    }
+    .d-action-none {
+      display: none;
+    }
+
+
+    &:hover {
+      .action {
+        visibility: visible;
+      }
+      .d-action-none {
+        display: inherit;
+      }
+    }
+
+  }
+
+
+
+  tr.sticky, thead.sticky {
+    position: sticky;
+    background: white;
+    z-index: 1;
+  }
+  th.sticky-left, td.sticky-left {
+    position: sticky;
+    left: 0px;
+    background: white;
+  }
+  .text-sm {
+    font-size: 11px;
+  }
+
+  .tree-opener {
+    cursor: pointer;
+    .opened {
+      display: none;
+    }
+    &.opened {
+      .opened {
+        display: inline;
+      }
+      .closed {
+        display: none;
+      }
+    }
+  }
+  
+  .table-sum {
+    position: fixed;
+    right: 0;
+    bottom: 0;
+    width: 150px;
+    background: white;
+    border: 2px solid black;
+    padding: 2px;
+    text-align: right;
+    margin-right: 5px;
+    z-index: 1000;
+  }
+
+}
+
+
+.widget table.custom-table td {
+  max-width: 120px;
+  overflow: hidden;
+}

data/app/controllers/concerns/custom_table_concern.rb

@@ -0,0 +1,118 @@
+module CustomTableConcern
+  extend ActiveSupport::Concern
+
+  included do
+    helper CustomTable::ApplicationHelper
+    helper CustomTable::FieldsetHelper
+    helper CustomTable::IconsHelper
+
+  end
+
+  class_methods do 
+  end
+
+  def format_web
+    !(request.format.xlsx? || request.format.csv?)
+  end
+
+  def custom_table collection, variant = nil, default_sorts: "created_at desc", default_search: {}
+
+    @q = collection.ransack(params[:q])
+    @q = collection.ransack((params[:q] || {}).merge(default_search)) if params[:q].nil?
+
+    customization = helpers.custom_table_user_customization_for(collection.model, variant)
+    @q.sorts = customization&.dig(:sorts).presence || default_sorts if @q.sorts.empty?
+
+    collection = @q.result(distinct: true)
+    # collection = collection.page(params[:page]).per(per_page) if format_web && paginate
+
+    if !current_user.nil?
+      current_user.save_custom_table_settings(collection.model, variant, per_page: params[:per]) if !params[:per].nil? && params[:do_not_save_settings].nil?
+      if !params[:q].nil? && !params[:q][:s].nil? && !@q.nil? && !@q.sorts[0].nil? && !@q.sorts[0].name.nil? && params[:do_not_save_settings].nil?
+        current_user.save_custom_table_settings(collection.model, variant, sorts: "#{@q.sorts[0].name} #{@q.sorts[0].dir}")
+      end
+    end
+
+    return collection
+  end
+
+  def custom_table_export(format, collection, filename: nil)
+
+    filename ||= collection.model.model_name.plural
+
+    format.xlsx do
+      # if collection.count > 1000
+        # redirect_to params.permit!.merge({:format => :html}), alert: t("custom_table.huge_xlsx_alert", csv: helpers.link_to(t("custom_table.download_as_csv"), params.permit!.merge({:format => :csv})))
+      # else
+        response.headers['Content-Disposition'] = "attachment; filename=\"#{filename}.xlsx\""
+      # end
+    end
+
+    format.csv do
+      # Delete this header so that Rack knows to stream the content.
+      headers.delete("Content-Length")
+      # Do not cache results from this action.
+      headers["Cache-Control"] = "no-cache"
+      # Let the browser know that this file is a CSV.
+      headers['Content-Type'] = 'text/csv'
+      # Do not buffer the result when using proxy servers.
+      headers['X-Accel-Buffering'] = 'no'
+      # Set the filename
+      headers['Content-Disposition'] = "attachment; filename=\"#{filename}.csv\"" 
+
+      global_model_name = collection.model.model_name.singular
+
+      fields = helpers.custom_table_fields_definition_for(collection.model)
+
+      # Allow pre-defined fields for export
+      if !@fields.nil?
+        fields = fields.select { |k, _v| local_assigns[:fields].include?(k) }
+      end 
+
+      @csv_enumerator ||= Enumerator.new do |yielder|
+
+        head = []
+
+        fields.each do |field, defs|
+          head.push (defs[:label].nil? ? collection.model.human_attribute_name(field) : defs[:label])
+        end
+
+        yielder << CSV.generate_line(head)
+
+        collection.find_each do |item|
+
+          row = []
+          model_name = item.model_name.singular # Allows to show different class models in one table!
+    
+          fields.each do |field, defs|
+            next if defs[:table] == false
+        
+            value = helpers.raw_field_value_for(item, field)
+        
+            if [Date, ActiveSupport::TimeWithZone].include?(value.class)
+              value = value.to_date
+            end
+        
+            row.push value
+          end
+        
+          # Extra cols definition
+          if defined?(@extra_cols)
+            row += @extra_cols.call(item)
+          end    
+
+          yielder << CSV.generate_line(row)
+        end
+      end
+
+      self.response_body = @csv_enumerator
+    end
+
+  end
+
+
+
+  private
+  
+
+end

data/app/controllers/custom_table/application_controller.rb

@@ -0,0 +1,4 @@
+module CustomTable
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/custom_table/settings_controller.rb

@@ -0,0 +1,86 @@
+module CustomTable
+  class SettingsController < ::ApplicationController
+
+    before_action :authenticate_user!
+    skip_authorization_check # Because we do it manually
+
+    layout false
+
+    def edit
+      @search_model = params[:id].constantize
+      @variant = params[:variant].presence
+      if !@variant.nil? && !helpers.custom_table_variants_for(@search_model).include?(@variant)
+        render status: 404, html: "No such variant: #{@variant}"
+        return
+      end
+    end
+
+    # PATCH/PUT settings
+    def update
+
+      p = settings_params.to_h
+
+      model = p[:model].constantize
+      variant = p[:variant].presence
+
+      defs = helpers.custom_table_fields_definition_for(model, variant)
+      variants = helpers.custom_table_variants_for(model)
+
+      if !variant.nil? && !variants.include?(variant)
+        render status: 422, html: "No such variant: #{variant}"
+        return
+      end
+
+      if defs.nil?
+        optional_redirect_to profile_path, alert: t("custom_table.customization_not_allowed", model: model)
+      end
+
+      p[:fields].reject!{|k,v| defs[k.to_sym].nil?} # Clearing unknown fields
+      p[:fields].each { |k, v| p[:fields][k] = (defs[k.to_sym][:appear] == :always) ? true : ActiveModel::Type::Boolean.new.cast(v) } 
+
+      if current_user.save_custom_table_settings(model, variant, fields: p[:fields])
+        flash[:notice] = t("custom_table.customization_saved")
+        respond_to do |format|
+          format.turbo_stream {render turbo_stream: turbo_stream.action(:refresh, nil)}
+        end
+      else
+        # optional_redirect_to main_app.root_path, alert: t("custom_table.cannot_save_customization")
+      end
+
+    end
+
+    # PATCH/PUT settings
+    def destroy
+
+      model = params[:id].constantize
+      variant = params[:variant].presence
+
+      defs = helpers.custom_table_fields_definition_for(model)
+      variants = helpers.custom_table_variants_for(model)
+
+      if !variant.nil? && !variants.include?(variant)
+        render status: 422, html: "No such variant: #{variant}"
+        return
+      end
+
+      if current_user.destroy_custom_table_settings(model, variant)
+        flash[:notice] = t("custom_table.customization_saved")
+        respond_to do |format|
+          format.turbo_stream {render turbo_stream: turbo_stream.action(:refresh, nil)}
+        end
+      else
+        # optional_redirect_to main_app.root_path, alert: t("custom_table.cannot_save_customization")
+      end
+
+    end
+
+
+    private
+
+      # Only allow a list of trusted parameters through.
+      def settings_params
+        params.require(:user).permit(:model, :variant, { fields: {} })
+      end
+
+  end
+end