trk_datatables 0.2.13 → 0.2.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfebccd40ad802ae6e7e6beb1eebec9099f9ede5bf4ed4d2f6f9ed92a08a8f03
-  data.tar.gz: 0fcb0efd54b898d2d2aa68ff76c095293fa0b57abb48a37bd893aa59a676ff4e
+  metadata.gz: 0d7a8767e7c4b77bbdd9d47b478de7b6b3dd456c449e83e50a70c4b674121fa7
+  data.tar.gz: aedc1d098b6ddd648a7b18fbf99cc88dede84f63a63c7ececa704fcb8bb0d018
 SHA512:
-  metadata.gz: fa204f488a45f055b602e9baf8504cd64e8a91404a69800588065fcabbfa5a85ce2ae9220751fdf7633facdfe1627a98bae33354eabfaf6c64e9053f20f6472a
-  data.tar.gz: ba2fbe421642ed72bff9e023b541c4321c56baa653f54f1ac372d3e7d43233691a7316040340ff20c94e1d4fab6ceb5ce314fe0efeadfa65240e2dee2042593e
+  metadata.gz: 890f228e839a1e25ab96db11cf92c2b9a328be57f49e202ad77d2071b2c4ccdec65c31bcb57f5743c3fabbca00cb0f941c9df15364025413a73616e23b906095
+  data.tar.gz: 9a6744711a901ea792c54633f4eac570a36c9547f8e86f9d112f4ed175d5f7838f33ccb2b33b529cde15f82bd7184edaec881056afb88f183b1df203b8139fa9

data/Gemfile.lock

@@ -1,39 +1,45 @@
 PATH
   remote: .
   specs:
-    trk_datatables (0.2.13)
+    trk_datatables (0.2.15)
       activesupport
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activemodel (6.0.0)
-      activesupport (= 6.0.0)
-    activerecord (6.0.0)
-      activemodel (= 6.0.0)
-      activesupport (= 6.0.0)
-    activesupport (6.0.0)
+    activemodel (6.1.7.2)
+      activesupport (= 6.1.7.2)
+    activerecord (6.1.7.2)
+      activemodel (= 6.1.7.2)
+      activesupport (= 6.1.7.2)
+    activesupport (6.1.7.2)
       concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 0.7, < 2)
-      minitest (~> 5.1)
-      tzinfo (~> 1.1)
-      zeitwerk (~> 2.1, >= 2.1.8)
-    byebug (11.0.1)
-    concurrent-ruby (1.1.5)
-    database_cleaner (1.7.0)
-    i18n (1.6.0)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    byebug (11.1.3)
+    concurrent-ruby (1.2.0)
+    database_cleaner (2.0.1)
+      database_cleaner-active_record (~> 2.0.0)
+    database_cleaner-active_record (2.0.1)
+      activerecord (>= 5.a)
+      database_cleaner-core (~> 2.0.0)
+    database_cleaner-core (2.0.1)
+    i18n (1.12.0)
       concurrent-ruby (~> 1.0)
-    minitest (5.12.0)
+    mini_portile2 (2.8.1)
+    minitest (5.17.0)
     minitest-color (0.0.2)
       minitest (~> 5)
-    pg (1.1.4)
+    pg (1.4.5)
     rake (10.5.0)
-    sqlite3 (1.4.1)
-    thread_safe (0.3.6)
-    timecop (0.9.4)
-    tzinfo (1.2.5)
-      thread_safe (~> 0.1)
-    zeitwerk (2.1.10)
+    sqlite3 (1.6.0)
+      mini_portile2 (~> 2.8.0)
+    timecop (0.9.6)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    zeitwerk (2.6.6)
 
 PLATFORMS
   ruby

data/README.md

@@ -96,7 +96,7 @@ module.exports = environment
     <%= javascript_pack_tag 'application', 'data-turbolinks-track': 'reload' %>
     <%# we need stylesheet for production server, locally it could work without stylesheet_pack_tag even in production mode %>
     <%= stylesheet_pack_tag 'application', 'data-turbolinks-track': 'reload' %>
-    <%# we use jQuery from wepbacker so asset pipeline should be included later %>
+    <%# we use jQuery from wepbacker so asset pipeline should be included later if you use asset pipeline %>
     <%= javascript_include_tag 'application', 'data-turbolinks-track': 'reload' %>
 ```
 
@@ -106,7 +106,7 @@ Than add a gem and sample PostsDatatable
 # Gemfile
 gem 'trk_datatables'
 
-# in console
+# in console you can use rails generator to generate app/datatables/xxx_datatable.rb
 bundle
 rails g trk_datatables post
 vi app/datatables/posts_datatable.rb
@@ -153,7 +153,7 @@ class PostsDatatable < TrkDatatables::ActiveRecord
     Post.left_joins(:user)
   end
 
-  def rows(filtered)
+  def rows(filtered) # rubocop:disable Metrics/MethodLength
     filtered.map do |post|
       [
         @view.link_to(post.title, post),
@@ -217,6 +217,9 @@ method.
 class PostsDatatable < TrkDatatables::ActiveRecord
   def global_search_columns
     # in addition to columns those fields will be used to match global search
+    # instead Post.all you should use Post.joins(:user) or
+    # Post.left_joins(:user) if user is optional. For has_many relations you
+    # need to join them since you will get multiple table rows
     %w[posts.body users.name]
   end
 end
@@ -256,7 +259,9 @@ For specific columns you can use following keys
 * `order: false` disable ordering for this column
 * `select_options: Post.statuses` generate select box instead of text input
 * `predefined_ranges: {}` for datetime fiels add ranges to pick up from
-* `hide: true` hide column with display none, for example `{ hide: @view.params[:user_id].present? }`
+* `hide: true` hide column with display none, for example `{ hide:
+  @view.params[:user_id].present? }`, note that you should send that column data
+  anyway, just it will not be visible
 * `class_name: 'Admin::User'` use different class name than
   `table_name.classify` (in this case of `admin_users` will be `AdminUser`)
 * `column_type_in_db` one of the: `:string`, `:integer`, `:date`, `:datetime`,
@@ -391,6 +396,15 @@ nor in Ruby code.
   end
 ```
 
+You can access filtered items for example
+```
+  def totals
+    filter_by_columns all_items
+    filter_by_search_all filter_by_columns all_items # this is actually filtered_items
+    order_and_paginate_items filter_by_search_all filter_by_columns all_items # this is ordered_paginated_filtered_items
+  end
+```
+
 ### Values calculated in database
 
 There are three types of calculated values (new custom fields that are
@@ -402,22 +416,64 @@ generated based on other columns):
   posts_count FROM "users" LEFT OUTER JOIN "posts" ON "posts"."user_id" =
   "users"."id" GROUP BY users.id`
 
+Simple calculations and subqueries works fine, you can search and order by them.
+Note that when you use join with other table, than you should group by all
+columns that you have used as columns which can be ordered by, for example
+```
+# app/datatables/member_profiles_datatable.rb
+  def columns
+    {
+      'member_profiles.full_name': {},
+      'users.email': {},
+      'users.current_sign_in_at': {},
+    }
+  end
+  def all_items
+    MemberProfile
+      .joins(:user)
+      .group("member_profiles.id")
+      .group("users.email")
+      .group("users.current_sign_in_at")
+   end
+```
+otherwise the error like
+`PG::GroupingError: ERROR:  column "users.current_sign_in_at" must appear in the
+GROUP BY clause or be used in an aggregate function`
+You should test by searching and selecting each column as sortable column.
+```
+# test/controllers/admin/member_profiles_controller_test.rb
+  test "#search when order by is by each defined column" do
+    columns = MemberProfilesDatatable.new(OpenStruct.new(params: {})).columns
+
+    columns.each_with_index do |_column_key_option, index|
+      post search_superadmin_member_profiles_path(search: { value: "foo" }, order: { "0": { column: index, dir: "asc" } })
+      assert_response :success
+    end
+  end
+```
+
 Since in SQL you can not use aggregate functions in WHERE (we should repeat
 calculation and subqueries), currently TrkDatatables does not support using
-aggregate functions since it requires implementation of `HAVING` (unless you
-disable search and order for those fields with aggregate functions
-`'users.posts_count': { search: false, order: false }`).
-You can use concatenation aggregate function: in postgres `STRING_AGG`, in mysql
-`GROUP_CONCAT` so in this case we search on real columns. For example let's we
-have `Post.select(%(posts.*, GROUP_CONCAT(comments.body) AS
-comments_body)).left_outer_joins(:comments) .group('posts.id')` and that we have
-a row `postName, comment1, comment2` than when we searh for `comment2` we will
-get a row `postName, comment2`.
+aggregate functions since it requires implementation of `HAVING` so when you use
+aggregate functions you need to disable search and order for those fields with
+aggregate functions `'users.posts_count': { search: false, order: false }`).
+
+You can use concatenation aggregate function: in postgres
+`STRING_AGG(comments.body, ' ') comments_body`, in mysql `GROUP_CONCAT` so in
+this case we search on real columns. For example let's we have
+```
+Post
+  .select(%(posts.*, GROUP_CONCAT(comments.body) AS comments_body))
+  .left_outer_joins(:comments)
+  .group('posts.id')
+```
+and that we have a row `postName, comment1, comment2` than when we searh for
+`comment2` we will get a row `postName, comment2`.
 
 Simple calculations and subqueries works fine, just you have to use public
 method to define calculation (that method is also used in filtering). Name of
-method is the same as column name `title_and_body` or `comments_count`. For table
-name you should use one of:
+method is the same as column name `title_and_body` or `comments_count`. For
+table name you should use one of:
 `:string_calculated_in_db`, `:integer_calculated_in_db`,
 `:date_calculated_in_db`, `:datetime_calculated_in_db` or
 `:boolean_calculated_in_db`.
@@ -487,7 +543,7 @@ class MostLikedPostsDatatable < TrkDatatables::ActiveRecord
     Post.select(%(
                 posts.*,
                 #{title_and_body} AS title_and_body,
-                (#{comments_count}) AS comments_count
+                #{comments_count} AS comments_count
                 ))
   end
 
@@ -501,8 +557,10 @@ class MostLikedPostsDatatable < TrkDatatables::ActiveRecord
   # you have { search: false }
   def comments_count
     <<~SQL
-      (SELECT COUNT(*) FROM comments
-      WHERE comments.post_id = posts.id)
+     (
+      SELECT COUNT(*) FROM comments
+      WHERE comments.post_id = posts.id
+     )
     SQL
   end
 
@@ -525,8 +583,11 @@ class MostLikedPostsDatatable < TrkDatatables::ActiveRecord
     end
   end
 
+  # You can use this in config/initializers/trk_datatables.rb
+  # class TrkDatatables::ActiveRecord; def default_order;
+  # or put in specific datatable class like here
   def default_order
-    [[2, :desc]]
+    [[columns.size - 1, :desc]]
   end
 end
 ```
@@ -619,6 +680,43 @@ calculated_ columns is used than it can not find translation so better is to:
       'string_calculated_in_db.column_value_translated': {search: false, title: @view.t('activerecord.attributes.translation.column_value_translated')},
 ```
 
+Note that when you have two associations to the same class, for example
+`Interest` has `:from_member_profile` and `:to_member_profile` you can use
+search for the first column, but for the second you should use
+`string_calculated_in_db` and inside method use table name that is generated in
+joins like `to_member_profiles_interests` (trk_datatable can not determine which
+class is this, in order to find its column)
+```
+# app/models/interest.rb
+class Interest < ApplicationRecord
+  belongs_to :from_member_profile, class_name: 'MemberProfile'
+  belongs_to :to_member_profile, class_name: 'MemberProfile'
+end
+
+# app/datatables/interests_datatable.rb
+class InterestsDatatable < TrkDatatables::ActiveRecord
+  def columns
+    {
+      'member_profiles.full_name': {},
+      'string_calculated_in_db.to_member_profiles_interests_full_name': {},
+      # if we want to search by this column than we can not use
+      # "to_member_profiles_interests.full_name": {},
+      # since we can not find that class and its arel_table
+   }
+  end
+
+  def to_member_profiles_interests_full_name
+    "to_member_profiles_interests.full_name"
+  end
+
+  def all_items
+    Interest
+      .joins(:from_member_profile) # this will be "member_profiles" table in sql
+      .joins(:to_member_profile) # this will be "to_member_profiles_interests"
+   end
+end
+```
+
 ### Default order and page length
 
 You can override default order (index and direction) and default page length so
@@ -628,10 +726,11 @@ save preferences) and this default values will be used
 ```
 # app/datatables/posts_datatable.rb
 class PostsDatatable
-  # when we show some invoice_no on first column, and that is reset every year
-  # on first april, thatn it is better is to use date column ordering
+  # when we show invoice_no on first column, and that is reset every year
+  # on first april, than it is better is to use date column ordering
+  # column starts from zero 0, 1, 2, 3
   def default_order
-    [[3, :desc]]
+    [[columns.size - 1, :desc]]
   end
 
   def default_page_length
@@ -768,6 +867,15 @@ You can set filters on datatable even params are blank, for example
 
 Inside datatable you can access params using `@view.params`
 
+To set the order (custom sort) in a link you can use:
+```
+<%= link_to 'Sort by email', \
+      posts_path(
+        PostsDatatable.order_set('users.email', :desc)
+      )
+%>
+```
+
 ### Saved Preferences (optional)
 
 You can save column order and page length in User.preferences field so
@@ -796,7 +904,7 @@ class PostsDatatable
 end
 ```
 
-It will store order and page lenght inside `dt_preferences` on
+It will store order and page length inside `dt_preferences` on
 `user.preferences`.
 
 ### Additional data to json response
@@ -892,7 +1000,7 @@ link_to 'Active', search_posts_path(PostsDatatable.param_set('posts.status',
 Here is example how you can test
 
 ```
-# test/datatables/happ
+# test/datatables/posts_datatable_test.rb
 require 'test_helper'
 
 class PostsDatatableTest < ActiveSupport::TestCase
@@ -911,6 +1019,27 @@ class PostsDatatableTest < ActiveSupport::TestCase
 end
 ```
 
+You can also write controller test
+```
+# test/controllers/posts_controller_test.rb
+require 'test_helper'
+
+class PostsControllerTest < ActiveSupport::TestCase
+  test "#index" do
+    get posts_path
+    assert_response :success
+  end
+
+  test "#search" do
+    post = posts(:post)
+    post search_posts_path(search: { value: post.title })
+    assert_response :success
+    response_json = JSON.parse response.body
+    assert_equal 1, response_json["data"].size
+  end
+end
+```
+
 ## Exceptions
 
 To catch errors from TrkDatables you can
@@ -1026,6 +1155,13 @@ rm -rf .yardoc/
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/trkin/trk_datatables. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
+## TODOs
+
+Column filtering with dropdowns https://datatables.net/extensions/searchpanes/examples/advanced/columnFilter.html
+Adding graphs https://datatables.net/forums/discussion/comment/123621/#Comment_123621
+https://datatables.net/examples/api/highcharts.html
+
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/trk_datatables/active_record.rb

@@ -121,7 +121,11 @@ module TrkDatatables
         column_key_option = @column_key_options[index]
         next if column_key_option[:column_options][ColumnKeyOptions::ORDER_OPTION] == false
 
-        queries << "#{column_key_option[:column_key]} #{direction}"
+        queries << if column_key_option[:table_class] < TrkDatatables::CalculatedInDb
+                     "#{send(column_key_option[:column_key])} #{direction}"
+                   else
+                     "#{column_key_option[:column_key]} #{direction}"
+                   end
       end
       filtered.order(Arel.sql(order_by.join(', ')))
     end

data/lib/trk_datatables/base_helpers.rb

@@ -21,6 +21,18 @@ module TrkDatatables
       DtParams.param_set column_index, value
     end
 
+    # Set sort for column. This is class method so you do not need
+    # datatable instance.
+    #
+    # @example
+    #   link_to 'Sort by email',
+    #   posts_path(PostsDatatable.order_set('users.email', :desc)
+    def order_set(column_key, direction = :asc, view = nil)
+      datatable = new view || OpenStruct.new(params: {})
+      column_index = datatable.index_by_column_key column_key
+      DtParams.order_set column_index, direction
+    end
+
     # Get the form field name for column. This is class method so you do not
     # need datatable instance. It returns something like
     # 'column[3][search][value]`. For global search you can use

data/lib/trk_datatables/dt_params.rb

@@ -110,6 +110,10 @@ module TrkDatatables
       {columns: {column_index.to_s => {search: {value: value}}}}
     end
 
+    def self.order_set(column_index, direction)
+      {order: {'0': {column: column_index, dir: direction}}}
+    end
+
     def self.form_field_name(column_index)
       "columns[#{column_index}][search][value]"
     end

data/lib/trk_datatables/version.rb

@@ -1,3 +1,3 @@
 module TrkDatatables
-  VERSION = '0.2.13'.freeze
+  VERSION = '0.2.15'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trk_datatables
 version: !ruby/object:Gem::Version
-  version: 0.2.13
+  version: 0.2.15
 platform: ruby
 authors:
 - Dusan Orlovic
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-05-11 00:00:00.000000000 Z
+date: 2023-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -205,7 +205,7 @@ metadata:
   source_code_uri: https://github.com/trkin/trk_datatables
   changelog_uri: https://github.com/trkin/trk_datatables/blob/master/CHANGELOG.md
   yard.run: yri
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -221,7 +221,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.2.15
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Gem that simplify using datatables with Ruby on Rails and Sinatra.
 test_files: []