grapple 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: cbdfba833204a62c126fb91ec6b95e6b17a76654
+  data.tar.gz: ee880107cf1becc73adc3c46d0f908be8b7ff465
+SHA512:
+  metadata.gz: 1976ae3090721348125616fdb2703bf5e568849c366c62904a81de9b6359a072522cc2fa8307d13e983961f1e9546ad54dac01ac6fc51e29bed25486eb262865
+  data.tar.gz: 591e70f06fbf5ef355a692fc082a7016a77d993a021b3f6f89c9aaff91c2eb22303825fe4f6d8496e372fffca403116aa3176a7b41938fb444363ecdabcc174e

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Equal Level
+
+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,182 @@
+# grapple
+Customizable data grid for Rails
+
+## Features
+* Modular design
+* Server side rendering
+* Usable out of the box
+* Sorting
+* Searching/Filtering
+* Pagination
+* AJAX
+
+## Installation
+
+``` ruby
+# Gemfile for Rails 3+
+gem 'grapple'
+```
+
+``` css
+/* app/assets/stylesheets/application.css */
+*= require grapple
+```
+
+## Dependencies
+* Rails 3+
+
+Optional Dependencies:
+
+* will_paginate - for pagination support
+* jQuery - for AJAX support
+* history.js - for back button support when using the AJAX data table
+
+## Table Builders
+HtmlTableBuilder - A basic HTML table builder
+
+DataGridBuilder (default) - An HTML table builder with support for paging, filtering, sorting, and actions.
+
+AjaxDataGridBuilder - DataGridBuilder that uses AJAX to retrieve results when sorting/filtering the table.
+
+In an initializer set the default builder:
+``` ruby
+Grapple::Helpers::TableHelper.builder = Grapple::AjaxDataGridBuilder
+```
+
+## Basic Usage (DataGridBuilder)
+app/controllers/posts_controller.rb
+``` ruby
+class PostsController < ApplicationController
+	def index
+		@posts = Post.all
+	end
+end
+```
+
+app/views/posts/index.html.erb
+``` HTML+ERB
+<%
+	columns = [
+		{ label: 'Name' },
+		{ label: 'Title' },
+		{ label: 'Content' },	
+		{ label: '' },
+		{ label: '' },
+		{ label: '' }
+	]
+
+	actions = [
+		{ label: 'New Post', url: new_posts_path }
+	]
+%>
+<%= table_for(columns, @posts) do |t| %>
+	<%= t.header do %>
+		<%= t.toolbar do %>
+			<%= t.actions actions %>
+		<% end %>
+		<%= t.column_headings %>
+	<% end %>
+	<%= t.body do |item| %>
+		<td><%= post.name %></td>
+		<td><%= post.title %></td>
+		<td><%= post.content %></td>
+		<td><%= link_to 'Show', post %></td>
+		<td><%= link_to 'Edit', edit_post_path(post) %></td>
+		<td><%= link_to 'Destroy', post, confirm: 'Are you sure?', method: :delete %></td>
+	<% end %>
+<% end %>
+```
+
+## Sorting
+TODO
+
+## Pagination (requires will_paginate)
+app/controllers/posts_controller.rb
+``` ruby
+def index
+	@posts = Post.paginate(page: params[:page] || 1, per_page: 10)
+end
+```
+
+app/views/posts/index.html.erb
+``` HTML+ERB
+<%= table_for(columns, @posts) do |t| %>
+	<%= t.header %>
+	<%= t.footer do %>
+		<%= t.pagination %>
+	<% end %>
+<% end %>
+```
+
+## Filtering/Searching
+TODO
+
+## Actions
+The Actions component can be used to generate buttons/links for actions related to the table.  This can be used to provide links to export the data in the table or create new objects.
+``` HTML+ERB
+<%= table_for(columns, @posts) do |t| %>
+	<%= t.header do %>
+		<%= t.toolbar do %>
+			<%= t.actions [
+					{ label: :new_post, url: new_posts_path },
+					{ label: :export_posts, url: export_posts_path }
+				] %>
+		<% end %>
+		<%= t.column_headings %>
+	<% end %>
+<% end %>
+```
+
+## AJAX
+The AjaxDataGridBuilder generates tables that can update their content using AJAX rather than re-loading the page.  jQuery is required.
+``` javascript
+// app/assets/javascripts/application.js
+//= require grapple
+//= require grapple-jquery
+```
+
+``` ruby
+# app/controllers/posts_controller.rb
+class PostsController < ApplicationController
+	def index
+		@posts = table_results
+	end
+	
+	# Method called by AJAX requests - renders the table without a layout
+	def table
+		@posts = table_results
+		render partial: 'table'
+	end
+	
+protected
+
+	def table_results
+		Post.paginate(page: params[:page] || 1, per_page: 10)
+	end
+end
+```
+
+Create a container around the table that can be updated by the JavaScript
+``` HTML+ERB
+<%# app/views/posts/index.html.erb %>
+<%= grapple_container(id: 'posts_table') do %>
+	<%= render :partial => 'table' %>
+<% end %>
+```
+
+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/
+
+``` javascript
+// app/assets/javascripts/application.js
+//= require jquery-history
+//= require grapple
+//= require grapple-history
+//= require grapple-jquery
+```
+
+## Customizing
+TODO

data/Rakefile

@@ -0,0 +1,9 @@
+# encoding: utf-8
+require 'bundler/setup'
+require 'rspec/core/rake_task'
+
+desc 'Test the datable plugin'
+RSpec::Core::RakeTask.new('spec') do |t|
+  t.pattern = FileList['spec/**/*_spec.rb']
+end
+

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

@@ -0,0 +1,81 @@
+(function(window, Grapple, $) {
+	'use strict';
+
+var urlQuery = Grapple.Util.urlQuery, 
+	parseUrlQuery = Grapple.Util.parseUrlQuery;
+
+var GrappleHistory = function() {
+	if(History.init) {
+		// https://github.com/browserstate/history.js/
+		this.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();
+		}
+	}
+	else {
+		// TODO: support native history api
+		this.api = window.history;
+	}
+	this.api = History;
+	this.changeCallback = null;
+};
+
+// Don't clutter the url with rails form parameters
+GrappleHistory.IGNORE_PARAMS = { 'utf8': true, 'authenticity_token': true };
+
+GrappleHistory.prototype = {
+
+	add: function(namespace, params) {
+		var state = this.api.getState();
+		var historyParams = parseUrlQuery(urlQuery(state.url));
+		var newParams = parseUrlQuery(params);
+
+		// Remove any parameters from the current state 
+		// that are for this table
+		for(var x in historyParams) {
+			var remove = namespace ? 
+				// Remove any parameters in the tables namespace
+				x.indexOf(namespace + '.') === 0 : 
+				// Table is in the global namespace, remove any parameters that aren't namespaced
+				x.indexOf('.') === -1;					
+
+			if(remove) {
+				delete historyParams[x];
+			}
+		}
+		
+		// Add the new parameters
+		for(var x in newParams) {
+			if(GrappleHistory.IGNORE_PARAMS[x]) continue;
+			var key = namespace ? namespace + '.' + x : x;
+			historyParams[key] = newParams[key];
+		}
+
+		this.api.pushState(null, document.title, '?' + $.param(historyParams));
+	},
+	
+	subscribe: function(callback) {
+		var api = this.api;
+		this.changeCallback = function(event) {
+			var state = api.getState();
+			callback(parseUrlQuery(urlQuery(state.url)));
+		};
+		$(window).bind('statechange', this.changeCallback);
+	},
+	
+	unsubscribe: function() {
+		if(this.changeCallback) {
+			$(window).unbind('statechange', this.changeCallback);
+			this.changeCallback = null;
+		}
+	}
+	
+};
+
+Grapple.History = GrappleHistory;
+
+})(window, Grapple, $);

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

@@ -0,0 +1,202 @@
+(function(Grapple, $) {
+	'use strict';
+
+var urlQuery = Grapple.Util.urlQuery, 
+	parseUrlQuery = Grapple.Util.parseUrlQuery;
+	
+var overrideLink = function(clickable, anchor, callback) {
+	var href = $(anchor).attr('href');
+	$(anchor).attr('href', 'javascript:void(0)');
+	$(clickable).on('click', function() {
+		callback(href ? href.split('?')[1] : '');
+	});
+};
+
+/**
+ * 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, history)
+ */
+var GrappleTable = function(element, options) {
+	options = options || {};
+	this.element = $(element);
+	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 || '';
+	if(typeof options.history !== 'undefined' && options.history !== true) {
+		this.history = options.history;
+	}
+	else if(this.element.data('grapple-ajax-history') == 1 || options.history === true) {
+		this.history = new Grapple.History();
+	}
+	else {
+		this.history = null;
+	}
+	this.init();
+};
+
+GrappleTable.CSS_AJAX_LOADING = 'grapple-ajax-loading';
+GrappleTable.CSS_LOADING = 'grapple-loading';
+GrappleTable.CSS_LOADING_OVERLAY = 'loading-overlay';
+GrappleTable.NON_TABLE_RESPONSE = '<!DOCTYPE html>';
+
+GrappleTable.prototype = {
+	
+	/**
+	 *
+	 */
+	init: function() {
+		var self = this;
+		self.table = self.element.children('table');
+		self.header = self.table.children('thead');
+		self.body = self.table.children('tbody');
+		self.footer = self.table.children('tfoot');
+		
+		self.initSorting();
+		self.initSearchForm();
+		self.initPagination();
+		self.initHistory();
+		
+		self.element.removeClass(GrappleTable.CSS_AJAX_LOADING);
+	},
+
+	initHistory: function() {
+		if(this.history) {
+			var self = this;
+			this.history.unsubscribe();
+			this.history = new Grapple.History();
+			this.history.subscribe(function(params) {
+				self.onHistoryChange(params);
+			});
+		}
+	},
+	
+	onHistoryChange: function(params) {
+		console.log("HISTORY CHANGE");
+		this._showLoading();
+		this._updateTable($.param(params));
+	},
+	
+	/**
+	 *
+	 */
+	loadTable: function(params) {
+		console.log("LOAD TABLE ", params);
+		this._showLoading();
+
+		if(this.history) {
+			console.log("ADD History");
+			this.history.unsubscribe();
+			this.history.add(this.namespace, params);
+		}
+		
+		console.log("Update table");
+		this._updateTable(params);
+	},
+	
+	_showLoading: function() {
+		// Add loading class to the container
+		this.element.addClass(GrappleTable.CSS_LOADING);
+		
+		// Set the position of the loading overlay based on the size of the table
+		var loadingBar = this.element.find('.' + GrappleTable.CSS_LOADING_OVERLAY)
+		loadingBar.width(this.table.width());
+		var barHeight = loadingBar.height() || 20;
+		var top = (this.table.height() / 2) - barHeight;
+		loadingBar.css('top', top + 'px');
+	},
+	
+	_hideLoading: function() {
+		// Remove the loading class from the container
+		this.element.removeClass(GrappleTable.CSS_LOADING);
+	},
+	
+	_updateTable: function(params) {
+		var self = this;
+		var url = this.url;
+		if(params.length) {
+			url += '?' + params;
+		}
+
+		$.ajax(url, {
+			success: function(data) {
+				// HACK
+				var nonTableKeyIndex = data.indexOf(GrappleTable.NON_TABLE_RESPONSE);
+				if(nonTableKeyIndex > -1 && nonTableKeyIndex < 100) {
+					data = "Failed to load table";
+				}
+				self.element.addClass(GrappleTable.CSS_AJAX_LOADING);
+				self.element.html(data);
+				self.init();
+				self._hideLoading();
+			},
+			error: function(a, b, c) {
+				// TODO: handle loading errors
+				console.log("Failed to load table");
+				console.log(a);
+				console.log(b);
+				console.log(c);
+			}
+		});
+	},
+	
+	initSorting: function() {
+		var self = this;
+		this.header.find('th.sortable').each(function(i, elem) {
+			overrideLink(elem, $(elem).find('a'), function(params) {
+				// Return to the first page on sorting
+				params = params.replace(/&?page=[0-9]+/, '');
+				params += '&page=1';				
+				self.loadTable(params);
+			});
+		});
+	},
+	
+	initSearchForm: function() {
+		var self = this;
+		this.header.find('form.search-form').each(function(i, elem) {
+			$(elem).on('submit', function(event) {
+				// Don't submit the form
+				event.preventDefault();
+				self.loadTable($(elem).serialize());
+			});
+		});
+	},
+	
+	initPagination: function() {
+		var self = this;
+		this.footer.find('.pagination a').each(function(i, elem) {
+			overrideLink(elem, elem, function(params) { 
+				self.loadTable(params);
+			});
+		});
+	}
+
+};
+
+Grapple.Table = GrappleTable;
+
+function Plugin(option) {
+	return this.each(function() {
+		var $this   = $(this);
+		var data    = $this.data('grapple');
+		var options = typeof option == 'object' && option;
+
+		if (!data && /destroy|hide/.test(option)) return;
+		if (!data) $this.data('grapple', (data = new GrappleTable(this, options)));
+		if (typeof option == 'string') data[option]();
+	});
+}
+
+var old = $.fn.grapple;
+
+$.fn.grapple             = Plugin;
+$.fn.grapple.Constructor = GrappleTable;
+
+$.fn.grapple.noConflict = function() {
+	$.fn.grapple = old;
+	return this;
+}
+
+})(Grapple, jQuery);

data/app/assets/javascripts/grapple.js

@@ -0,0 +1,39 @@
+(function(globals) {
+	'use strict';
+
+// Namespace
+var Grapple = {};
+
+var decodeParam = function(str) { 
+	return decodeURIComponent(str.replace(/\+/g, " "));
+};
+
+var parseUrlQuery = function(query) {
+	var regex = /([^&=]+)=?([^&]*)/g;
+	var params = {}, e;
+	while(e = regex.exec(query)) { 
+		var k = decodeParam(e[1]), v = decodeParam(e[2]);
+		if(k.substring(k.length - 2) === '[]') {
+			k = k.substring(0, k.length - 2);
+			(params[k] || (params[k] = [])).push(v);
+		}
+		else {
+			params[k] = v;
+		}
+	}
+	return params;
+};
+
+// Get the query string from a url, returns an empty string if there is no query
+var urlQuery = function(url) {
+	return url.split('?')[1] || '';
+};
+
+globals.Grapple = {
+	Util: {
+		urlQuery: urlQuery,
+		parseUrlQuery: parseUrlQuery
+	}
+};
+
+})(window);