doctrine2/manual/docs/en/utilities/pagination/controlling-range-styles.txt

There are some cases where simple paginations are not enough. One example situation is when you want to write page links listings.
To enable a more powerful control over pager, there is a small subset of pager package that allows you to create ranges.

Currently, Doctrine implements two types (or styles) of ranges: Sliding ({{Doctrine_Pager_Range_Sliding}}) and Jumping ({{Doctrine_Pager_Range_Jumping}}).

++++ Sliding

Sliding page range style, the page range moves smoothly with the current page. The current page is always in the middle, except in the first and last pages of the range.
Check out how does it work with a chunk length of 5 items:

<code>
Listing 1 2 3 4 5 6 7 8 9 10 11 12 13 14
Page 1: o-------|
Page 2: |-o-----|
Page 3: |---o---|
Page 4:   |---o---|
Page 5:     |---o---|
Page 6:       |---o---|
Page 7:         |---o---|
Page 8:           |---o---|
</code>

++++ Jumping

In Jumping page range style, the range of page links is always one of a fixed set of "frames": 1-5, 6-10, 11-15, and so on.

<code>
Listing 1 2 3 4 5 6 7 8 9 10 11 12 13 14
Page 1: o-------|
Page 2: |-o-----|
Page 3: |---o---|
Page 4: |-----o-|
Page 5: |-------o
Page 6:           o---------|
Page 7:           |-o-------|
Page 8:           |---o-----|
</code>


Now that we know how the different of styles of pager range works, it's time to learn how to use them:

<code type="php">
$pager_range = new Doctrine_Pager_Range_Sliding(
	array(
		'chunk' => 5 // Chunk length
	),
	$pager // Doctrine_Pager object we learned how to create in previous topic
);
</code>

What is the advantage to use this object, instead of the {{Doctrine_Pager}}? Just one; it allows you to retrieve ranges around the current page.
Look at the example:

<code type="php">
// Retrieves the range around the current page
// In our example, we are using sliding style and we are at page 1
$pages = $pager_range->rangeAroundPage();

// Outputs: [1][2][3][4][5]
echo '['. implode('][', $pages) .']';
</code>

If you build your {{Doctrine_Pager}} inside the range object, the API gives you enough power to retrieve information related to {{Doctrine_Pager_Range}} subclass instance:

<code type="php">
// Return the Pager associated to this Pager_Range
$pager_range->getPager();

// Defines a new Doctrine_Pager (automatically call _initialize protected method)
$pager_range->setPager($pager);

// Return the options assigned to the current Pager_Range
$pager_range->getOptions();

// Returns the custom Doctrine_Pager_Range implementation offset option
$pager_range->getOption($option);

// Check if a given page is in the range
$pager_range->isInRange($page);

// Return the range around the current page (obtained from Doctrine_Pager
// associated to the $pager_range instance)
$pager_range->rangeAroundPage();
</code>