Rails endless page plugin

Few days ago I have looked for implementation of the 'endless page' in the Rails. When I'm talking about endless pages I mean alternative to the standard paging used all over Internet. Alternative variant works like initial list of items that sends background Ajax requests and adds received data to the end of list. You can see examples in the DZone and Google Reader if you want. I have googled a lot and talked with authors of various articles related to this functionality. It seems like, there was no such Rails plugins and I have decided to create it.

Theory.
Common view on the functionality. When user opens web page in the background JavaScript timer starts and periodically checks position of the scroller. If user scrolled page and scroller is in the bottom part of scrollbar then Ajax request is sended and additional data recieved and added to the bottom of initial page. If user have recieved all existing data then timer is stopped.

Software need to have.
Plugin doesn't require any gems or plugins installed. Ajax request is executed using Prototype library.

Example of usage.
In the beginning we should have basic Rails application that is easy to create so I'll not tell about this part of project. It should be simple index page with list of items limited by, lets say, 500 first items. Each item look and feel is set by Rails partial.

These are steps needed to implement:
0) Download plugin by entering 'ruby script/plugin install git://github.com/shine/endless_page' in the project root folder. In the vendor/plugins/endless_page folder enter 'ruby install.rb'. During installation endless_page folder will be created in the app/views. Several files will be copied to the new folder and to the public/javascripts.

1)Controller. In the index action session variable setting should be added. Variable will contain id of last item shown to the user:

def index
@articles = Article.find(:all, :order => 'id', :limit => '500')

session[:last_article] = @articles.last.id.to_s
end

2)Additional method should process Ajax request:

def append_items
@additional_objects = Article.find(:all, :conditions => [params[:sort_by]+' > '+session[:last_article]], :limit => '100')

if @additional_objects.blank?
render :template => '/endless_page/have_nothing_to_add'
else
session[:last_article] = @additional_objects.last.id.to_s
render :template => '/endless_page/append'
end
end

Here is one important detail: name of the array passed to the RJS should be @additional_objects. Otherwise RJS will have nothing to process. If..else..end block should be equal for the all implementations of endless pages in the project with exception of session variable name, of course.

3) View. In the head of the page Prototype library and additional JS file with plugin related functions should be included:

<%= javascript_include_tag :defaults %>
<%= javascript_include_tag 'endless_page' %>

4) HTML component that will contain elements added by Ajax should have "id" attribute. The most simple variant of this attribute value will be 'container'. If you need to change it then you will see a way to do so below.

5) After HTML container there should be script that will configure and run JavaScript timer:

<script type="text/javascript">
var ep_config = new EPConfig();

ep_config.auth_token = encodeURIComponent('<%= form_authenticity_token%>');
ep_config.url = '<%= url_for(:controller => 'articles', :action => 'append_items')%>';
ep_config.partial = '/articles/item';

start_endless_page_listener(ep_config);
</script>

In the beginning we are creating configuration object with several default values. After that we are setting few attributes that are unique for each endless page: Rails auth token, url of the controller/action that should proces Ajax request and partial that should be used to show new added items. Finally, we are starting JavaScript scroller checker.

If you need to change container id then you can do it before start of listener by adding next line:

ep_config.container = 'my_favourite_name';

Additionally, you can change other settings like period of scroller checking, point of Ajax activation and so on. Full list you can see in the bottom of the endless_page.js in the public/javascripts folder.

It seems like enough for plugin usage.

Any thoughts and comments are welcome.

Update: some JavaScript changes were made