pox_paginate

= PoxPaginate 0.2.5

PoxPaginate is an extension to WillPaginate and ActiveResource that makes it possible to transparently paginate over a collection of XML serialised resources.

This gem is based on our experience building largish distributed systems consisting of multiple Rails apps integrated over POX (Plain Old XML). Yes, it is in production. No, unfortunately we aren’t allowed to talk about it.

== Installation

PoxPaginate is available as a gem. In your Gemfile add
gem ‘pox_paginate’, ‘~> 0.2.0’ # Please check for the latest version

We also strongly recommend you use Ruby LibXML or Nokogiri rather than the standard REXML for deserialisation. While PoxPaginate supports all three, REXML is simply too slow for use in production. To switch to using either gem:
gem ‘nokogiri’, ‘~> 1.4.3.1’
or
gem ‘libxml-ruby’, ‘~> 1.1.4’

• These gems are not added in the Gemfile

After this, you need to instruct Rails to use them. In application.rb, do
ActiveSupport::XmlMini.backend = ‘LibXML’
or
ActiveSupport::XmlMini.backend = ‘Nokogiri’

JDOM is supported as a backend on JRuby
ActiveSupport::XmlMini.backend = ‘JDOM’

== Usage

When constructing the xml serialised form of a resource in a controller, add pagination - like so:
class ProductsController < ApplicationController

# GET /products
# GET /products.xml
def index
  @products = Product.paginate :page => params[:page], :per_page => params[:per_page]
  respond_to do |format|
    format.html # index.html.erb
    format.xml  { render :xml => @products }
  end
end
...
...
...

end

PoxPaginate extends WillPaginate::Collection to add ‘current_page,’ ‘per_page’ and ‘total_entries’ as attributes on the root node of the collection xml.

On the client, you do the usual:
class Product < ActiveResource::Base
self.site = ‘http://oogabooga.in’
end

Now whenever you do
Product.find(:all, :params => {:page => 2, :per_page => 5})

PoxPaginate will kick in if pagination related attributes are present on the root node, and will result in the creation of a PoxPaginate::RemoteCollection, which is a subclass of WillPaginate::Collection and so behaves in exactly the same manner.

=== Note

• PoxPaginate currently overrides the Hash.from_xml method to fix a bug in Rails that is documented in this {Rails issue}[https://github.com/rails/rails/issues/636]
• This patch is merged in Rail head (not in RC6)
• PoxPaginate must needs be installed on both the client and the server Rails instance

== Continuous Itegration

You can find the link to the pox_paginate CI build over at the C42 Engineering {open source}[http://c42.in/open_source] page.

== How to contribute

• Create an {issue}[http://github.com/c42/pox_paginate/issues] describing what you’re adding (or fixing)
• Fork pox_paginate
• Make your changes, including specs, with the issue number in the commit message
• Run the build (running rake should do it) to make sure everything is all right
• Send us a pull request

If your patch is accepted, we will add you to the ‘Contributors’ section of the README.

== Contributors

• {Sidu Ponnappa}[http://github.com/kaiwren]
• {Niranjan Paranjape}[http://github.com/niranjan]
• {Jean-Denis Vauguet}[http://github.com/chikamichi]
• {klacointe }[http://github.com/klacointe]