effective_datatables 4.7.16 → 4.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0782f0833ce459c31e724f049f4819e6276c4464c85822d9140f254747cde9cc'
-  data.tar.gz: 542aeb3d78e19c1dc8dff1adf8b7b6965c3a2b7d1a906c26560a42013a8c0e66
+  metadata.gz: 97162d77c01d7bc35d4d9bbda9b7f61d815628c7ded32c1c9c8a0a16e630c42f
+  data.tar.gz: 2bd27055dd9822c798373d0f073dc049ce471401cef071d50320a02f03d5c491
 SHA512:
-  metadata.gz: 90302ac7327123ce9e0a2520d70030ec8eb905c508bb15329641ae90210b5a7018723076b2c421150e289c7e2cc4b90193b8076d6bc5a5cb239c0864b4eaed5b
-  data.tar.gz: 2ebeed000e1e53e6948d7832c750322177c3c13db53ce61f2d0049ece7589b81499862b04ea760963a8e8c70228b7920efc3df6924980a58d945c4ac632ee497
+  metadata.gz: b7a59f37ce683bfb17e6b75715dee88a9125d26380988d7e9db9fd2c7f818e00235ee7418680d3dad90dabcf3c4e991bfb81ca32b7a4b80556573bf722a7e49f
+  data.tar.gz: 11d06c3f01185c4d92248bb40a32e78376eca5ae6bbbbabd5997a9a4a0a52f4d6ce1fb70bca5b6c50aa4ad60fb747b7060b3aaaf39bae0fbb5d51420cfbe9cef

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2019 Code and Effect Inc.
+Copyright 2021 Code and Effect Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -8,7 +8,7 @@ Does the right thing with searching sql columns as well as computed values from
 
 Displays links to associated edit/show/destroy actions based on `current_user` authorized actions.
 
-Other features include aggregate (total/average) footer rows, bulk actions, show/hide columns, responsive collapsing columns and Google charts.
+Other features include aggregate (total/average) footer rows, bulk actions, show/hide columns, responsive collapsing columns, google charts, and inline crud.
 
 This gem includes the jQuery DataTables assets.
 
@@ -46,6 +46,7 @@ Please check out [Effective Datatables 3.x](https://github.com/code-and-effect/e
     * [order](#order)
     * [reorder](#reorder)
     * [aggregate](#aggregate)
+    * [download](#download)
   * [filters](#filters)
     * [scope](#scope)
     * [filter](#filter)
@@ -54,7 +55,8 @@ Please check out [Effective Datatables 3.x](https://github.com/code-and-effect/e
     * [bulk_action](#bulk_action_divider)
     * [bulk_download](#bulk_download)
     * [bulk_action_content](#bulk_action_content)
-  * [charts](#charts)
+  * [Charts](#charts)
+  * [Inline](#inline)
   * [Extras](#extras)
   * [Advanced Search and Sort](#advanced-search-and-sort)
 * [Addtional Functionality](#additional-functionality)
@@ -196,6 +198,13 @@ class PostsDatatable < Effective::Datatable
     # POSTs to the given url with params[:ids], an Array of ids for all selected rows
     # These actions are assumed to change the underlying collection
     bulk_action 'Approve all', bulk_approve_posts_path, data: { confirm: 'Approve all selected posts?' }
+    # GETs to the given url. Pass the ids via cookie, encoded in url, or LocalStorage.
+    # These actions are assumed to redirect the user to some other page.
+    bulk_action 'Action 1 | ids encoded in params', action_1_posts_path, data: { method: :get }
+
+    bulk_action 'Action 2 | ids stored in _ids_ field in local storage', action_2_posts_path, data: { 'payload-mode' => 'local-storage', method: :get }
+
+    bulk_action 'Action 3 | ids stored in _ids_ field in a cookie', action_3_posts_path, data: { 'payload-mode' => 'cookie', method: :get }
     bulk_action_divider
     bulk_action 'Destroy all', bulk_destroy_posts_path, data: { confirm: 'Destroy all selected posts?' }
   end
@@ -453,7 +462,7 @@ The `datatable do ... end` block configures a table of data.
 
 Initialize the datatable in your controller or view, `@datatable = PostsDatatable.new(self)`, and render it in your view `<%= render_datatable(@datatable) %>`
 
-### col
+## col
 
 This is the main DSL method that you will interact with.
 
@@ -526,7 +535,7 @@ You can also use the joined syntax, `col 'user.email'` to create a column for ju
 
 This feature is only working with `belongs_to` and you need to add the `.joins(:user)` to the collection do ... end block yourself.
 
-### val
+## val
 
 Shorthand for value, this command also creates a column on the datatable.
 
@@ -548,7 +557,7 @@ This is implemented as a full Array search/sort and is much slower for large dat
 
 The `.format do ... end` block can then be used to apply custom formatting.
 
-### bulk_actions_col
+## bulk_actions_col
 
 Creates a column of checkboxes for use with the `bulk_actions` section.
 
@@ -558,7 +567,7 @@ Use these checkboxes to select all / none / one or more rows for the `bulk_actio
 
 You can only have one `bulk_actions_col` per datatable.
 
-### actions_col
+## actions_col
 
 When working with an ActiveRecord based collection, this column will consider the `current_user`'s authorization, and generate links to edit, show and destroy actions for any collection class.
 
@@ -596,7 +605,13 @@ Any `data-remote` actions will be hijacked and performed as inline ajax by datat
 
 If you'd like to opt-out of this behavior, use `actions_col(inline: false)` or add `data-inline: false` to your action link.
 
-### length
+If the automatic actions_col aren't being displayed, try setting the namespace directly when calling the table
+
+```
+MyApp::UsersTable.new(namespace: :my_app)
+```
+
+## length
 
 Sets the default number of rows per page. Valid lengths are `5`, `10`, `25`, `50`, `100`, `250`, `500`, `:all`
 
@@ -606,7 +621,7 @@ When not specified, effective_datatables uses the default as per the `config/ini
 length 100
 ```
 
-### order
+## order
 
 Sets the default order of table rows. The first argument is the column, the second the direction.
 
@@ -618,7 +633,7 @@ When not specified, effective_datatables will sort by the first defined column.
 order :created_at, :asc|:desc
 ```
 
-### reorder
+## reorder
 
 Enables drag-and-drop row re-ordering.
 
@@ -636,7 +651,7 @@ reorder :position
 
 Using `reorder` will sort the collection by this field and disable all other column sorting.
 
-### aggregate
+## aggregate
 
 The `aggregate` command inserts a row in the table's `tfoot`.
 
@@ -673,6 +688,30 @@ end.aggregate { |values, column| distance_of_time_in_words(values.min, values.ma
 
 In the above example, `values` is an Array containing all row's values for one column at a time.
 
+## download
+
+Add a Download button which streams a CSV file containing all rows and columns in the table's collection, ignoring any search, sort or filtering.
+
+This is an opt-in feature.
+
+To enable, please set `config.download = true` in your `config/initializers/effective_datatables.rb` file.
+
+Once enabled, you can disable it on an individual table by:
+
+```ruby
+datatable do
+  download false
+end
+```
+
+and you can exclude individual columns from being rendered on the CSV export
+
+```ruby
+col :first_name, csv: false
+```
+
+The column will still appear in the export, but the contents will be blank.
+
 ## filters
 
 Creates a single form with fields for each `filter` and a single radio input field for all `scopes`.
@@ -681,7 +720,7 @@ The form is submitted by an AJAX POST action, or, in some advanced circumstances
 
 Initialize the datatable in your controller or view, `@datatable = PostsDatatable.new(self)`, and render its filters anywhere with `<%= render_datatable_filters(@datatable) %>`.
 
-### scope
+## scope
 
 All defined scopes are rendered as a single radio button form field. Works great with the [effective_form_inputs](https://github.com/code-and-effect/effective_form_inputs) gem.
 
@@ -705,7 +744,7 @@ class Post < ApplicationRecord | ActiveRecord::Base
 end
 ```
 
-### filter
+## filter
 
 Each filter has a name and a default/fallback value. If the form is submitted blank, the default values are used.
 
@@ -758,7 +797,7 @@ Creates a single dropdown menu with a link to each action, download or content.
 
 Along with this section, you must put a `bulk_actions_col` somewhere in your `datatable do ... end` section.
 
-### bulk_action
+## bulk_action
 
 Creates a link that becomes clickable when one or more checkbox/rows are selected as per the `bulk_actions_col` column.
 
@@ -771,6 +810,12 @@ You can also specify `data-method: :get` to instead make a `GET` request with th
 ```ruby
 bulk_actions do
   bulk_action 'Approve all', bulk_approve_posts_path, data: { confirm: 'Approve all selected posts?' }
+
+  bulk_action 'Action 1 | ids encoded in params', action_1_posts_path, data: { method: :get }
+
+  bulk_action 'Action 2 | ids stored in _ids_ field in local storage', action_2_posts_path, data: { 'payload-mode' => 'local-storage', method: :get }
+
+  bulk_action 'Action 3 | ids stored in _ids_ field in a cookie', action_3_posts_path, data: { 'payload-mode' => 'cookie', method: :get }
 end
 ```
 
@@ -780,6 +825,9 @@ In your `routes` file:
 resources :posts do
   collection do
     post :bulk_approve
+    get :action_1
+    get :action_2
+    get :action_3
   end
 end
 ```
@@ -798,6 +846,22 @@ def bulk_approve
     render json: { status: 500, message: 'An error occured while approving a post.' }
   end
 end
+
+def action_1
+  @posts = Post.where(id: params[:ids])
+
+  render :some_partial
+end
+
+def action_2
+  @posts = Post.where(id: cookies[:ids].split(','))
+
+  render :some_partial
+end
+
+def action_3
+  render :some_partial # and get ids via JS:  localStorage.getItem('ids');
+end
 ```
 
 or if using [effective_resources](https://github.com/code-and-effect/effective_resources):
@@ -814,11 +878,11 @@ def approve!
 end
 ```
 
-### bulk_action_divider
+## bulk_action_divider
 
 Inserts a menu divider `<li class='divider' role='separator'></li>`
 
-### bulk_download
+## bulk_download
 
 So it turns out there are some http issues with using an AJAX action to download a file.
 
@@ -859,7 +923,7 @@ def bulk_export_report
 end
 ```
 
-### bulk_action_content
+## bulk_action_content
 
 Blindly inserts content into the dropdown.
 
@@ -873,12 +937,16 @@ end
 
 Don't actually use this.
 
-## charts
+# Charts
 
 Create a [Google Chart](https://developers.google.com/chart/interactive/docs/quick_start) based on your searched collection, filters and attributes.
 
 No javascript required. Just use the `chart do ... end` block and return an Array of Arrays.
 
+The first collection, `collection` is the raw results as returned from the `collection do` block.
+
+The second collection, `searched_collection` is the results after the table's search columns have been applied, but irregardless of pagination.
+
 ```ruby
 charts do
   chart :breakfast, 'BarChart' do |collection|
@@ -894,6 +962,18 @@ charts do
       [date.strftime('%F'), posts.length]
     end
   end
+
+  chart :posts_per_user, 'ColumnChart' do |collection, searched_collection|
+    measured_posts = if search.present?
+      ["Posts with #{search.map { |k, v| k.to_s + ' ' + v.to_s }.join(',')}", searched_collection.length]
+    else
+      ['All Posts', collection.length]
+    end
+
+    [['Posts', 'Count'], measured_posts] +
+    searched_collection.group_by(&:user).map { |user, posts| [user.last_name, posts.length] }
+  end
+
 end
 ```
 
@@ -914,11 +994,169 @@ All options passed to `chart` are used to initialize the chart javascript.
 
 By default, the only package that is loaded is `corechart`, see the `config/initializers/effective_datatables.rb` file to add more packages.
 
-## Extras
+# Inline
+
+Any datatable can be used as an inline datatable, to create, update and destroy resources without leaving the current page.
+
+If your datatable is already working with `actions_col` and being rendered from an `Effective::CrudController` controller, all you need to do is change your view from `render_datatable(@datatable)` to `render_datatable(@datatable, inline: true)`.
+
+Click here for a [Inline Live Demo](https://effective-datatables-demo.herokuapp.com/things) and here for an [Inline Code Example](https://github.com/code-and-effect/effective_datatables_demo)
+(only the `thing` data model and `things_datatable` are being used inline)
+
+To use effective_datatables as an inline CRUD builder, you will be relying heavily on [effective_resources](https://github.com/code-and-effect/effective_resources) which is a dependency of this gem. I would also recommend you install [effective_developer](https://github.com/code-and-effect/effective_developer) to get access to some scaffolds and generators. It's not required but I'm gonna use them in this example.
+
+Here is how I build rails models for inline datatable CRUD operations:
+
+1. Create a new model file `app/models/thing.rb`:
+
+```ruby
+class Thing < ApplicationRecord
+  belongs_to :user
+
+  effective_resource do
+    title           :string
+    description     :text
+    timestamps
+  end
+
+  scope :deep, -> { includes(:user) }
+  scope :sorted, -> { order(:title) }
+
+  def to_s
+    title
+  end
+end
+```
+
+The `effective_resource do` block comes from the [effective_resources](https://github.com/code-and-effect/effective_resources) gem and is used to build any permitted_params.
+
+2. Generate a migration. Run `rails generate effective:migration things` to create a migration based off the model file then `rails db:migrate`.
+
+3. Scaffold the rest. Run `rails generate effective:scaffold_controller things` which will create:
+
+- A controller `app/controllers/things_controller.rb`:
+
+```ruby
+class ThingsController < ApplicationController
+  include Effective::CrudController
+end
+```
+
+The Effective::CrudController comes from [effective_resources](https://github.com/code-and-effect/effective_resources) gem and handles the standard 7 CRUD actions and member and collection actions. It is opinionated code that follows rails conventions. It considers the `routes.rb` and `ability.rb` or other authorization, to find all available actions.
+
+- A datatable `app/datatables/things_datatable.rb`:
+
+```ruby
+class ThingsDatatable < Effective::Datatable
+  datatable do
+    col :title
+    col :description
+    actions_col
+  end
+
+  collection do
+    Thing.deep.all
+  end
+end
+```
+
+This is an ordinary datatable. As long as it's an ActiveRecord collection, inline crud will work.
+
+- A view partial `app/views/things/_thing.html.haml`:
+
+```ruby
+%table.table
+  %tbody
+    %tr
+      %th Title
+      %td= thing.title
+    %tr
+      %th Description
+      %td= thing.description
+```
+
+This file is what rails uses when you call `render(thing)` and what datatables uses for the inline `show` action. It's important that its called `_thing.html`.
+
+- A form partial `app/views/things/_form.html.haml`:
+
+```ruby
+= effective_form_with(model: thing) do |f|
+  = f.text_field :title
+  = f.text_area :description
+  = f.submit
+```
+
+The `effective_form_with` comes from [effective_bootstrap](https://github.com/code-and-effect/effective_bootstrap) gem and is a drop-in replacement for the newer `form_with` syntax. It's really good, you should use it, but an ordinary `form_with` will work here just fine.
+
+This `_form.html` is an effective gems convention. This file must exist for your resource.
+
+- A resources entry in `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  resources :things do
+    post :approve, on: :member
+    post :reject, on: :member
+  end
+end
+```
+
+Above we have `resources :things` for the 7 crud actions. And we add two more member actions, which datatables will call `approve!` or `reject!` on thing.
+
+
+4. Render in the view. Create an `app/views/things/index.html.haml` and call `render_datatable(@datatable, inline: true)` or `render_inline_datatable(@datatable).
+
+```ruby
+= render_datatable(@datatable, inline: true)
+```
+
+Your datatable should now have New, Show, Edit, Approve and Reject buttons. Click them for inline functionality.
+
+## Troubleshooting Inline
+
+If things aren't working, try the following:
+
+- Double check your javascripts:
+
+```ruby
+//= require jquery3
+//= require popper
+//= require bootstrap
+//= require effective_bootstrap
+//= require effective_datatables
+//= require jquery_ujs
+```
+
+The inline functionality requires one of sprockets jquery_ujs, sprockets rails_ujs or webpack @rails/ujs libraries.
+
+- Double check your stylesheets:
+
+```ruby
+@import 'bootstrap';
+@import 'effective_bootstrap';
+@import 'effective_datatables';
+```
+
+- Make sure your datatable is not being rendered inside a `<form>...</form>` tag. It will display a javascript console error and won't work.
+
+- Double check your `resources :things` are in `routes.rb` in the same namespace as the controller, and that you have authorization for those actions in `ability.rb` or whatever your `config/initializers/effective_datatables.rb` `config.authorization_method` returns.
+
+## A note on how it works
+
+We use good old `rails_ujs` for all inline actions.
+
+When inline, any of the actions_col actions, as well as the New button, will be changed into `data-remote: true` actions.
+
+The [inline_crud javascript](https://github.com/code-and-effect/effective_datatables/blob/master/app/assets/javascripts/effective_datatables/inline_crud.js.coffee) handles fetching the form, or view partial and expanding/collapsing the appropriate row of the datatable.
+
+When an inline action is clicked, effective_datatables will make an AJAX request to the server, which could be received by an `Effective::CrudController` that will handle the `.js` format, and respond_with the appropriate [rails_ujs .js.erb views](https://github.com/code-and-effect/effective_resources/tree/master/app/views/application).
+
+
+# Extras
 
 The following commands don't quite fit into the DSL, but are present nonetheless.
 
-### simple
+## simple
 
 To render a simple table, without pagination, sorting, filtering, export buttons, per page, and default visibility:
 
@@ -926,7 +1164,7 @@ To render a simple table, without pagination, sorting, filtering, export buttons
 <%= render_datatable(@datatable, simple: true) %>
 ```
 
-### index
+## index
 
 If you just want to render a datatable and nothing else, there is a quick way to skip creating a view:
 
@@ -940,13 +1178,13 @@ end
 
 will render `views/effective/datatables/index` with the assigned datatable.
 
-## Advanced Search and Sort
+# Advanced Search and Sort
 
 The built-in search and ordering can be overridden on a per-column basis.
 
 The only gotcha here is that you must be aware of the type of collection.
 
-### With ActiveRecord collection
+## With ActiveRecord collection
 
 In the case of a `col` and an ActiveRecord collection:
 
@@ -978,7 +1216,7 @@ If `column[:sql_column].blank?` then this `col` has fallen back to being a `val`
 
 Try adding `col :post_category, sql_column: 'post_categories.title'`
 
-### With Array collection
+## With Array collection
 
 And in the case of a `col` with an Array collection, or any `val`:
 
@@ -1017,7 +1255,7 @@ end
 
 The search and sort for each column will be merged together to form the final results.
 
-### Default search collection
+## Default search collection
 
 When using a `col :comments` type belongs_to or has_many column, a search collection for that class will be loaded.
 
@@ -1139,6 +1377,22 @@ def finalize(collection)
 end
 ```
 
+## Render outside of view
+
+You can render a datatable outside the view.
+
+Anything you pass to the `rendered` method is treated as view/request params.
+
+You can test filters and scopes by passing them here.
+
+```
+post = Post.create!
+datatable = PostsDatatable.new.rendered(end_date: Time.zone.now+2.days, current_user_id: 1)
+
+assert_equal 1, datatable.collection.count
+assert_equal [post], datatable.collection
+```
+
 ## Authorization
 
 All authorization checks are handled via the config.authorization_method found in the `config/initializers/effective_datatables.rb` file.

data/app/assets/javascripts/effective_datatables/bulk_actions.js.coffee

@@ -19,11 +19,12 @@ $(document).on 'change', ".dataTables_wrapper input[data-role='bulk-actions']",
 
 toggleDropdown = ($wrapper) ->
   $bulkActions = $wrapper.children().first().find('.buttons-bulk-actions').children('button')
+  selected = $wrapper.find("input[data-role='bulk-action']:checked").length
 
-  if $wrapper.find("input[data-role='bulk-action']:checked").length > 0
-    $bulkActions.removeAttr('disabled')
+  if selected > 0
+    $bulkActions.removeAttr('disabled').text("Bulk Actions (#{selected} items)")
   else
-    $bulkActions.attr('disabled', 'disabled')
+    $bulkActions.attr('disabled', 'disabled').text('Bulk Actions')
 
 restoreSelected = ($table, selected) ->
   $bulkActions = $table.closest('.dataTables_wrapper').children().first().find('.buttons-bulk-actions').children('button')
@@ -41,11 +42,25 @@ restoreSelected = ($table, selected) ->
 
   if present then $bulkActions.removeAttr('disabled') else $bulkActions.attr('disabled', 'disabled')
 
-#### Bulk Action link behaviour
+# rails_ujs data-confirm requires special attention
+# https://github.com/rails/rails/blob/main/actionview/app/assets/javascripts/rails-ujs/features/confirm.coffee
+$(document).on 'confirm:complete', '.dataTables_wrapper .buttons-bulk-actions a', (event) ->
+  if event.originalEvent.detail && event.originalEvent.detail[0] == true
+    doBulkActionPost(event)
+    (window.Rails || $.rails).stopEverything(event)
+    return false
+
 $(document).on 'click', '.dataTables_wrapper .buttons-bulk-actions a', (event) ->
-  event.preventDefault() # prevent the click
+  unless $(event.currentTarget).data('confirm')
+    doBulkActionPost(event)
+    event.preventDefault()
+
+doBulkActionPost = (event) ->
+  $bulkAction = $(event.currentTarget)  # This is the regular <a href=...> tag maybe with data-confirm
+
+  document.cookie = 'ids=; expires=Thu, 01 Jan 1970 00:00:00 GMT'
+  localStorage.removeItem('ids')
 
-  $bulkAction = $(event.currentTarget)  # This is a regular <a href=...> tag
   $wrapper = $bulkAction.closest('.dataTables_wrapper')
   $table = $wrapper.find('table.dataTable').first()
   $processing = $table.siblings('.dataTables_processing').first()
@@ -54,6 +69,7 @@ $(document).on 'click', '.dataTables_wrapper .buttons-bulk-actions a', (event) -
   url = $bulkAction.attr('href')
   title = $bulkAction.text()
   download = $bulkAction.data('bulk-download')
+  payload_mode = $bulkAction.data('payload-mode')
   token = $table.data('authenticity-token')
   values = $.map($selected, (input) -> input.getAttribute('value'))
   method = $bulkAction.data('ajax-method')
@@ -61,10 +77,17 @@ $(document).on 'click', '.dataTables_wrapper .buttons-bulk-actions a', (event) -
   return unless url && values
 
   if method == 'GET'
-    if url.includes('?')
-      window.location.assign(url + '&' + $.param({ids: values}))
+    if payload_mode == 'cookie'
+      document.cookie = "ids=#{values}";
+      window.location.assign(url)
+    else if payload_mode == 'local-storage'
+      localStorage.setItem('ids', values);
+      window.location.assign(url)
     else
-      window.location.assign(url + '?' + $.param({ids: values}))
+      if url.includes('?')
+        window.location.assign(url + '&' + $.param({ids: values}))
+      else
+        window.location.assign(url + '?' + $.param({ids: values}))
 
     return
 

data/app/assets/javascripts/effective_datatables/download.js.coffee

@@ -0,0 +1,10 @@
+$(document).on 'click', '.dataTables_wrapper a.buttons-download', (event) ->
+  $button = $(event.currentTarget)
+  $table = $('#' + $button.attr('aria-controls'))
+
+  url = $table.data('source').replace('.json', '/download.csv')
+  attributes = 'attributes=' + encodeURIComponent($table.data('attributes'))
+
+  $button.attr('href', url + '?' + attributes)
+
+  setTimeout (=> $button.attr('href', 'download.csv')), 0

data/app/assets/javascripts/effective_datatables/flash.js.coffee

@@ -16,7 +16,7 @@ flash = (message, status = '') ->
   timeout = $processing.data('timeout')
   clearTimeout(timeout) if timeout
 
-  delay = (if status == 'danger' then 4000 else 1500)
+  delay = (if status == 'danger' then 4000 else 1000)
 
   $processing.html(message).data('timeout', setTimeout( =>
       $processing.html('Processing...')