ajax_table_rails 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 135199e12d3994cb2cd2ca99096927029366910b
+  data.tar.gz: c73f7a30edcd5f8b9685577b7d048d91b3f1a180
+SHA512:
+  metadata.gz: 9ca2d2d538d6a6e1ae355d68bbfb3502b4de9370905ca02603a2bc9fb1353b71ca57d92474b072d9f2649f20cd8fbe9dbef45e7e287cdabaa4c0983e1526dd5f
+  data.tar.gz: 536c0b373cc3959ed3c10ab27916079b824dce0f64aea7081ecbf1bd4e23adf1e8999f0ae3d4a576a3693282ec62330b00f27a3b329f898a0c93a2fcf97d64e1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## v0.0.1
+
+* Initial release

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Declare your gem's dependencies in ajax_table_rails.gemspec.
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2014 Yuval Kordov
+
+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,150 @@
+# AjaxTableRails
+
+AjaxTableRails is a super simple, super lightweight library if all you want is fast, JSON-loaded tables with ajax sorting and pagination. It provides just enough to get you going and doesn't do anything fancy. It is also still very much in early development, so there are probably bugs.
+
+## Usage
+
+### Dependencies
+
+Rails and JQuery. C'est ca. If you want to use the Javascript without Rails, feel free.
+
+### Install ajax_table_rails gem
+
+Add `ajax_table_rails` to your `Gemfile` and run `bundle install`
+
+````
+gem 'ajax_table_rails'
+````
+
+### Include javascript assets
+
+Add the following to your `app/assets/javascripts/application.js`:
+
+````
+//= require ajaxtable
+````
+
+### Build your table
+
+In your view (using Users as an example):
+
+````
+<table class="ajax-table" data-source="<%= users_path(format: :json)%>">
+  <thead>
+    <tr>
+      <th data-sort-column="name">Name</th>
+      <th data-sort-column="email">Email</th>
+      <th>Actions</th>
+    </tr>
+  </thead>
+  <tfoot>
+    <td colspan="3">&nbsp;</td>
+  </tfoot>
+  <tbody>
+  </tbody>
+</table>
+````
+
+In this example, the table will automatically initialize, and the Name and Email columns will be sortable. Record count and pagination will be inserted into the `tfoot`.
+
+**Required attributes**
+
+| Attribute | Description |
+| --------- | ----------- |
+| table data-source | JSON path for your table data |
+
+**Optional attributes**
+
+| Attribute | Description |
+| --------- | ----------- |
+| table class | "ajax-table" required for ajax tables to auto-init. Exclude this if you wish to init manually with custom settings (see below). |
+| th data-sort-column | Matches database column you'd like to sort against. |
+
+### Customize your table
+
+AjaxTableRails is built with Bootstrap and FontAwesome in mind, as well as some other defaults that may make you unhappy. You may want to override the classes used for pagination and sorting, as well as some other bits and bops. Here's what a full customization looks like (default values shown):
+
+````
+$(function() {
+  ajaxTable.init($('#some-table'), {
+    cssClasses: {
+      count: 'at-count',          // "Showing xx records out of xx" span
+      pagination: 'pagination',   // Pagination ul, defaults to match Bootstrap
+      sort: 'at-sort',            // Sort icon base class
+      sortAsc: 'fa fa-sort-up',   // Sort icon ascending indicator, defaults to use FontAwesome
+      sortDesc: 'fa fa-sort-down' // Sort icon descending indicator, defaults to use FontAwesome
+    },
+    text: {
+      count: 'Showing {count} records out of {total_count}', // Pass null to skip rendering of this element
+      nextPage: '&raquo;',
+      previousPage: '&laquo;'
+    }
+  });
+});
+````
+
+### Build your controller
+
+Call `set_ajax_table` in a `before_action` to set your sorting criteria, then setup the query in a JSON response block.
+
+`set_ajax_table` populates `@order` and `@page`, which you can use directly in your query. I use Kaminari for pagination, but you can use whatever you like.
+
+````
+before_action -> {
+  set_ajax_table(columns: %w[name email], default_column: "name", default_direction: "desc")
+}, only: [:index]
+
+def index
+  respond_to do |format|
+    format.html {}
+    format.json {
+      @users = User.order(@order).page(@page)
+    }
+  end
+end
+````
+
+**Optional attributes**
+
+| Attribute | Description |
+| --------- | ----------- |
+| columns | Whitelist of sortable columns |
+| default_column | Your default sort column (if unspecified, defaults to `id`) |
+| default_direction | Your default sort direction (if unspecified, deaults to `asc`) |
+
+### Make it shiny
+
+Use whatever CSS you like. Here's a rudimentary example of some things you may want to do.
+
+````
+th[data-sort-column] {
+	cursor: pointer;
+}
+i.at-sort {
+  margin-left: 5px;
+}
+span.at-count {
+  float: left;
+  margin-top: 10px;
+}
+ul.pagination {
+  float: right;
+}
+````
+
+## Love it? Hate it?
+
+@uberllama
+
+I also write random [tech articles](http://blog.littleblimp.com).
+
+## Copyright
+
+Copyright &copy; 2014 Yuval Kordov. See MIT-LICENSE for further details.
+
+## TODO
+
+* Windowed pagination
+* Result filtering
+* Show default sort
+* Allow customization via data attributes

data/Rakefile

@@ -0,0 +1,7 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+Bundler::GemHelper.install_tasks

data/ajax_table_rails.gemspec

@@ -0,0 +1,21 @@
+$:.push File.expand_path("../lib", __FILE__)
+
+# Maintain your gem's version:
+require "ajax_table_rails/version"
+
+# Describe your gem and declare its dependencies:
+Gem::Specification.new do |s|
+  s.name        = "ajax_table_rails"
+  s.version     = AjaxTableRails::VERSION
+  s.authors     = ["Yuval Kordov"]
+  s.email       = ["yuval.kordov@gmail.com"]
+  s.homepage    = "https://github.com/uberllama/ajax_table_rails"
+  s.summary     = "Simple JSON-loaded tables with sorting and pagination"
+  s.description = "An ultra lightweight alternative to datatables or dynatables, with built in Rails helpers. Still under construction [insert animated construction worker here]."
+  s.license     = "MIT"
+
+  s.files = `git ls-files`.split("\n")
+  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+
+  s.add_dependency "rails", ">= 3.1"
+end

data/app/assets/javascripts/ajaxtable.js

@@ -0,0 +1,156 @@
+var ajaxTable = (function($) {
+
+  // On document ready, ajaxify all tables with the `ajax-table` class.
+  //
+  // If you want to use custom settings, forego the `ajax-table` class and call init manually:
+  // $(function() {
+  //   ajaxTable.init($('#some-table'), {
+  //     cssClasses: { pagination: 'some-class' },
+  //     text: { count: null },
+  //     ...
+  //   });
+  // });
+  //
+  // @see config Available settings
+  $(function() {
+    $('table.ajax-table').each(function() {
+      init($(this));
+    });
+  });
+  
+  /* public */
+
+  // Load and build initial table, and bind static events
+  var init = function($table, options) {
+    $.extend(true, config, options);
+    $table.data('page', 1);
+    loadTable($table);
+    initSorting($table);
+  };
+  
+  /* private */
+
+  // Default config
+  // All of these settings can be overriden by manually calling `init`
+  var config = {
+    // You can safely use multiple classes here
+    // @example `pagination: 'pagination foo-pagination'`
+    cssClasses: {
+      count: 'at-count',          // "Showing xx records out of xx" span
+      pagination: 'pagination',   // Pagination ul, defaults to match Bootstrap
+      sort: 'at-sort',            // Sort icon base class
+      sortAsc: 'fa fa-sort-up',   // Sort icon ascending indicator, defaults to use FontAwesome
+      sortDesc: 'fa fa-sort-down' // Sort icon descending indicator, defaults to use FontAwesome
+    },
+    // @note Querystring param keys match up with those used by ajax_table.rb
+    params: {
+      page: 'page',
+      sortColumn: 'sort',
+      sortDirection: 'direction'
+    },
+    // To not display count, pass `text.count: null`
+    text: {
+      count: 'Showing {count} records out of {total_count}',
+      nextPage: '»',
+      previousPage: '«'
+    }
+  };
+
+  // Load and render table, based on current sort and page
+  var loadTable = function($table) {
+    params = {};
+    params[config.params.page] = $table.data('page');
+    params[config.params.sortColumn] = $table.data('sort-column');
+    params[config.params.sortDirection] = $table.data('sort-direction');
+    
+    var request = $.ajax({
+      url: $table.data('source'),
+      data: $.extend({ format: 'json' }, params),
+      type: 'GET',
+      dataType: 'json'
+    });
+    request.done(function(data) {
+      buildRows($table, data.rows);
+      buildPagination($table, data.pagination);
+    });
+  };
+
+  // Bind table headers to sort with direction
+  // @note To enable sorting on a header, add a `data-sort-column` attribute with the desired column name.
+  // @example `<th data-sort-column="email">Email</th>`
+  var initSorting = function($table) {
+    $table.find('th[data-sort-column]').on('click', function() {
+      // Set direction based on prior and clicked sort column
+      var sortColumn = $(this).data('sort-column');
+      var direction = ($table.data('sort-column') == sortColumn && $table.data('sort-direction') == 'asc') ? 'desc' : 'asc';
+      $table.data('sort-direction', direction);
+      // Set new sort column
+      $table.data('sort-column', sortColumn);
+      // Always reset page to 1 when re-sorting
+      $table.data('page', 1);
+      // Remove and re-insert sort icon
+      $table.find('th i.' + config.cssClasses.sort).remove();
+      var $i = $('<i/>', { class: config.cssClasses.sort + ' ' + (direction == 'asc' ? config.cssClasses.sortAsc : config.cssClasses.sortDesc) });
+      $(this).append($i);
+      // Reload table
+      loadTable($table);
+    });
+  };
+
+  // Build table rows
+  var buildRows = function($table, rows) {
+    var $tbody = $table.find('tbody');
+    $tbody.children().remove();
+    $.each(rows, function(i,row) {
+      var $tr = $('<tr/>');
+      $tbody.append($tr);
+      $.each(row, function(k,v) {
+        $tr.append('<td>' + v + '</td>');
+      });
+    });
+  };
+
+  // Build counts and simple pagination
+  var buildPagination = function($table, pagination) {
+    $td = $table.find('tfoot').find('td').first();
+    $td.children().remove();
+    if (pagination.total_count > pagination.count) {
+      // Display current out of total record count
+      if (config.text.count) {
+        var $count = $('<span/>', { class: config.cssClasses.count });
+        $td.append($count);
+        $count.html(config.text.count.replace('{count}', pagination.count).replace('{total_count}', pagination.total_count));
+      }
+      // Pagination controls
+      var pageCount = Math.ceil(pagination.total_count / pagination.per_page);
+      var currentPage = $table.data('page');
+      var $ul = $('<ul/>', { class: config.cssClasses.pagination });
+      $td.append($ul);
+      if (currentPage > 1) {
+        var previousPage = currentPage-1;
+        $ul.append('<li><a href="#" data-page=' + previousPage + '>' + config.text.previousPage + '</a></li>');
+      }
+      for (var pageNumber = 1; pageNumber <= pageCount; pageNumber++) {
+        var li = '<li';
+        if (pageNumber == currentPage) li += ' class="active"';
+        li += '>';
+        $ul.append(li + '<a href="#" data-page=' + pageNumber + '>' + pageNumber + '</a></li>');
+      }
+      if (currentPage < pageCount) {
+        var nextPage = currentPage+1;
+        $ul.append('<li><a href="#" data-page=' + nextPage + '>' + config.text.nextPage + '</a></li>');
+      }
+      // Bind the pagination controls
+      $table.find('ul.' + config.cssClasses.pagination.split(' ').join('.') + ' a').on('click', function(e) {
+        $table.data('page', $(this).data('page'));
+        loadTable($table);
+        e.preventDefault();
+      });
+    }
+  };
+
+  return {
+    init: init
+  }
+
+})(jQuery);

data/app/controllers/concerns/ajax_table_actions.rb

@@ -0,0 +1,30 @@
+module AjaxTableActions
+  extend ActiveSupport::Concern
+
+  private
+
+  # before_action that sets @page and @order instance variables based off ajax_table params `sort` and `direction`
+  #
+  # @example With sortable columns
+  #   before_action -> { set_ajax_table(columns: %w[name email], default_column: "name", default_direction: "asc") }
+  #
+  # @example With no sortable columns
+  #   before_action -> { set_ajax_table(default_column: "name", default_direction: "asc") }
+  #
+  # @param [Hash] options                         Optional configuration. If none specified, sort params are ignored and the collection is sorted by ID
+  # @option options [Array] columns               Whitelisted columns that can be sorted on
+  # @option options [String] default_column       Default sort column
+  # @option options [String] default_direction    Default sort direction
+  def set_ajax_table(options = {})
+    @page = [params[:page].to_i, 1].max
+
+    unless options.empty?
+      column = (options[:columns] && options[:columns].detect {|column| column == params[:sort]}) || options[:default_column]
+      direction = %w[asc desc].include?(params[:direction]) ? params[:direction] : options[:default_direction]
+    end
+    column ||= 'id'
+    direction ||= 'asc'
+    @order = "#{column} #{direction}"
+  end
+
+end

data/lib/ajax_table_rails/engine.rb

@@ -0,0 +1,9 @@
+module AjaxTableRails
+  class Engine < ::Rails::Engine
+    initializer "ajax_table_rails.load_before_actions" do
+      ActiveSupport.on_load(:action_controller) do
+        ActionController::Base.send(:include, AjaxTableActions)
+      end
+    end
+  end
+end

data/lib/ajax_table_rails/version.rb

@@ -0,0 +1,3 @@
+module AjaxTableRails
+  VERSION = "0.0.1"
+end

data/lib/ajax_table_rails.rb

@@ -0,0 +1,4 @@
+require "ajax_table_rails/engine"
+
+module AjaxTableRails
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: ajax_table_rails
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Yuval Kordov
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-01-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+description: An ultra lightweight alternative to datatables or dynatables, with built
+  in Rails helpers. Still under construction [insert animated construction worker
+  here].
+email:
+- yuval.kordov@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- CHANGELOG.md
+- Gemfile
+- MIT-LICENSE
+- README.md
+- Rakefile
+- ajax_table_rails.gemspec
+- app/assets/javascripts/ajaxtable.js
+- app/controllers/concerns/ajax_table_actions.rb
+- lib/ajax_table_rails.rb
+- lib/ajax_table_rails/engine.rb
+- lib/ajax_table_rails/version.rb
+homepage: https://github.com/uberllama/ajax_table_rails
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.1
+signing_key: 
+specification_version: 4
+summary: Simple JSON-loaded tables with sorting and pagination
+test_files: []