nether 0.0.2 → 0.0.3

data/MIT-LICENSE

@@ -1,20 +1,20 @@
-Copyright 2012 Matthew Cross
-
-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.
+Copyright 2012 Matthew Cross
+
+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.rdoc

@@ -1,41 +1,34 @@
-= Nether
-My first attempt at a rails gem, Nether is an engine for easily adding endless page functionality to content paginated 
-by will_paginate in your rails 3.1 application.
-
-It uses jquery.pageless[https://github.com/jney/jquery.pageless] and is based heavily on their demo application.
-
-== Requirements
-Currently only supports apps using the assets pipeline and will_paginate.
-
-== Installation
-Add the following to your Gemfile and run the bundle command.
-
-  gem 'nether'
-	
-Once the gem is installed execute the generator to install the js files and images.
-
-  rails generate nether:install
-	
-== Usage
-Endless page functionality is handled by a helper function that takes three arguments by default.
-The total number of pages undergoing pagination, the path to get more content and the css id of the
-dom object to render. There is also an optional fourth argument for specifying the dom object 
-containing the content to be rendered.
-
-To use the helper add the following to your view after the will paginate helper, replacing 
-variables as necessary.
-
-  <%= nether(@articles.total_pages, articles_path, "#content" %>
-
-You must also add a helper to the action handling the pagination. The helper takes the partial to render 
-as an argument and an optional argument to delay rendering.
-
-  render_nether("articles/article")
-  
-== Help
-You will find an example app at nether_example[https://github.com/maecro/nether_example].
-	
-== Todo
-* Remove dependancy on assets pipeline.
-* Compatability with other pagination solutions.
-* Test, test, test.
+= Nether
+Nether is a rails engine for easily adding endless page functionality to paginated content. It uses jquery.pageless[https://github.com/jney/jquery.pageless] and is based heavily on their demo application.
+
+== Requirements
+Currently only supports apps using the assets pipeline.
+
+== Installation
+Add the following to your Gemfile and run the bundle command.
+
+  gem 'nether'
+	
+Once the gem is installed execute the generator to install the js files and images.
+
+  rails generate nether:install
+	
+== Usage (will_paginate)
+Endless page functionality is handled by a helper function that takes three arguments by default. The number of pages, the path to get more content and the css id of the dom object to render. There is also an optional fourth argument for specifying the dom object containing the content to be rendered.
+
+To use the helper add the following to your view after the will paginate helper, replacing variables as necessary.
+
+  <%= nether(@articles.total_pages, articles_path, "#content" %>
+
+You must also add a helper to the action handling the pagination. The helper takes the partial to render as an argument and an optional argument to delay rendering.
+
+  render_nether("articles/article")
+
+== Usage (kaminari)
+Usage is the same as for will_paginate, however the method num_pages is instead used to return the number of pages.
+
+  <%= nether(@articles.num_pages, articles_path, "#content") %>
+  
+== Help
+* You will find an example app at nether_example[https://github.com/maecro/nether_example].
+* The wiki[https://github.com/maecro/nether/wiki] contains other useful information and examples.

data/Rakefile

@@ -1,37 +1,37 @@
-#!/usr/bin/env rake
-begin
-  require 'bundler/setup'
-rescue LoadError
-  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
-end
-begin
-  require 'rdoc/task'
-rescue LoadError
-  require 'rdoc/rdoc'
-  require 'rake/rdoctask'
-  RDoc::Task = Rake::RDocTask
-end
-
-RDoc::Task.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'Nether'
-  rdoc.options << '--line-numbers'
-  rdoc.rdoc_files.include('README.rdoc')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
-
-
-Bundler::GemHelper.install_tasks
-
-require 'rake/testtask'
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib'
-  t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = false
-end
-
-
-task :default => :test
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Nether'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/app/controllers/nether_controller.rb

@@ -1,8 +1,8 @@
-module NetherController
-  def render_nether(partial, delay=3)
-      if request.xhr?
-      sleep(delay)
-      render :partial => partial
-    end
-  end
+module NetherController
+  def render_nether(partial, delay=3)
+      if request.xhr?
+      sleep(delay)
+      render :partial => partial
+    end
+  end
 end

data/app/helpers/nether_helper.rb

@@ -1,13 +1,13 @@
-module NetherHelper
-  def nether(total_pages, url=nil, identifier=nil, container=nil)
-    opts = {
-      :totalPages => total_pages,
-      :url        => escape_javascript(url),
-      :loaderMsg  => 'Loading more results'
-    }
-  
-    container && opts[:container] ||= container
-  
-    javascript_tag("$('#{identifier}').pageless(#{opts.to_json});")
-  end
+module NetherHelper
+  def nether(total_pages, url=nil, identifier=nil, container=nil)
+    opts = {
+      :totalPages => total_pages,
+      :url        => escape_javascript(url),
+      :loaderMsg  => 'Loading more results'
+    }
+  
+    container && opts[:container] ||= container
+  
+    javascript_tag("$('#{identifier}').pageless(#{opts.to_json});")
+  end
 end

data/lib/generators/nether/install/USAGE

@@ -1,19 +1,19 @@
-Description:
-    The install generator downloads jquery.pageless from
-    github to assets/javascripts.
-
-
-Options:
-
-Examples:
-    rails generate nether:install
-
-        This will create two files:
-            Layout:     app/views/layouts/application.rhtml
-            Stylesheet: public/stylesheets/application.css
-
-
-    ./script/generate app_layout myname --no-css
-
-        This will create one file:
+Description:
+    The install generator downloads jquery.pageless from
+    github to assets/javascripts.
+
+
+Options:
+
+Examples:
+    rails generate nether:install
+
+        This will create two files:
+            Layout:     app/views/layouts/application.rhtml
+            Stylesheet: public/stylesheets/application.css
+
+
+    ./script/generate app_layout myname --no-css
+
+        This will create one file:
             Layout:     app/views/layouts/myname.rhtml

data/lib/generators/nether/install/install_generator.rb

@@ -1,9 +1,9 @@
-module Nether
-  class InstallGenerator < Rails::Generators::Base
-    source_root File.expand_path('../templates', __FILE__)
-    def install_pageless
-      copy_file "jquery.pageless.js.erb", "app/assets/javascripts/jquery.pageless.js.erb"
-      copy_file "load.gif", "app/assets/images/load.gif"
-    end
-  end
+module Nether
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path('../templates', __FILE__)
+    def install_pageless
+      copy_file "jquery.pageless.js.erb", "app/assets/javascripts/jquery.pageless.js.erb"
+      copy_file "load.gif", "app/assets/images/load.gif"
+    end
+  end
 end

data/lib/generators/nether/install/templates/jquery.pageless.js.erb

@@ -1,179 +1,179 @@
-// =======================================================================
-// PageLess - endless page
-//
-// Pageless is a jQuery plugin.
-// As you scroll down you see more results coming back at you automatically.
-// It provides an automatic pagination in an accessible way : if javascript 
-// is disabled your standard pagination is supposed to work.
-//
-// Licensed under the MIT:
-// http://www.opensource.org/licenses/mit-license.php
-//
-// Parameters:
-//    currentPage: current page (params[:page])
-//    distance: distance to the end of page in px when ajax query is fired
-//    loader: selector of the loader div (ajax activity indicator)
-//    loaderHtml: html code of the div if loader not used
-//    loaderImage: image inside the loader
-//    loaderMsg: displayed ajax message
-//    pagination: selector of the paginator divs. 
-//                if javascript is disabled paginator is provided
-//    params: paramaters for the ajax query, you can pass auth_token here
-//    totalPages: total number of pages
-//    url: URL used to request more data
-//
-// Callback Parameters:
-//    scrape: A function to modify the incoming data.
-//    complete: A function to call when a new page has been loaded (optional)
-//    end: A function to call when the last page has been loaded (optional)
-//
-// Usage:
-//   $('#results').pageless({ totalPages: 10
-//                          , url: '/articles/'
-//                          , loaderMsg: 'Loading more results'
-//                          });
-//
-// Requires: jquery
-//
-// Author: Jean-Sébastien Ney (https://github.com/jney)
-//
-// Contributors:
-//   Alexander Lang (https://github.com/langalex)
-//   Lukas Rieder (https://github.com/Overbryd)
-//
-// Thanks to:
-//  * codemonky.com/post/34940898
-//  * www.unspace.ca/discover/pageless/
-//  * famspam.com/facebox
-// =======================================================================
-
-(function($) {
-  
-  var FALSE = !1
-    , TRUE = !FALSE
-    , element
-    , isLoading = FALSE
-    , loader
-    , namespace = '.pageless'
-    , SCROLL = 'scroll' + namespace
-    , RESIZE = 'resize' + namespace
-    , settings = { container: window
-                 , currentPage: 1
-                 , distance: 100
-                 , pagination: '.pagination'
-                 , params: {}
-                 , url: location.href
-                 , loaderImage: "<%= asset_path 'load.gif' %>"
-                 }
-    , container
-    , $container;
-    
-  $.pageless = function(opts) {
-    $.isFunction(opts) ? settings.call() : init(opts);
-  };
-  
-  var loaderHtml = function () {
-    return settings.loaderHtml || '\
-<div id="pageless-loader" style="display:none;text-align:center;width:100%;">\
-  <div class="msg" style="color:#e9e9e9;font-size:2em"></div>\
-  <img src="' + settings.loaderImage + '" alt="loading more results" style="margin:10px auto" />\
-</div>';
-  };
- 
-  // settings params: totalPages
-  var init = function (opts) {
-    if (settings.inited) return;
-    settings.inited = TRUE;
-    
-    if (opts) $.extend(settings, opts);
-    
-    container = settings.container;
-    $container = $(container);
-    
-    // for accessibility we can keep pagination links
-    // but since we have javascript enabled we remove pagination links 
-    if(settings.pagination) $(settings.pagination).remove();
-    
-    // start the listener
-    startListener();
-  };
-  
-  $.fn.pageless = function (opts) {
-    var $el = $(this)
-      , $loader = $(opts.loader, $el);
-      
-    init(opts);
-    element = $el;
-    
-    // loader element
-    if (opts.loader && $loader.length) {
-      loader = $loader;
-    } else {
-      loader = $(loaderHtml());
-      $el.append(loader);
-      // if we use the default loader, set the message
-      if (!opts.loaderHtml) {
-        $('#pageless-loader .msg').html(opts.loaderMsg);
-      }
-    }
-  };
-  
-  //
-  var loading = function (bool) {
-    (isLoading = bool)
-    ? (loader && loader.fadeIn('normal'))
-    : (loader && loader.fadeOut('normal'));
-  };
-  
-  // distance to end of the container
-  var distanceToBottom = function () {
-    return (container === window)
-         ? $(document).height() 
-         - $container.scrollTop() 
-         - $container.height()
-         : $container[0].scrollHeight 
-         - $container.scrollTop() 
-         - $container.height();
-  };
-
-  var stopListener = function() {
-    $container.unbind(namespace);
-  };
-  
-  // * bind a scroll event
-  // * trigger is once in case of reload
-  var startListener = function() {
-    $container.bind(SCROLL+' '+RESIZE, watch)
-              .trigger(SCROLL);
-  };
-  
-  var watch = function() {
-    // listener was stopped or we've run out of pages
-    if (settings.totalPages <= settings.currentPage) {
-      stopListener();
-      // if there is a afterStopListener callback we call it
-      if (settings.end) settings.end.call();
-      return;
-    }
-    
-    // if slider past our scroll offset, then fire a request for more data
-    if(!isLoading && (distanceToBottom() < settings.distance)) {
-      loading(TRUE);
-      // move to next page
-      settings.currentPage++;
-      // set up ajax query params
-      $.extend( settings.params
-              , { page: settings.currentPage });
-      // finally ajax query
-      $.get( settings.url
-           , settings.params
-           , function (data) {
-               $.isFunction(settings.scrape) ? settings.scrape(data) : data;
-               loader ? loader.before(data) : element.append(data);
-               loading(FALSE);
-               // if there is a complete callback we call it
-               if (settings.complete) settings.complete.call();
-           }, 'html');
-    }
-  };
+// =======================================================================
+// PageLess - endless page
+//
+// Pageless is a jQuery plugin.
+// As you scroll down you see more results coming back at you automatically.
+// It provides an automatic pagination in an accessible way : if javascript 
+// is disabled your standard pagination is supposed to work.
+//
+// Licensed under the MIT:
+// http://www.opensource.org/licenses/mit-license.php
+//
+// Parameters:
+//    currentPage: current page (params[:page])
+//    distance: distance to the end of page in px when ajax query is fired
+//    loader: selector of the loader div (ajax activity indicator)
+//    loaderHtml: html code of the div if loader not used
+//    loaderImage: image inside the loader
+//    loaderMsg: displayed ajax message
+//    pagination: selector of the paginator divs. 
+//                if javascript is disabled paginator is provided
+//    params: paramaters for the ajax query, you can pass auth_token here
+//    totalPages: total number of pages
+//    url: URL used to request more data
+//
+// Callback Parameters:
+//    scrape: A function to modify the incoming data.
+//    complete: A function to call when a new page has been loaded (optional)
+//    end: A function to call when the last page has been loaded (optional)
+//
+// Usage:
+//   $('#results').pageless({ totalPages: 10
+//                          , url: '/articles/'
+//                          , loaderMsg: 'Loading more results'
+//                          });
+//
+// Requires: jquery
+//
+// Author: Jean-Sébastien Ney (https://github.com/jney)
+//
+// Contributors:
+//   Alexander Lang (https://github.com/langalex)
+//   Lukas Rieder (https://github.com/Overbryd)
+//
+// Thanks to:
+//  * codemonky.com/post/34940898
+//  * www.unspace.ca/discover/pageless/
+//  * famspam.com/facebox
+// =======================================================================
+
+(function($) {
+  
+  var FALSE = !1
+    , TRUE = !FALSE
+    , element
+    , isLoading = FALSE
+    , loader
+    , namespace = '.pageless'
+    , SCROLL = 'scroll' + namespace
+    , RESIZE = 'resize' + namespace
+    , settings = { container: window
+                 , currentPage: 1
+                 , distance: 100
+                 , pagination: '.pagination'
+                 , params: {}
+                 , url: location.href
+                 , loaderImage: "<%= asset_path 'load.gif' %>"
+                 }
+    , container
+    , $container;
+    
+  $.pageless = function(opts) {
+    $.isFunction(opts) ? settings.call() : init(opts);
+  };
+  
+  var loaderHtml = function () {
+    return settings.loaderHtml || '\
+<div id="pageless-loader" style="display:none;text-align:center;width:100%;">\
+  <div class="msg" style="color:#e9e9e9;font-size:2em"></div>\
+  <img src="' + settings.loaderImage + '" alt="loading more results" style="margin:10px auto" />\
+</div>';
+  };
+ 
+  // settings params: totalPages
+  var init = function (opts) {
+    if (settings.inited) return;
+    settings.inited = TRUE;
+    
+    if (opts) $.extend(settings, opts);
+    
+    container = settings.container;
+    $container = $(container);
+    
+    // for accessibility we can keep pagination links
+    // but since we have javascript enabled we remove pagination links 
+    if(settings.pagination) $(settings.pagination).remove();
+    
+    // start the listener
+    startListener();
+  };
+  
+  $.fn.pageless = function (opts) {
+    var $el = $(this)
+      , $loader = $(opts.loader, $el);
+      
+    init(opts);
+    element = $el;
+    
+    // loader element
+    if (opts.loader && $loader.length) {
+      loader = $loader;
+    } else {
+      loader = $(loaderHtml());
+      $el.append(loader);
+      // if we use the default loader, set the message
+      if (!opts.loaderHtml) {
+        $('#pageless-loader .msg').html(opts.loaderMsg);
+      }
+    }
+  };
+  
+  //
+  var loading = function (bool) {
+    (isLoading = bool)
+    ? (loader && loader.fadeIn('normal'))
+    : (loader && loader.fadeOut('normal'));
+  };
+  
+  // distance to end of the container
+  var distanceToBottom = function () {
+    return (container === window)
+         ? $(document).height() 
+         - $container.scrollTop() 
+         - $container.height()
+         : $container[0].scrollHeight 
+         - $container.scrollTop() 
+         - $container.height();
+  };
+
+  var stopListener = function() {
+    $container.unbind(namespace);
+  };
+  
+  // * bind a scroll event
+  // * trigger is once in case of reload
+  var startListener = function() {
+    $container.bind(SCROLL+' '+RESIZE, watch)
+              .trigger(SCROLL);
+  };
+  
+  var watch = function() {
+    // listener was stopped or we've run out of pages
+    if (settings.totalPages <= settings.currentPage) {
+      stopListener();
+      // if there is a afterStopListener callback we call it
+      if (settings.end) settings.end.call();
+      return;
+    }
+    
+    // if slider past our scroll offset, then fire a request for more data
+    if(!isLoading && (distanceToBottom() < settings.distance)) {
+      loading(TRUE);
+      // move to next page
+      settings.currentPage++;
+      // set up ajax query params
+      $.extend( settings.params
+              , { page: settings.currentPage });
+      // finally ajax query
+      $.get( settings.url
+           , settings.params
+           , function (data) {
+               $.isFunction(settings.scrape) ? settings.scrape(data) : data;
+               loader ? loader.before(data) : element.append(data);
+               loading(FALSE);
+               // if there is a complete callback we call it
+               if (settings.complete) settings.complete.call();
+           }, 'html');
+    }
+  };
 })(jQuery);