datagrid 1.6.2 → 1.7.0

data/lib/datagrid/helper.rb

@@ -4,30 +4,28 @@ require "action_view"
 module Datagrid
   module Helper
 
-    # Returns individual cell value from the given grid, column name and model
-    # Allows to render custom HTML layout for grid data
-    #
+    # @param grid [Datagrid] grid object
+    # @param column [Datagrid::Columns::Column, String, Symbol] column name
+    # @param model [Object] an object from grid scope
+    # @return [Object] individual cell value from the given grid, column name and model
+    # @example
     #   <ul>
     #     <% @grid.columns.each do |column|
     #       <li><%= column.header %>: <%= datagrid_value(@grid, column.name, @resource %></li>
     #     <% end %>
     #   </ul>
-    #
-    def datagrid_value(grid, column_name, model)
-      datagrid_renderer.format_value(grid, column_name, model)
+    def datagrid_value(grid, column, model)
+      datagrid_renderer.format_value(grid, column, model)
     end
 
-    def datagrid_format_value(grid, column_name, model) #:nodoc:
-      datagrid_value(grid, column_name, model)
+    # @!visibility private
+    def datagrid_format_value(grid, column, model)
+      datagrid_value(grid, column, model)
     end
 
     # Renders html table with columns defined in grid class.
     # In the most common used you need to pass paginated collection
     # to datagrid table because datagrid do not have pagination compatibilities:
-    #
-    #   assets = grid.assets.page(params[:page])
-    #   datagrid_table(grid, assets, options)
-    #
     # Supported options:
     #
     # * <tt>:html</tt> - hash of attributes for <table> tag
@@ -38,8 +36,14 @@ module Datagrid
     #   and needs different columns. Default: all defined columns.
     # * <tt>:partials</tt> - Path for partials lookup.
     #   Default: 'datagrid'.
-    def datagrid_table(grid, *args)
-      datagrid_renderer.table(grid, *args)
+    # @param grid [Datagrid] grid object
+    # @param assets [Array] objects from grid scope
+    # @return [String] table tag HTML markup
+    # @example
+    #   assets = grid.assets.page(params[:page])
+    #   datagrid_table(grid, assets, options)
+    def datagrid_table(grid, assets = grid.assets, **options)
+      datagrid_renderer.table(grid, assets, **options)
     end
 
     # Renders HTML table header for given grid instance using columns defined in it
@@ -50,6 +54,8 @@ module Datagrid
     #   Default: true
     # * <tt>:partials</tt> - Path for partials lookup.
     #   Default: 'datagrid'.
+    # @param grid [Datagrid] grid object
+    # @return [String] HTML table header tag markup
     def datagrid_header(grid, options = {})
       datagrid_renderer.header(grid, options)
     end
@@ -66,6 +72,7 @@ module Datagrid
     # * <tt>:partials</tt> - Path for partials lookup.
     #   Default: 'datagrid'.
     #
+    # @example
     #   = datagrid_rows(grid) # Generic table rows Layout
     #
     #   = datagrid_rows(grid) do |row| # Custom Layout
@@ -93,21 +100,30 @@ module Datagrid
     # * <tt>:partials</tt> - Path for form partial lookup.
     #   Default: 'datagrid'.
     # * All options supported by Rails <tt>form_for</tt> helper
+    # @param grid [Datagrid] grid object
+    # @return [String] form HTML tag markup
     def datagrid_form_for(grid, options = {})
       datagrid_renderer.form_for(grid, options)
     end
 
     # Provides access to datagrid columns data.
-    #
-    #   # Suppose that <tt>grid</tt> has first_name and last_name columns
+    # Used in case you want to build html table completelly manually
+    # @param grid [Datagrid] grid object
+    # @param asset [Object] object from grid scope
+    # @param block [Proc] block with Datagrid::Helper::HtmlRow as an argument returning a HTML markup as a String
+    # @return [Datagrid::Helper::HtmlRow, String] captured HTML markup if block given otherwise row object
+    # @example
+    #   # Suppose that grid has first_name and last_name columns
     #   <%= datagrid_row(grid, user) do |row| %>
     #     <tr>
     #       <td><%= row.first_name %></td>
     #       <td><%= row.last_name %></td>
     #     </tr>
     #   <% end %>
-    #
-    # Used in case you want to build html table completelly manually
+    # @example
+    #   <% row = datagrid_row(grid, user) %>
+    #   First Name: <%= row.first_name %>
+    #   Last Name: <%= row.last_name %>
     def datagrid_row(grid, asset, &block)
       HtmlRow.new(self, grid, asset).tap do |row|
         if block_given?
@@ -117,37 +133,47 @@ module Datagrid
     end
 
     # Generates an ascending or descending order url for the given column
+    # @param grid [Datagrid] grid object
+    # @param column [Datagrid::Columns::Column, String, Symbol] column name
+    # @param descending [Boolean] specifies order direction. Ascending if false, otherwise descending.
+    # @return [String] order layout HTML markup
     def datagrid_order_path(grid, column, descending)
       datagrid_renderer.order_path(grid, column, descending, request)
     end
 
     # Represents a datagrid row that provides access to column values for the given asset
-    #
+    # @example
     #   row = datagrid_row(grid, user)
+    #   row.class      # => Datagrid::Helper::HtmlRow
     #   row.first_name # => "<strong>Bogdan</strong>"
     #   row.grid       # => Grid object
     #   row.asset      # => User object
+    #   row.each do |value|
+    #     puts value
+    #   end
     class HtmlRow
 
       include Enumerable
 
       attr_reader :grid, :asset
 
-      def initialize(context, grid, asset) # :nodoc:
+      # @!visibility private
+      def initialize(context, grid, asset)
         @context = context
         @grid = grid
         @asset = asset
       end
 
-      # Return a column value for given column name
+      # @return [Object] a column value for given column name
       def get(column)
         @context.datagrid_value(@grid, column, @asset)
       end
 
       # Iterates over all column values that are available in the row
-      def each
+      # param block [Proc] column value iterator
+      def each(&block)
         @grid.columns.each do |column|
-          yield(get(column))
+          block.call(get(column))
         end
       end
 

data/lib/datagrid/ordering.rb

@@ -1,10 +1,12 @@
 require "datagrid/columns"
 
 module Datagrid
+  # Raised when grid order value is incorrect
   class OrderUnsupported < StandardError
   end
   module Ordering
 
+    # @!visibility private
     def self.included(base)
       base.extend         ClassMethods
       base.class_eval do
@@ -26,38 +28,37 @@ module Datagrid
 
       end
       base.send :include, InstanceMethods
-    end # self.included
+    end
 
+    # @!visibility private
     module ClassMethods
-
       def order_unsupported(name, reason)
         raise Datagrid::OrderUnsupported, "Can not sort #{self.inspect} by ##{name}: #{reason}"
       end
-
-    end # ClassMethods
+    end
 
     module InstanceMethods
 
-      def assets # :nodoc:
+      # @!visibility private
+      def assets
         check_order_valid!
         apply_order(super)
       end
 
-      # Returns a column definition that is currently used to order assets
-      #
+      # @return [Datagrid::Columns::Column, nil] a column definition that is currently used to order assets
+      # @example
       #   class MyGrid
       #     scope { Model }
       #     column(:id)
       #     column(:name)
       #   end
-      #   MyGrid.new(:order => "name").order_column # => #<Column name: "name", ...>
-      #
+      #   MyGrid.new(order: "name").order_column # => #<Column name: "name", ...>
       def order_column
-        order && column_by_name(order)
+        order ? column_by_name(order) : nil
       end
 
-      # Returns true if given grid is ordered by given column.
-      # <tt>column</tt> can be given as name or as column object
+      # @param column [String, Datagrid::Columns::Column]
+      # @return [Boolean] true if given grid is ordered by given column.
       def ordered_by?(column)
         order_column == column_by_name(column)
       end
@@ -127,7 +128,6 @@ module Datagrid
           self.class.order_unsupported(order_column.name, "Order option proc can not handle more than one argument")
         end
       end
-    end # InstanceMethods
-
+    end
   end
 end

data/lib/datagrid/renderer.rb

@@ -1,7 +1,8 @@
 require "action_view"
 
 module Datagrid
-  class Renderer #:nodoc:
+  # @!visibility private
+  class Renderer
 
     def self.for(template)
       new(template)
@@ -34,11 +35,9 @@ module Datagrid
       _render_partial('form', options[:partials], {:grid => grid, :options => options})
     end
 
-    def table(grid, *args)
-      options = args.extract_options!
+    def table(grid, assets, **options)
       options[:html] ||= {}
       options[:html][:class] ||= "datagrid #{@template.dom_class(grid)}"
-      assets = args.any? ? args.shift : grid.assets
 
       _render_partial('table', options[:partials],
                       {

data/lib/datagrid/scaffold.rb

@@ -124,6 +124,6 @@ RUBY
 
   def file_exists?(name)
     name = Rails.root.join(name) unless name.to_s.first == "/"
-    File.exists?(name)
+    File.exist?(name)
   end
 end

data/lib/datagrid/utils.rb

@@ -1,4 +1,5 @@
 module Datagrid
+  # @!visibility private
   module Utils # :nodoc:
     class << self
 

data/lib/datagrid/version.rb

@@ -1,3 +1,3 @@
 module Datagrid
-  VERSION = "1.6.2"
+  VERSION = "1.7.0"
 end

data/lib/datagrid.rb

@@ -23,6 +23,7 @@ module Datagrid
 
   autoload :Engine
 
+  # @!visibility private
   def self.included(base)
     base.class_eval do
 
@@ -34,7 +35,7 @@ module Datagrid
       include ::Datagrid::Ordering
 
     end
-  end # self.included
+  end
 
   class ConfigurationError < StandardError; end
   class ArgumentError < ::ArgumentError; end

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: datagrid
 version: !ruby/object:Gem::Version
-  version: 1.6.2
+  version: 1.7.0
 platform: ruby
 authors:
 - Bogdan Gusiev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-09-07 00:00:00.000000000 Z
+date: 2023-01-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '6.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '6.0'
 description: This allows you to easily build datagrid aka data tables with sortable
   columns and filters
 email: agresso@gmail.com
@@ -90,7 +90,7 @@ files:
 - templates/controller.rb.erb
 - templates/grid.rb.erb
 - templates/index.html.erb
-homepage: http://github.com/bogdan/datagrid
+homepage: https://github.com/bogdan/datagrid
 licenses:
 - MIT
 metadata:
@@ -107,14 +107,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.0'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.0
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Ruby gem to create datagrids