README.md in ajax_pagination-0.0.2 vs README.md in ajax_pagination-0.1.0
- old
+ new
@@ -1,6 +1,7 @@
# AJAX Pagination
+[](http://travis-ci.org/ronalchn/ajax_pagination)
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.
@@ -66,26 +67,45 @@
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". For example:
+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:
```html
<div class="ajaxpagination"><a href="#">My ajaxified link</a></div>
```
-If you are using will_paginate, you can simply put this in the partial (so that the new links get reloaded when the page changes):
+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 } %>
```
Note: It is recommended to set the pagination parameter to nil. When AJAX pagination calls the controller with a request for the partial, it appends ?pagination=NAMEOFPAGINATION. If the parameter is not set, AJAX Pagination will not respond to the AJAX call. will_paginate by default keeps any parameters in the query string. However, because this parameter is for internal use only, setting it to nil will keep the parameter from showing up in the url, making it look nicer (also better for caching).
Now, AJAX Pagination will automatically call the controller for new content when an ajaxified link is clicked.
+If the links are outside the partial, you will need to also let AJAX Pagination know what content container should be reloaded when the links are followed. In this case, the div with ajaxpagination class should define the data-pagination attribute, the value corresponding to the name of the pagination content, for example you can do the following (which ajaxifies the menu navigation links):
+
+```erb
+<div class="ajaxpagination menu" data-pagination="menu">
+ <ul>
+ <li><%= link_to "Home", root_url %></li>
+ <li><%= link_to "Posts", posts_url %></li>
+ <li><%= link_to "Changelog", changelog_url %></li>
+ <li><%= link_to "Readme", pages_readme_url %></li>
+ <li><%= link_to "About", pages_about_url %></li>
+ </ul>
+</div>
+<%= ajax_pagination :pagination => "menu", :reload => {:urlpart => "path", :urlregex => "^.*$"} do %>
+ <%= yield %>
+<% end %>
+```
+
+Incidentally, this example also presents an alternative to passing in a :partial option to <tt>ajax_pagination</tt>. Instead, you can pass it a block, in which case you can call the render helper yourself, or any other function (in this case, yield). If a block is passed, any :partial option is ignored.
+
### Controller responder
However, the controller needs to be told how to respond. Add a call to <tt>ajax_pagination(format)</tt> in the controller action, which will return javascript containing the partial.
```ruby
@@ -103,11 +123,11 @@
The pagination should now work.
### Loading visualization
-AJAX Pagination can also add a loading image and partially blanking out of the paginated content. To do this, wrap all the content you want to cover with <tt>ajax_pagination_loadzone</tt>. For example, in the partial, you might have:
+AJAX Pagination can also add a loading image and partially blanking out of the paginated content. To do this, you can wrap all the content you want to cover with <tt>ajax_pagination_loadzone</tt>. For example, in the partial, you might have:
```erb
<%= will_paginate @objects, :params => { :pagination => nil } %>
<%= ajax_pagination_loadzone do %>
While this partial is being loaded with other content,
@@ -118,10 +138,20 @@
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. (TODO: add default loader image, and make the location changeable)
+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 %>
+ <%= yield %>
+<% end %>
+```
+
+In this case, whatever is inside the yield will not need to call ajax_pagination_loadzone.
+
### Content reloading
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.
@@ -149,11 +179,25 @@
Instead of passing in the Array/Hash Ruby object, a string in json form is accepted:
```erb
<%= ajax_pagination :reload => '[{"urlregex":"page=([0-9]+)","regexindex":1},{"query":"page"}]' %>
```
+## Example Application
+This gem contains an example application (actually, it is there also for testing purposes), however it is nevertheless a good example.
+Clone this repository, and run the server, using:
+
+```sh
+git clone git://github.com/ronalchn/ajax_pagination.git
+cd ajax_pagination
+cd spec/rails_app
+bundle install
+bundle exec rails server
+```
+
+Then point your browser to http://localhost:3000/
+
## AJAX Call
The AJAX Call is triggered by a link wrapped in any container with a certain class. The AJAX Call is to the same address, but with the ?pagination=NAME parameter added. The format requested is javascript. If the controller also returns javascript for other uses, AJAX Pagination does not necessarily prevent such uses. The ajax_pagination(format, :pagination => "page") function in the controller handles the AJAX Call when the format is javascript, and the ?pagination parameter is set to the correct string. It also returns true if the pagination parameter matches. Therefore, you can use use the javascript format when it does not match, as shown below:
```ruby
respond_to do |format|
@@ -171,12 +215,12 @@
format.js # index.js.erb
end
```
## Javascript Dependency
-As well as the included ajax_pagination.js file, this gem uses jquery.ba-bbq.js, a jquery plugin. This is included in the gem as an asset already to simplify installation. ajax_pagination.js will automatically require jquery.ba-bbq.js.
+As well as the included ajax_pagination.js file, this gem uses jquery.ba-bbq.js and jquery.url.js, which are jquery plugins. They are included in the gem as assets already to simplify installation. ajax_pagination.js will automatically require jquery.ba-bbq.js, and jquery.url.js.
-However, if you are already using this (especially a different version of this), simply ensure that your file is named jquery.ba-bbq.js as well, so that it overrides the file in the gem.
+However, if you are already using them (especially if using a different version), simply ensure that your assets directory contains javascript files of the same name to shadow/override the file in the gem.
The other javascript dependencies rely on gems: jquery-rails, and jquery-historyjs. So if they are used, AJAX Pagination should play well with other gems using the libraries.
## Development
You are welcome to submit pull requests on GitHub at https://github.com/ronalchn/ajax_pagination, however, please be aware that submitting a pull request is assumed to grant to me non-exclusive, perpetual rights to the use of the software for any use whatsoever. This allows me to release the software under a more permissible license in the future if I want.