grapple 0.1.8 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fba23ec15fa15e3af330adb21135aa01d7fc086b
-  data.tar.gz: a1400867677c6d2aaf42f960be45cc3a43290882
+  metadata.gz: 1d49408d1a5288a086cb3cb5016d2c6e68b09691
+  data.tar.gz: 6cbd12c3529aa3bb347771430e6bffab4926924b
 SHA512:
-  metadata.gz: c34626569e41eb3064454c449b39c6bf789addcf65e67891b2adade034e62666dbadc8ef5aec741cbd86466a2f30a0ce148b87e3f2aebc2ccb75756b0e23683b
-  data.tar.gz: c7209519dd827357fa63d1d582ab050cfbd1b83345dbc24ea994c591f969b8d16fd0d39735b8328acbf4dd809e10cf1d661ada5d44bf34672d26125501e2851e
+  metadata.gz: e4fb86706c0372306b4381daa0224257b16589318d2726e9451294696e2bc5707359c29b6a2fcb907266bdca4493f7d385975b0c7e0d501cb6ec0f5cd017bb5c
+  data.tar.gz: 13e5c2b134d2930a836db20d3c8ea619cafccd0f69e43201171f178f1b1e3d9244468973878b8b85b4f3cd5c2d8da8cbc667df5ce9d9603ff695f612733f61f2

data/README.md

@@ -189,7 +189,7 @@ Render the table using `table_for` in `app/views/posts/_table.html.erb`
 
 ## History w/AJAX (back button)
 
-Requires: https://github.com/browserstate/history.js/
+Uses the native `window.history` API by default. If History.js is present it will use that instead for compatibility with older browsers (https://github.com/browserstate/history.js/).
 
 ``` javascript
 // app/assets/javascripts/application.js

data/app/assets/javascripts/grapple-history.js

@@ -4,25 +4,62 @@
 var urlQuery = Grapple.Util.urlQuery, 
 	parseUrlQuery = Grapple.Util.parseUrlQuery;
 
-var GrappleHistory = function(namespace) {
-	this.namespace = namespace;
-	if(History.init) {
-		// https://github.com/browserstate/history.js/
-		this.api = History;
+// History.js for backwards compatibility with older browsers
+// https://github.com/browserstate/history.js/
+var LegacyHistory = function() {
+	var api = History;
 		
-		// Initialization of history.js can be delayed
-		// if it was do it now
-		if(this.api.options && this.api.options.delayInit) {
-			this.api.options.delayInit = false;
-			this.api.init();
-		}
+	// Initialization of history.js can be delayed
+	// if it was do it now
+	if(api.options && api.options.delayInit) {
+		api.options.delayInit = false;
+		api.init();
 	}
-	else {
-		// TODO: support native history api
-		this.api = window.history;
+	this.api = api;
+};
+
+LegacyHistory.prototype = {
+	push: function(params) {
+		return this.api.pushState(null, document.title, '?' + params);
+	},
+	get: function() {
+		return urlQuery(this.api.getState().url);
+	},
+	bind: function(callback) {
+		$(window).bind('statechange', callback);
+	},
+	unbind: function(callback) {
+		$(window).unbind('statechange', callback);
 	}
-	this.api = History;
-	this.changeCallback = null;
+};
+
+// Native Browser History API
+var ModernHistory = function() {
+
+};
+
+ModernHistory.prototype = {
+	push: function(params) {
+		if(window.history && window.history.pushState) {
+			return window.history.pushState(params, document.title, '?' + params);
+		}
+	},
+	get: function() {
+		if(window.history) {
+			return window.history.state || urlQuery(document.location.toString());
+		}
+	},
+	bind: function(callback) {
+		$(window).bind('popstate', callback);
+	},
+	unbind: function(callback) {
+		$(window).unbind('popstate', callback);
+	}
+};
+
+var GrappleHistory = function(grappleTable) {
+	this.grappleTable = grappleTable;
+	this._historyChangeCallback = null;
 };
 
 // Don't clutter the url with rails form parameters
@@ -30,10 +67,20 @@ GrappleHistory.IGNORE_PARAMS = { 'utf8': true, 'authenticity_token': true };
 
 GrappleHistory.prototype = {
 
-	add: function(params) {
-		var namespace = this.namespace;
-		var state = this.api.getState();
-		var historyParams = parseUrlQuery(urlQuery(state.url));
+	init: function() {
+		// Use the History.js wrapper if History.js has been loaded
+		this.api = typeof History !== 'undefined' && History.init ? new LegacyHistory() : new ModernHistory();
+		this._subscribeToTableChange();
+		this._subscribeToHistoryChange();
+	},
+
+	/**
+	 * Add an entry to the history
+	 * @param {String} params 
+	 */
+	_addHistoryEntry: function(params) {
+		var namespace = this.grappleTable.namespace;
+		var historyParams = parseUrlQuery(this.api.get());
 		var newParams = parseUrlQuery(params);
 
 		// Remove any parameters from the current state 
@@ -57,14 +104,45 @@ GrappleHistory.prototype = {
 			historyParams[x] = newParams[x];
 		}
 		
-		this.api.pushState(null, document.title, '?' + $.param(historyParams));
+		this.api.push($.param(historyParams));
 	},
 	
-	subscribe: function(callback) {
-		var api = this.api, namespace = this.namespace;
-		this.changeCallback = function(event) {
-			var state = api.getState();
-			var params = parseUrlQuery(urlQuery(state.url));
+	/**
+	 * Listen for changes to the table to add them to the history
+	 */
+	_subscribeToTableChange: function() {
+		var self = this;
+		this._beforeLoadCallback = function(e, params) {
+			self._unsubscribeFromTableChange();
+			self._unsubscribeFromHistoryChange();
+			// Don't add params to history if this was triggered by history change
+			if(self._ignoreNextLoad) {
+				self._ignoreNextLoad = false;
+			}
+			else {
+				self._addHistoryEntry(params);
+			}
+		};
+		this.grappleTable.element.on('grapple:before_load', this._beforeLoadCallback);
+	},
+
+	/**
+	 * Stop listening for changes to the table
+	 */
+	_unsubscribeFromTableChange: function() {
+		if(this._beforeLoadCallback) {
+			this.grappleTable.element.unbind('grapple:before_load', this._beforeLoadCallback);
+			this._beforeLoadCallback = null;
+		}
+	},
+
+	/**
+	 * Listen for changes to the history (back button clicks)
+	 */
+	_subscribeToHistoryChange: function() {
+		var api = this.api, namespace = this.grappleTable.namespace, self = this;
+		this._historyChangeCallback = function(event) {
+			var params = parseUrlQuery(api.get());
 			// Only include the parameters for this namespace
 			if(namespace) {
 				var r = new RegExp('^' + namespace + '\\[([^\\]]+)\\]$')
@@ -74,15 +152,19 @@ GrappleHistory.prototype = {
 					}
 				}
 			}
-			callback(params);
+			self._ignoreNextLoad = true;
+			self.grappleTable.loadTable($.param(params));
 		};
-		$(window).bind('statechange', this.changeCallback);
+		this.api.bind(this._historyChangeCallback);
 	},
 	
-	unsubscribe: function() {
-		if(this.changeCallback) {
-			$(window).unbind('statechange', this.changeCallback);
-			this.changeCallback = null;
+	/**
+	 * Stop listening for history changes
+	 */
+	_unsubscribeFromHistoryChange: function() {
+		if(this._historyChangeCallback) {
+			this.api.unbind(this._historyChangeCallback);
+			this._historyChangeCallback = null;
 		}
 	}
 	

data/app/assets/javascripts/grapple-jquery.js

@@ -1,8 +1,5 @@
 (function(Grapple, $) {
 	'use strict';
-
-var urlQuery = Grapple.Util.urlQuery, 
-	parseUrlQuery = Grapple.Util.parseUrlQuery;
 	
 var overrideLink = function(clickable, anchor, callback) {
 	var href = $(anchor).attr('href');
@@ -15,8 +12,8 @@ var overrideLink = function(clickable, anchor, callback) {
 /**
  * Creates a new instance of the Grapple AJAX widget.
  *
- * @param {String} Selector for the table container element.
- * @param {Object} Hash of options for the table (url, namespace, history)
+ * @param {String} element - Selector for the table container element.
+ * @param {Object} options - Hash of options for the table (url, namespace, history)
  */
 var GrappleTable = function(element, options) {
 	options = options || {};
@@ -24,14 +21,12 @@ var GrappleTable = function(element, options) {
 	this.url = options.url || this.element.data('grapple-ajax-url');
 	this.namespace = options.namespace || this.element.data('grapple-ajax-namespace') || null;
 	this.currentParams = options.params || '';
+	this.plugins = {};
 	if(typeof options.history !== 'undefined' && options.history !== true) {
-		this.history = options.history;
+		this.plugins.history = options.history;
 	}
 	else if(this.element.data('grapple-ajax-history') == 1 || options.history === true) {
-		this.history = new Grapple.History(this.namespace);
-	}
-	else {
-		this.history = null;
+		this.plugins.history = new Grapple.History(this);
 	}
 	this.init();
 };
@@ -44,7 +39,7 @@ GrappleTable.NON_TABLE_RESPONSE = '<!DOCTYPE html>';
 GrappleTable.prototype = {
 	
 	/**
-	 *
+	 * Initialize the grapple table
 	 */
 	init: function() {
 		var self = this;
@@ -56,39 +51,29 @@ GrappleTable.prototype = {
 		self.initSorting();
 		self.initSearchForm();
 		self.initPagination();
-		self.initHistory();
+		self.initPlugins();
 		
 		self.element.removeClass(GrappleTable.CSS_AJAX_LOADING);
 	},
 
-	initHistory: function() {
-		if(this.history) {
-			var self = this;
-			this.history.unsubscribe();
-			this.history = new Grapple.History(this.namespace);
-			this.history.subscribe(function(params) {
-				self.onHistoryChange(params);
-			});
+	/**
+	 * Initialize plugins
+	 */
+	initPlugins: function() {
+		for(var name in this.plugins) {
+			this.plugins[name].init();
 		}
 	},
 	
-	onHistoryChange: function(params) {
-		this._showLoading();
-		this._updateTable($.param(params));
-	},
-	
 	/**
-	 *
+	 * Load the table contents
+	 * @param {String} params - Query string of parameters to load the table with
+	 * @fires Grapple#grapple:before_load
+	 * @fires Grapple#grapple:after_load
 	 */
 	loadTable: function(params) {
-		this.element.trigger('grapple:before_load');
+		this.element.trigger('grapple:before_load', params);
 		this._showLoading();
-
-		if(this.history) {
-			this.history.unsubscribe();
-			this.history.add(params);
-		}
-		
 		this._updateTable(params);
 	},
 	
@@ -117,7 +102,7 @@ GrappleTable.prototype = {
 		}
 		$.ajax(url, {
 			success: function(data) {
-				// HACK
+				// HACK: handle full page responses
 				var nonTableKeyIndex = data.indexOf(GrappleTable.NON_TABLE_RESPONSE);
 				if(nonTableKeyIndex > -1 && nonTableKeyIndex < 100) {
 					data = "Failed to load table";

data/app/assets/javascripts/grapple.js

@@ -1,9 +1,6 @@
 (function(globals) {
 	'use strict';
 
-// Namespace
-var Grapple = {};
-
 var decodeParam = function(str) { 
 	return decodeURIComponent(str.replace(/\+/g, " "));
 };

data/config/locales/en.yml

@@ -1,2 +1,5 @@
 en:
-  no_search_results: "We're sorry. No results were found."
+  displaying_x_y_of_z_results: "Displaying %{x} - %{y} of %{z} results"
+  no_search_results: "We're sorry. No results were found."
+  search: "Search"
+  zero_results: "0 results"

data/lib/grapple/base_table_builder.rb

@@ -2,6 +2,12 @@ module Grapple
 	class BaseTableBuilder
 
 		# Create a helper
+		# @param name [Symbol]
+		#   The name of the helper
+		# @param klass [Grapple::Components::BaseComponent]
+		#   The component class
+		# @param settings [Hash]
+		#   Settings for the component
 		def self.helper(name, klass, settings = {})
 			class_eval <<-RUBY_EVAL
 				def #{name}(*arguments, &block)
@@ -13,6 +19,10 @@ module Grapple
 		end
 
 		# Update settings for a helper
+		# @param helper_name [Symbol]
+		#   The name of the helper
+		# @param options [Hash]
+		#   Settings to update for the component
 		def self.configure(helper_name, *options)
 			settings = options[0] || {}
 			method = :"settings_for_#{helper_name}"
@@ -24,7 +34,22 @@ module Grapple
 			define_singleton_method(method) { settings }
 		end
 
-		attr_reader :columns, :records, :template, :params, :namespace
+		# An Array of columns
+		# @return [Array<Hash>]
+		attr_reader :columns
+		
+		# An Array, ActiveRecord::Collection or Enumerable of records to be displayed in the table
+		# @return [Enumerable]
+		attr_reader :records
+
+		# @return [ActionView::Base]
+		attr_reader :template
+		
+		# Request parameters
+		attr_reader :params
+		
+		# @return [String] namespace for the grapple table
+		attr_reader :namespace
 
 		def initialize(template, columns, records, params = {}, *options)
 			@template = template
@@ -37,14 +62,18 @@ module Grapple
 			@helper_instances = {}
 		end
 		
+		# Default options for the component
+		# @return [Hash]
 		def default_options
 			{ }
 		end
 
+		# HTML to insert before the <table> tag
 		def before_table
 			''
 		end
 
+		# HTML to insert after the </table> tag
 		def after_table
 			''
 		end

data/lib/grapple/components.rb

@@ -19,6 +19,8 @@ module Grapple
 		autoload :SearchSubmit
 		autoload :WillPaginatePagination
 		autoload :WillPaginateInfobar
+		autoload :KaminariPagination
+		autoload :KaminariInfobar
 
 	end
 end

data/lib/grapple/components/actions.rb

@@ -1,5 +1,22 @@
 module Grapple
 	module Components
+
+		# Render links that apply to the table
+		# @example
+		#  <%
+		#    actions = [
+		#      { label: :new_user, url: new_user_path },
+		#      { label: :export_users, url: export_users_path }
+		#    ]
+		#  %>
+		#  <%= table_for(columns, @users) do |t| %>
+		#    <%= t.header do %>
+		#      <%= t.toolbar do %>
+		#        <%= t.actions actions %>
+		#      <% end %>
+		#		   <%= t.column_headings %>
+		#	   <% end %>
+		#  <% end %>
 		class Actions < HtmlComponent
 
 			setting :link_to_helper, :link_to

data/lib/grapple/components/base_component.rb

@@ -1,5 +1,7 @@
 module Grapple
 	module Components
+
+		# Base class for components
 		class BaseComponent
 			
 			cattr_accessor :default_settings
@@ -11,8 +13,12 @@ module Grapple
 				@@default_settings[self.name][name] = default
 			end
 			
-			attr_reader :columns, :records, :template, :params, :builder
-			
+			attr_reader :columns
+			attr_reader :records
+			attr_reader :template
+			attr_reader :params
+			attr_reader :builder
+
 			def initialize(columns, records, template, params, builder, settings = {})
 				@template = template
 				@columns = columns
@@ -23,7 +29,7 @@ module Grapple
 					self.send(:"#{name}=", value)
 				end
 			end
-			
+
 			def render(*options, &block)
 				raise StandardError.new("Component must override render method")
 			end
@@ -71,6 +77,7 @@ module Grapple
 				template.with_output_buffer(&block).html_safe
 			end
 
+			# Renders a block if present, otherwise renders the components with options
 			def block_or_components(components, options, &block)
 				block.nil? ? render_components(components, options, &block).join : capture_block(&block)
 			end

data/lib/grapple/components/column_headings.rb

@@ -34,6 +34,10 @@ module Grapple
 					content = label
 				end
 				
+				if column[:class]
+					column[:class].split(" ").each{|c| cell_classes << c}
+				end
+				
 				cell_classes = ' class="' + cell_classes.join(' ') + '"'
 				title = column[:title] ? " title=\"#{h(column[:title])}\"" : ''
 				liner_classes = liner_classes.length ? " class=\"#{liner_classes.join(" ")}\"" : ''

data/lib/grapple/components/html_header.rb

@@ -1,6 +1,7 @@
 module Grapple
 	module Components
 
+		# thead element for tables
 		class HtmlHeader < HtmlComponent
 			
 			setting :components, []

data/lib/grapple/components/kaminari_pagination.rb

@@ -1,9 +1,9 @@
 module Grapple
 	module Components
-		# Generates paging links using will_paginate.
+		# Generates paging links using Kaminari.
 		#
 		# @example 
-		#   <%= table_for(columns, Post.paginate(page: 2)) do |t| %>
+		#   <%= table_for(columns, Post.page(2)) do |t| %>
 		#     <%= t.footer do %>
 		#       <%= t.pagination %>
 		#     <% end %>

data/lib/grapple/components/search_query_field.rb

@@ -9,7 +9,7 @@ module Grapple
 				template.text_field_tag(
 					search_query_param.to_s, 
 					params[search_query_param.to_sym], 
-					{ :class => search_query_field_class, placeholder: "Search" }
+					{ class: search_query_field_class, placeholder: I18n.translate(:search) }
 				)
 			end
 

data/lib/grapple/components/will_paginate_infobar.rb

@@ -2,9 +2,6 @@ module Grapple
 	module Components
 		class WillPaginateInfobar < HtmlComponent
 
-			setting :message, "Displaying %s - %s of %s results"
-			setting :no_results_message, "0 results"
-
 			def render
 				if records.total_entries > 0
 					start_range = records.offset + 1
@@ -14,12 +11,12 @@ module Grapple
 					end_range = ActiveSupport::NumberHelper.number_to_delimited(end_range)
 					total = ActiveSupport::NumberHelper.number_to_delimited(records.total_entries)
 
-					html = sprintf(message, start_range, end_range, total)
+					html = I18n.translate(:displaying_x_y_of_z_results, x: start_range, y: end_range, z: total)
 				else
-					html = no_results_message
+					html = I18n.translate(:zero_results)
 				end
 
-				builder.row "<th colspan=\"#{num_columns}\">#{html}</th>", :class => 'infobar'
+				builder.row "<th colspan=\"#{num_columns}\">#{html}</th>", class: 'infobar'
 			end
 
 		end

data/lib/grapple/components/will_paginate_pagination.rb

@@ -16,9 +16,10 @@ module Grapple
 
 			def render(paginate_parameters = {})
 				td_class = ""
+
 				if records.instance_of?(Array)
 					html = ' '
-				elsif !params[:query].blank? and records.empty?
+				elsif params.has_key?(:query) && records.empty?
 					html = h(t(no_results_message))
 					td_class = "class='text-left'"
 				else

data/lib/grapple/helpers/table_helper.rb

@@ -5,6 +5,16 @@ module Grapple
 			@@builder = Grapple::DataGridBuilder
 			mattr_accessor :builder
 		
+			# Render a grapple table
+			# @param columns [Enumerable]
+			# @param records [Enumerable]
+			# @option args :container [Boolean]
+			#   If true the table will be rendered with a container div around it
+			# @option args :html [Hash]
+			#   HTML attributes for the `<table>` element
+			# @option args :builder [Grapple::BaseTableBuilder]
+			#   The table builder to use to render the table
+			# @option args :params 
 			def table_for(columns, records, *args, &block)
 				options = args[0] || {}
 				# Don't render the container for AJAX requests by default

data/spec/builders/ajax_data_grid_builder_spec.rb

@@ -9,11 +9,11 @@ describe 'Ajax Data Grid Builder' do
 	end
 	
 	it "container_attributes should be correct" do
-		attr = Grapple::AjaxDataGridBuilder.container_attributes(self, { :id => 'my_table' })
+		builder = Grapple::AjaxDataGridBuilder.new(self, [], [], {}, id: 'my_table')
+		attr = builder.container_attributes()
 		expect(attr[:id]).to eq "my_table"
 		expect(attr[:class]).to include("grapple")
 		expect(attr[:data]['grapple-ajax-url']).to eq '/mock/path'
-		puts attr
 	end
 
 end

data/spec/builders/html_table_builder_spec.rb

@@ -9,16 +9,15 @@ describe 'Base Table Builder' do
 	end
 
 	it "container_attributes should be correct" do
-		attr = Grapple::HtmlTableBuilder.container_attributes(self, { :id => 'my_table' })
+		builder = Grapple::HtmlTableBuilder.new(self, users_columns, users_records, {}, id: 'my_table')
+		attr = builder.container_attributes()
 		expect(attr[:class]).to include("grapple")
 	end
 
 	it "table should be correct" do
 		builder = Grapple::HtmlTableBuilder.new(self, users_columns, users_records, {})
 
-		html = builder.table("<tr><td>TEST</td></tr>")
-
-		#puts html
+		html = builder.table("<tr><td>TEST</td></tr>".html_safe)
 
 		expect(html).to have_tag('table') do
 			with_tag("tr", count: 1) do 
@@ -29,4 +28,4 @@ describe 'Base Table Builder' do
 		end
 	end
 	
-end
+end

data/spec/components/will_paginate_spec.rb

@@ -20,14 +20,9 @@ describe 'will_paginate' do
 	it "should be valid" do
 		records = User.all.paginate({ page: 1, per_page: 3 })
 		builder = Grapple::DataGridBuilder.new(self, columns, records, {})
-		puts builder.infobar()
-		puts builder.pagination()
 
 		records = User.where('id < 0').paginate({ page: 1, per_page: 3 })
-		builder = Grapple::DataGridBuilder.new(self, columns, records, {:query => 'test'})
-		puts builder.infobar()
-		puts builder.pagination()
-		
+		builder = Grapple::DataGridBuilder.new(self, columns, records, {:query => 'test'})	
 	end
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: grapple
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.3.0
 platform: ruby
 authors:
 - Edward Potocko
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-23 00:00:00.000000000 Z
+date: 2020-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -18,28 +18,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.13
+        version: 4.2.11.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.13
+        version: 4.2.11.1
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.13
+        version: 4.2.11.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.13
+        version: 4.2.11.1
 - !ruby/object:Gem::Dependency
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
@@ -88,28 +88,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.13
+        version: 4.2.11.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.13
+        version: 4.2.11.1
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.13
+        version: 4.2.11.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.13
+        version: 4.2.11.1
 - !ruby/object:Gem::Dependency
   name: will_paginate
   requirement: !ruby/object:Gem::Requirement
@@ -207,7 +207,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.6.14.1
 signing_key: 
 specification_version: 4
 summary: Customizable data grid for Rails