A Brief Introduction of PaginableCollections

PaginableCollections is an open source set of extensions and abstractions created to give developers a consistent way to paginate their data.

Imagine an array of numbers:
array_of_numbers

With PaginableCollections, we are able to partition our number collection into sub-collections.

array_of_numbers_partition

A sub-collection can then be used to create a pagination-enabled user experience.

paginable_user_experiences

I want to note that PaginableCollections does not ship with any user interface elements - no HTML helpers, partial views, or anything like that. It is focused on providing the abstractions and extensions required to build these user interfaces.

Lets Look at Some Code!

To get started, we need the PaginableCollections package. This is available on NuGet using your favorite package manager:

Install-Package PaginableCollections

With the appropriate using statements in place, we can start writing some code.

var numbers = new int[] { 2, 4, 5, 1, 6, 8, 2, 0, 4, 3, 4, 1, 5, 9, 7, 0, 2, 4, 8, 9 };

First, define our number collection - this is our dataset.

var numbers = new int[] { 2, 4, 5, 1, 6, 8, 2, 0, 4, 3, 4, 1, 5, 9, 7, 0, 2, 4, 8, 9 };

var pageNumber = 2;
var itemCountPerPage = 6;

Next, define some local variables to contain our page information. In this example, we want the data from page 2, and the page size to be 6.

var numbers = new int[] { 2, 4, 5, 1, 6, 8, 2, 0, 4, 3, 4, 1, 5, 9, 7, 0, 2, 4, 8, 9 };

var pageNumber = 2;
var itemCountPerPage = 6;

var paginable = numbers.ToPaginable(pageNumber, itemCountPerPage);

Remember, PaginableCollections is a set of extensions; it works with all IEnumerable and IQueryable based collections. The ToPaginable extension method is used to return a paginable of data for the specified PageNumber and ItemCountPerPage. Wait..what is a paginable?

what_is_paginable

Here is how I explained it - a paginable is an enumerable with some additional metadata.

paginable-diagram

PageNumber and ItemCountPerPage are provided via the extension method call. In addition, LINQ is used to count the elements and storing it as TotalItemCount. Once TotalItemCount is known, we can math to calculate the total TotalPageCount.

A quick note on the paginable - a more accurate statement is IPaginable<T> is an IEnumerable<IPaginableItem<T>> with some page metadata.

paginable-diagram-explained

We are wrapping each element in our sub-collection in a PaginableItem object. Each PaginableItem<T> has the actual item, plus some item metadata. The ItemNumber property identifies the item position in the collection.

paginable-item-explained

Because paginable is a collection, it is easy to just iterate over elements.

var numbers = new int[] { 2, 4, 5, 1, 6, 8, 2, 0, 4, 3, 4, 1, 5, 9, 7, 0, 2, 4, 8, 9 };

var pageNumber = 2;
var itemCountPerPage = 6;

var paginable = numbers.ToPaginable(pageNumber, itemCountPerPage);

foreach(var t in paginable)
{
    Console.WriteLine($"{t.ItemNumber}, {t.Item}");
}

Using the page and item metadata makes it super easy to build the corresponding user interface.

paginable-user-experiences-annotated-more

Resources

Enjoy!