ajax_table_rails 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b5d01e5c8e5273ed807ac6ccb4fa53c2e18744e4
-  data.tar.gz: 2aed6fc52f83751cf394a05746a4765fc172a538
+  metadata.gz: 7daf0536ef80c2d76d7eeadd42c5e4b3dbd1b5a4
+  data.tar.gz: 3dc3a84175edbdb15d2d139d391edf9098032763
 SHA512:
-  metadata.gz: 825b22093e803c527b8ee61e59b41cc0158d756f5ababfd5c00860214a6a6905d82463d32e15d264c808a9c92d7ad6b127d2dfeb7a83d72a9035de6de364fd80
-  data.tar.gz: 2bd8ddcbae62e2bde5b792a262c86274a03eda4b64ae084da05848c408e05827f742d911a366f5421b4210ade3625417a7ff82406fde08f56c8f84e38f883103
+  metadata.gz: 3778d000593bdfe61d1ae038dfba7de8a79151938444e48501544e8cb134e49e3428de682ccdc364dec2c91d6f985c03a1914be5fb481efc6a048da57eb8e897
+  data.tar.gz: bfa11c01eccf58b264937061988fbe6ef2f15781bda807aa416c307a1fa7b2c6883f434beb00f0f6ad8d9695832db6be0df83cf2cfff10a09285fee2594d7908

data/CHANGELOG.md

@@ -1,3 +1,6 @@
+## v0.0.3
+
+* Now a Jquery plugin with a much better interface
 ## v0.0.2
 
 * Initial search implementation

data/README.md

@@ -1,6 +1,6 @@
 # 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.
+AjaxTableRails is a super simple, super lightweight library if all you want is fast, JSON-loaded tables with ajax sorting, pagination, and filtering. 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
 
@@ -26,12 +26,12 @@ Add the following to your `app/assets/javascripts/application.js`:
 
 ### Basic usage
 
-#### Build your table
+#### Table structure
 
-In your view (using Users as an example):
+Your table should look like this:
 
 ````
-<table class="ajax-table" data-source="<%= users_path(format: :json)%>" id="users-table">
+<table data-source="<%= users_path(format: :json)%>" id="users-table">
   <thead>
     <tr>
       <th data-sort-column="name">Name</th>
@@ -47,26 +47,42 @@ In your view (using Users as an example):
 </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`.
+Records are inserted into the `tbody` and record count and pagination are inserted into the `tfoot`.
 
-**Required attributes**
+**Data Attributes**
 
 | Attribute | Description |
 | --------- | ----------- |
 | table data-source | JSON path for your table data |
+| th data-sort-column | Matches database column you'd like to sort against. |
 
-**Optional attributes**
+#### Filtering results
 
-| 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. |
+You can optionally specify a form that will be bound to your table for simple table searching and reseting.
+
+````
+<form id="users-search">
+  <input class="ajax-table-search-input">
+  <a href="#" class="ajax-table-reset">x</a>
+  <input type="submit" value="Search">
+</form>
+````
+
+The `ajax-table-search-input` and `ajax-table-reset` class names are required. Alternatively, you can call search and reset manually (see Advanced Usage, below).
+
+#### Init that!
+
+````
+$(function() {
+  $('#users-table').ajaxTable({ searchForm: '#users-search' });
+});
+````
 
 #### 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.
+`set_ajax_table` populates `@order`, `@page`, and `@search`, which you can use directly in your query. I use [kaminari](https://github.com/amatsuda/kaminari) for pagination and either a custom scope or [pg_search](https://github.com/Casecommons/pg_search) for searching, but you can use whatever you like.
 
 ````
 before_action -> {
@@ -78,12 +94,14 @@ def index
     format.html {}
     format.json {
       @users = User.order(@order).page(@page)
+      @users = @users.search(@search) if @search.present?
+      @total_count = @users.except(:order, :limit, :offset).count
     }
   end
 end
 ````
 
-**Optional attributes**
+**Data attributes**
 
 | Attribute | Description |
 | --------- | ----------- |
@@ -103,31 +121,19 @@ end
 json.pagination do
   json.per_page User.default_per_page
   json.count @users.size
-  json.total_count User.count
+  json.total_count @total_count
 end
 ````
 
 ### Advanced usage
 
-#### Filtering results
-
-**Under construction.** Adding the following anywhere on your page will currently work.
-
-````
-<form class="ajax-table-search" data-ajax-table-id="users-table">
-  <input class="ajax-table-search-input">
-  <a href="#" class="ajax-table-reset">x</a>
-  <input type="submit" value="Search">
-</form>
-````
-
-#### Customize your table
+#### Custom settings
 
 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'), {
+  $('#users-table').ajaxTable({
     cssClasses: {
       count: 'at-count',          // "Showing xx records out of xx" span
       pagination: 'pagination',   // Pagination ul, defaults to match Bootstrap
@@ -135,6 +141,7 @@ $(function() {
       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
     },
+    searchForm: null,             // Form selector to be automatically bound for searching this table
     text: {
       count: 'Showing {count} records out of {total_count}', // Pass null to skip rendering of this element
       nextPage: '&raquo;',
@@ -144,6 +151,15 @@ $(function() {
 });
 ````
 
+#### Custom search and reset
+
+The `search()` and `reset()` methods are public, so you're free to forego the simple automagic implementation and realize your wildest interface fantasies.
+
+````
+$('#users-table').ajaxTable('search', 'baby sloths');
+$('#users-table').ajaxTable('reset');
+````
+
 #### Make it shiny
 
 Use whatever CSS you like. Here's a rudimentary example of some things you may want to do.
@@ -176,7 +192,6 @@ Copyright &copy; 2014 Yuval Kordov. See MIT-LICENSE for further details.
 
 ## TODO
 
-* Result filtering
 * Windowed pagination
 * Show default sort
 * Allow customization via data attributes

data/app/assets/javascripts/ajaxtable.js

@@ -1,98 +1,12 @@
-var ajaxTable = (function($) {
+;(function ($, window, document, undefined) {
 
-  // On document ready:
-  // ajaxify all tables with the `ajax-table` class
-  // bind search/reset via forms with the `ajax-table-search` class
-  //
-  // If you want to use custom settings for your tables, 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));
-    });
-
-    $('body').on('submit', 'form.ajax-table-search', function(e) {
-      var $form = $(this);
-      search($('#'+$form.data('ajax-table-id')), $form.find('input.ajax-table-search-input').val());
-      e.preventDefault();
-    });
-
-    $('body').on('click', '.ajax-table-reset', function(e) {
-      var $form = $(this).closest('form.ajax-table-search');
-      $form.find('input.ajax-table-search-input').val('');
-      resetTable($('#'+$form.data('ajax-table-id')));
-      e.preventDefault();
-    });
-  });
-  
-  /* 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);
-  };
-
-  // Filter table records against submitted keywords
-  var search = function($table, val) {
-    $table.data('page', 1);
-    $table.data('search', val);
-    loadTable($table);
-  };
-
-  // Reset table to an unpaginated and unfiltered state
-  var resetTable = function($table) {
-    $table.data('page', 1);
-    $table.removeData('search');
-    loadTable($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',
-      search: 'search',
-      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 page, sort, and search filter
+  // Load and build table and pagination based on current data state
   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');
-    params[config.params.search]        = $table.data('search');
+    params[$table.data('ajaxTable').params.page] = $table.data('page');
+    params[$table.data('ajaxTable').params.sortColumn] = $table.data('sort-column');
+    params[$table.data('ajaxTable').params.sortDirection] = $table.data('sort-direction');
+    params[$table.data('ajaxTable').params.search] = $table.data('search');
     
     var request = $.ajax({
       url: $table.data('source'),
@@ -106,28 +20,6 @@ var ajaxTable = (function($) {
     });
   };
 
-  // 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() {
-      // Reset pagination
-      $table.data('page', 1);
-      // Set direction based on prior and just-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);
-      // 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');
@@ -147,32 +39,32 @@ var ajaxTable = (function($) {
     $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 });
+      if ($table.data('ajaxTable').text.count) {
+        var $count = $('<span/>', { class: $table.data('ajaxTable').cssClasses.count });
         $td.append($count);
-        $count.html(config.text.count.replace('{count}', pagination.count).replace('{total_count}', pagination.total_count));
+        $count.html($table.data('ajaxTable').text.count.replace('{count}', pagination.count).replace('{total_count}', pagination.total_count));
       }
       // Build pagination controls
       var pageCount = Math.ceil(pagination.total_count / pagination.per_page);
       var currentPage = $table.data('page');
-      var $ul = $('<ul/>', { class: config.cssClasses.pagination });
+      var $ul = $('<ul/>', { class: $table.data('ajaxTable').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>');
+        $ul.append('<li><a href="#" data-page=' + previousPage + '>' + $table.data('ajaxTable').text.previousPage + '</a></li>');
       }
       for (var pageNumber = 1; pageNumber <= pageCount; pageNumber++) {
         var li = '<li';
-        if (pageNumber == currentPage) li += ' class="active"';
+        if (pageNumber == currentPage || (pageNumber == 1 && !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>');
+        $ul.append('<li><a href="#" data-page=' + nextPage + '>' + $table.data('ajaxTable').text.nextPage + '</a></li>');
       }
       // Bind pagination controls
-      $table.find('ul.' + config.cssClasses.pagination.split(' ').join('.') + ' a').on('click', function(e) {
+      $table.find('ul.' + $table.data('ajaxTable').cssClasses.pagination.split(' ').join('.') + ' a').on('click', function(e) {
         $table.data('page', $(this).data('page'));
         loadTable($table);
         e.preventDefault();
@@ -180,10 +72,118 @@ var ajaxTable = (function($) {
     }
   };
 
-  return {
-    init: init,
-    search: search,
-    resetTable: resetTable
-  }
+  // 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() {
+      // Reset pagination
+      $table.data('page', 1);
+      // Set direction based on prior and just-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);
+      // Remove and re-insert sort icon
+      $table.find('th i.' + $table.data('ajaxTable').cssClasses.sort).remove();
+      var $i = $('<i/>', { class: $table.data('ajaxTable').cssClasses.sort + ' ' + (direction == 'asc' ? $table.data('ajaxTable').cssClasses.sortAsc : $table.data('ajaxTable').cssClasses.sortDesc) });
+      $(this).append($i);
+      // Reload table
+      loadTable($table);
+    });
+  };
+
+  // Initialize search and reset based off of searchForm specified on init
+  var initSearch = function($table, searchForm) {
+    $('body').on('submit', searchForm, function(e) {
+      searchTable($table, $(this).find('input.ajax-table-search-input').val());
+      e.preventDefault();
+    });
+    
+    $('body').on('click', '.ajax-table-reset', function(e) {
+      $(this).closest('form').find('input.ajax-table-search-input').val('');
+      resetTable($table);
+      e.preventDefault();
+    });
+  };
+
+  // Filter table records against submitted keywords
+  var searchTable = function($table, val) {
+    $table.data('page', 1);
+    $table.data('search', val);
+    loadTable($table);
+  };
+
+  // Reset table to an unpaginated and unfiltered state
+  var resetTable = function($table) {
+    $table.data('page', 1);
+    $table.removeData('search');
+    loadTable($table);
+  };
+
+  var publicMethods = {
+
+    init: function(options) {
+      return this.each(function() {
+        var $this = $(this);
+        var defaults = {
+          // 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',
+            search:         'search',
+            sortColumn:     'sort',
+            sortDirection:  'direction'
+          },
+          searchForm:       null,             // Form selector to be automatically bound for searching this table
+          text: {
+            count:          'Showing {count} records out of {total_count}', // To not display count, pass `text.count: null`
+            nextPage:       '&raquo;',
+            previousPage:   '&laquo;'
+          }
+        }
+ 
+        var settings = $.extend(true, defaults, options);
+        $this.data('ajaxTable', settings);
+        loadTable($this);
+        initSorting($this);
+        if (settings.searchForm) {
+          initSearch($this, settings.searchForm);
+        }
+      });
+    },
+
+    search: function(val) {
+      var $this = $(this);
+      searchTable($this, val);
+      return $this;
+    },
+
+    reset: function() {
+      var $this = $(this);
+      resetTable($this);
+      return $this;
+    }
+
+  };
+
+  $.fn.ajaxTable = function(method) {
+    if (publicMethods[method]) {
+      return publicMethods[method].apply(this, Array.prototype.slice.call(arguments, 1));
+    } else if (typeof(method) === 'object' || !method) {
+      return publicMethods.init.apply(this, arguments);
+    } else {
+      $.error('Method ' + method + ' does not exist on jQuery.ajaxTable.');
+    }
+  };
 
-})(jQuery);
+})(jQuery, window, document);

data/lib/ajax_table_rails/version.rb

@@ -1,3 +1,3 @@
 module AjaxTableRails
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ajax_table_rails
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Yuval Kordov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-29 00:00:00.000000000 Z
+date: 2014-01-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails