alphabetical_paginate 1.0.0 → 1.0.1

data/.gitignore

@@ -15,3 +15,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+*.swp

data/README.md

@@ -1,6 +1,13 @@
 # AlphabeticalPaginate
 
-TODO: Write a gem description
+A lightweight and highly customizable pagination gem for Ruby on Rails that generates alphabetic pagination categories from collection arrays. It allows you to select the field you want to paginate on. 
+
+By default, it works with [Bootstrap Pagination](http://twitter.github.io/bootstrap/components.html#pagination) CSS and it is also fully compatible with the [will_paginate](https://github.com/mislav/will_paginate) in case you want to use both. 
+
+AlphabeticalPaginate incorporates efficient partial page rerendering techniques and loading animations.
+
+Some code was inspired by [will_paginate](https://github.com/mislav/will_paginate).
+
 
 ## Installation
 
@@ -10,20 +17,104 @@ Add this line to your application's Gemfile:
 
 And then execute:
 
-    $ bundle
+    $ bundle install
+
+## Basic Setup
+
+Basic Pagination is as simple as adding a few lines to the controller and the view.
+
+### Controller
+You simply need to call alpha_paginate on the desired table (i.e. `User.all.alpha_paginate`). This method takes two parameters, the first always being `params[:letter]` and the second being an optional options hash. 
+
+Also, it takes a block in which you can specify the field you wish to paginate by (it can even be in another table). It returns the paginated subset of the collection, sorted by the pagination field. The method returns two values (the paginated array subsection, and an options hash), both of which must be stored as class variables. 
+
+*An example of its use is as such:*
+```ruby
+#app/controllers/users_controllers.rb
+class UsersController < ApplicationController
+
+  def index
+    @users, @alphaParams = User.all.alpha_paginate(params[:letter]){|user| user.name}
+  end
+  
+  ...
+end
+```
+
+### View
+You need to call `alphabetical_paginate` that we just generated in the controller (i.e `<%= alphabetical_paginate @alphaParams %>`) in the view, whereever you would like to render the pagination selector div. You also **must wrap the content you want paginated in a div with id="pagination_table"**.
+
+You can place as many `<%= alphabetical_paginate @alphaParams =>` as you wish on the page, if you want to render multiple pagination divs.
+
+*An example is as such:*
+```html
+#app/controllers/users/index.html.erb
+
+<%= alphabetical_paginate @alphaParams %>
+
+<div id="pagination_table">
+  <% User.all.each do |user| %>
+    ...
+  <% end %>
+</div>
+```
+
+## Customization
+
+### Options
+The gem is highly customizable. The `alpha_paginate ` method takes a hash as an optional second parameter like such:
+
+```ruby
+#app/controllers/users_controllers.rb
+class UsersController < ApplicationController
+
+  def index
+    @users, @alphaParams = User.all.alpha_paginate(params[:letter], {:enumerate => false}){|user| user.name}
+  end
+  
+  ...
+end
+```
+
+The available options are as follows:
+
+Key | Value | Default |Description
+--- | --- | --- | ---
+`:enumerate` | `Boolean` | `false` | Whether you want the number field collapsed (all numbers go into `0`) or separate (`0`, `1`, `2`...).
+`:default_field` | `String` | `"a"` | Which field you want the page to default to on first load (`"0"`, `"a"`. `"*"`).
+`:paginate_all` | `Boolean` | `false` | Whether you want empty fields to still render in pagination.
+`:numbers` | `Boolean` | `true` | Whether you want numbers to be included in the pagination at all, either collapsed, or expanded (depending on `:enumerate`).
+`:others` | `Boolean` | `true` | Whether you want all other characters (non alphanumeric) to be included in the pagination at all.
+`:pagination_class` | `String` | `"pagination-centered"` | All the classes you would like to add to the rendered pagination selector div (for CSS purposes).
+
+## Advanced Pagination
+
+You can select a complex field to paginate by. Be careful, as this may be slow in large data sets.
+
+For instance, the following example paginates posts by the author's group's name (jumping across two tables).
+It still returns the Post objects despite whatever field you use to paginate / sort it by (It still auto-sorts by the pagination field).
+```ruby
+#app/controllers/users_controllers.rb
+class UsersController < ApplicationController
 
-Or install it yourself as:
+  def index
+    @posts, @alphaParams = Post.all.alpha_paginate(params[:letter]) do |post|
+      author = post.author
+      group = author.group
+    end
+  end
+  
+  ...
+end
+```
 
-    $ gem install alphabetical_paginate
+## Rails 3.0 and Lower
 
-## Usage
+The gem makes use of the Asset Pipeline, introduced in Rails 3.1. It still works with lower versions of Rails, however, you need to copy the assets over manually.
 
-TODO: Write usage instructions here
+Copy the contents of `vendor/assets/javascripts` of this repo into the `public/javascripts` of your app
+and also copy the contents of `vendor/assets/images` of this repo into the `public/images` of your app.
 
-## Contributing
+# Support
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+Please feel free to reach out and contact if you find the gem useful at all! Also, feel free to report / fix any bugs or add features.

data/alphabetical_paginate.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["lz781@nyu.edu"]
   spec.description   = "Alphabetical Pagination"
   spec.summary       = "Pagination"
-  spec.homepage      = "http://google.com"
+  spec.homepage      = "https://github.com/lingz/alphabetical_paginate"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files`.split($/)

data/lib/alphabetical_paginate/array.rb

@@ -33,6 +33,6 @@ class Array
     end
     params[:availableLetters] = availableLetters.collect{|k,v| k.to_s}
     params[:currentField] = current_field
-    return output, params
+    return output.sort, params
   end
 end

data/lib/alphabetical_paginate/version.rb

@@ -1,3 +1,3 @@
 module AlphabeticalPaginate
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

data/vendor/assets/javascripts/alphabetical_paginate.js

@@ -1,45 +1,45 @@
 $(function() {
-    var once = false;
+  var once = false;
 
-    var img = "<img src='/images/loader.gif' class='loading'/>"
-    
-    $(document).on("click", ".pagination#alpha a", function(e) {
-        var url = location.href,
-            letter = $(this).data("letter");
-        if (/letter/.test(url)){
-          url = url.replace(/letter=?./,"letter=" + letter); 
+  var img = "<img src='/images/aloader.gif' class='loading'/>";
+  
+  $(document).on("click", ".pagination#alpha a", function(e) {
+      var url = location.href,
+          letter = $(this).data("letter");
+      if (/letter/.test(url)){
+        url = url.replace(/letter=?./,"letter=" + letter); 
+      }
+      else {
+        if (/\?/.test(url)) {
+          url += "&letter=" + letter;
         }
         else {
-          if (/\?/.test(url)) {
-            url += "&letter=" + letter
-          }
-          else {
-            url += "?letter=" + letter 
-          }
+          url += "?letter=" + letter;
         }
-        $(".pagination").html(img);
-        //$.load(url + " #pagination_table");
-        $.get(url, function(result) {
-          $(".pagination").html($(".pagination", result));
-          $("#pagination_table").html($("#pagination_table", result));
-        });
-        history.pushState(null, document.title, url);
-        e.preventDefault();
-    });
-
-
- // let navigate the browser throught the ajax history
-$(window).bind("popstate", function() {
-  if (once) {
-    $(".pagination").html(img);
-    $.get(location.href, function(result) {
-      $(".pagination").html($(".pagination", result));
+      }
+      $(".pagination").html(img);
+      //$.load(url + " #pagination_table");
+      $.get(url, function(result) {
+        $(".pagination").html($(".pagination", result));
         $("#pagination_table").html($("#pagination_table", result));
       });
-    } else {
-      once = true;
-    }
-});
+      history.pushState(null, document.title, url);
+      e.preventDefault();
+  });
+
+
+   // let navigate the browser throught the ajax history
+  $(window).bind("popstate", function() {
+    if (once) {
+      $(".pagination").html(img);
+      $.get(location.href, function(result) {
+        $(".pagination").html($(".pagination", result));
+          $("#pagination_table").html($("#pagination_table", result));
+        });
+      } else {
+        once = true;
+      }
+  });
 
 
 });

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: alphabetical_paginate
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
   prerelease: 
 platform: ruby
 authors:
@@ -89,21 +89,18 @@ files:
 - Rakefile
 - alphabetical_paginate.gemspec
 - lib/alphabetical_paginate.rb
-- lib/alphabetical_paginate/.array.rb.swp
-- lib/alphabetical_paginate/.view_helpers.rb.swp
 - lib/alphabetical_paginate/array.rb
 - lib/alphabetical_paginate/engine.rb
 - lib/alphabetical_paginate/railtie.rb
 - lib/alphabetical_paginate/version.rb
 - lib/alphabetical_paginate/view_helpers.rb
-- spec/.alpha_example.rb.swp
-- spec/.alphabetical_paginate_spec.rb.swp
 - spec/alpha_example.rb
 - spec/alphabetical_paginate_spec.rb
 - spec/support/helpers.rb
+- vendor/assets/images/aloader.gif
 - vendor/assets/javascripts/alphabetical_paginate.js
 - vendor/assets/javascripts/index.js
-homepage: http://google.com
+homepage: https://github.com/lingz/alphabetical_paginate
 licenses:
 - MIT
 post_install_message: 
@@ -129,8 +126,6 @@ signing_key:
 specification_version: 3
 summary: Pagination
 test_files:
-- spec/.alpha_example.rb.swp
-- spec/.alphabetical_paginate_spec.rb.swp
 - spec/alpha_example.rb
 - spec/alphabetical_paginate_spec.rb
 - spec/support/helpers.rb