README.md in ajax_pagination-0.2.0 vs README.md in ajax_pagination-0.3.0
- old
+ new
@@ -1,24 +1,14 @@
# AJAX Pagination
[](http://travis-ci.org/ronalchn/ajax_pagination)
+[Wiki](https://github.com/ronalchn/ajax_pagination/wiki) | [RDoc](http://rdoc.info/gems/ajax_pagination/frames) | [Changelog](https://github.com/ronalchn/ajax_pagination/blob/master/CHANGELOG.md)
+
Handles AJAX pagination for you, by hooking up the links you want to load content with javascript in designated page containers. Each webpage can have multiple page containers, each with a different set of pagination links. The page containers can be nested. Degrades gracefully when javascript is disabled.
-## Introduction
-This gem can ajaxify any pagination solution. Links wrapped in containers with specific classes will be ajaxified. This means that clicking it will instead send an AJAX request for the page in javascript format. The result will replace the content in a container for the content. this gem is tested to work with will_paginate, but should work for other pagination solutions, as well as navigation level links or tabbed interfaces. The ajax call will load new content into the designated content container.
+For more, see [Introduction and Background](https://github.com/ronalchn/ajax_pagination/wiki/Introduction-and-Background).
-Please note, this is not a pagination solution by itself. You should use a pagination solution such as will_paginate and Kaminari, or a menu builder such as Simple-navigation or Semantic-menu, or you can roll your own. After that is implemented, you can use AJAX Pagination to ajaxify it, so that when users change pages, they do not have the reload the whole page.
-
-## Background
-This gem depends on Rails 3.1+, jQuery and jquery-historyjs. The gem was extracted from http://github.com/xrymbos/nztrain-v2/, and further development will be tied to the needs of the application. Therefore, some dependencies are because the application uses a particular version of these other gems. If you need to use this in other versions/javascript frameworks, I would welcome any pull requests. They are not currently supported because I do not need to use this gem in those other frameworks.
-
-The original AJAX pagination functionality was inspired by the RailsCasts on pagination with AJAX. However, other functionality was added to the pagination, and more modular code was desired, especially when many different controllers need pagination. Added functionality includes loading cues and support of multiple pagination areas on the same webpage.
-
-Because the code became more modular, it also made it suitable to turn into a Ruby Gem, so that others can create AJAX pagination without fiddling with the details.
-
-Rails 3.1+ is required only because the javascript is placed into the assets pipeline.
-
## Installation
Add to your Gemfile:
gem 'ajax_pagination'
@@ -32,18 +22,19 @@
AJAX Pagination depends on jquery-rails and jquery-historyjs, so if their javascript files are not already included, also include to following in your assets/javascripts/application.js file:
```javascript
//= require jquery
+//= require jquery_ujs
//= require history
```
## Getting Started
The next section presents the usage of the functions in detail. However, it also presents the different options that can be chosen. For a simpler overview of how you can easily use this gem, please read one of the more specific guides below (found in the wiki):
-* [Add AJAX to will_paginate](https://github.com/ronalchn/ajax_pagination/wiki/Adding-AJAX-to-will_paginate)
-* [Add AJAX to site navigation](https://github.com/ronalchn/ajax_pagination/wiki/Adding-AJAX-to-site-navigation)
+* [Adding AJAX to will_paginate](https://github.com/ronalchn/ajax_pagination/wiki/Adding-AJAX-to-will_paginate)
+* [Adding AJAX to site navigation](https://github.com/ronalchn/ajax_pagination/wiki/Adding-AJAX-to-site-navigation)
and much [more](https://github.com/ronalchn/ajax_pagination/wiki/Home).
## Usage
@@ -75,16 +66,18 @@
This will cause it to display content in the _mypartial.* view.
If you are using will_paginate, and the links are wrapped in a div with class="pagination", the links will be ajaxified automatically.
-Otherwise, you should wrap the links with a container. We recommend that the class given is "ajaxpagination". You can put the links inside the partial, for example:
+Otherwise, you can wrap a set of links with a container. We recommend that the class given is "ajaxpagination". You can put the links inside the partial, for example:
```html
<div class="ajaxpagination"><a href="#">My ajaxified link</a></div>
```
+If you want to ajaxify individual links, check out the ajax_link_to helper (shown later), which is more flexible (can handle non-GET requests). Wrapping links in a container is actually just a convenience feature, which internally does the same things ajax_link_to does.
+
If you are using will_paginate, you can simply put the links inside the partial (so that the new links get reloaded when the page changes):
```erb
<%= will_paginate @objects, :params => { :pagination => nil } %>
```
@@ -194,11 +187,11 @@
<% end %>
```
Links outside are still clickable (such as the will_paginate links).
-The loading image is currently an image asset at "ajax-loader.gif", so put your loading image there. You can specify a new default filename in your initializer.
+The loading image is currently an image asset at "ajax-loader.gif", so put your loading image there. You can specify a new default filename in your initializer. If you want a different loading image (other than configuring a site-wide default), you can pass an option :image => "newimageinassetpipeline.gif" to the ajax_pagination view helper method.
If you want all the content in the partial (or otherwise wrapped by the ajax_pagination helper method) to be included as a loading zone (with the visual loading cues), you can instead, set the :loadzone option to true, eg:
```erb
<%= ajax_pagination :pagination => "menu", :reload => {:urlpart => "path", :urlregex => "^.*$"}, :loadzone => true do %>
@@ -206,11 +199,11 @@
<% end %>
```
In this case, whatever is inside the yield will not need to call ajax_pagination_loadzone.
-### Content reloading
+### Browser History
The back and forward buttons on your browser may not work properly yet. It will work as long as the link includes distinct query parameter with the same name as the pagination name for the set. For example, if the name of the pagination set is "page" (the default), when the browser url changes, AJAX Pagination looks for a change in the links query parameter with the same name, such as if the url changes from /path/to/controller?page=4 to /path/to/controller?page=9, then AJAX Pagination knows that the content corresponding to the pagination set needs reloading. The absence of the parameter is a distinct state, so changes such as /path/to/controller to /path/to/controller?page=0 are detected.
However, if the pagination is to different controllers, eg. url changes from /ControllerA to /ControllerB, AJAX Pagination will not reload the content, because the name of the pagination set is "page", and the url ?page=... parameter has not changed. There are some options that can be passed to ajax_pagination, through the reload option.
@@ -232,14 +225,53 @@
```erb
<%= ajax_pagination :reload => [{:urlregex => "page=([0-9]+)", :regexindex => 1},{:query => "watching"}] %>
```
-Instead of passing in the Array/Hash Ruby object, a string in json form is accepted:
+Sometimes, you may have a small section of the page which is paginated, but for which you do not want to change the url. In effect, the page you are on should remain the same, simply with a cool effect, which changes the content displayed. This would mean that the new content loaded does not add to browser history.
+By default, the url does get changed, and browser history is added to. To turn this off, you can set :history => false, eg:
+
```erb
-<%= ajax_pagination :reload => '[{"urlregex":"page=([0-9]+)","regexindex":1},{"query":"page"}]' %>
+<%= ajax_pagination :history => false %>
```
+
+When history is turned off, by default, reload is also set to never reload the content.
+
+### Link and Form helpers
+For individual links, you can ajaxify them using ajax_link_to with the same format as the link_to helper, but making sure to pass a pagination option:
+
+```erb
+<%= ajax_link_to "Name", posts_url, :pagination => "page" %>
+```
+
+Similarly, there exist AJAX form helpers, again with the same format as the original form helpers:
+
+```erb
+<%= ajax_form_tag posts_url, :method => "post", :class => "myclass", :pagination => "page" do %>
+ ...
+<% end %>
+
+<%= ajax_form_for @post, :method => "post", :html => {:class => "myclass", :pagination => "menu"} do %>
+ ...
+<% end %>
+```
+
+Note that these form helpers actually use another helper method ajax_options, with the original non-ajax helpers. This means that you can also use:
+
+```erb
+<%= link_to "Name", posts_url, ajax_options :pagination => "page" %>
+
+<%= form_tag posts_url, ajax_options :method => "post", :class => "myclass", :pagination => "page" do %>
+ ...
+<% end %>
+
+<%= form_for @post, :method => "post", :html => ajax_options({:class => "myclass", :pagination => "menu"}) do %>
+ ...
+<% end %>
+```
+
+This is actually a powerful feature, because though you would simply use the ajax_link_to, ajax_form_tag, ajax_form_for tags as shorthand, if you are using another helper method (eg. one from Formtastic or Simple Form gems), you can use ajax_options with that helper method.
### Initializer
You can configure AJAX Pagination in the initializer. Run ```
rails generate ajax_pagination:install
``` to get the initializer file.