alphapager Follow @yiiframework

This extension is an alphanumeric pager which could be used standalone or within a Grid-/ListView.

It's consisting of the main pagination component and:
- LinkPager widget
- ListPager widget
- Extended ListView and GridView for usage with alphapager (including AJAX support)
- Extended ActiveDataProvider and ArrayDataProvider for usage with alphapager

It's mainly a modification of yiis CPagination and CLinkPager/CListPager classes to achieve a pager which adds a CONDITION to a CDbCriteria instead of LIMIT/OFFSET like the standard pagination does.

Therefore it's possible to page through data (like an addresslist) by selecting a letter (A-Z) for a specified attribute to start with (e.g. the last name).

In addition it's possible to control a standard pagination as kind of subpagination per letter.

If there are questions, bugs or suggestions you're welcome to post a comment in the discussion topic here.

Resources ¶

• Screenshot v.1.1
• Another Screenshot
• Join discussion
• Report a bug

Documentation ¶

Requirements ¶

• Yii 1.1.x or above

Installation ¶

• Extract the release folder under protected/extensions

Usage ¶

It's easy getting started! For usage with GridView and ListView you can directly jump over to point 2.

1. Standalone AlphaPager ¶

First of all you may include something like the following inside the corresponding action of your controller:

1.1 AlphaPager without a subpagination ¶

Yii::import('application.extensions.alphapager.ApPagination');
 
$criteria=new CDbCriteria;
// The constructor takes the name of the models attribute to which the condition should be applied when using applyCondition().
// Here we'll select the output by 'title'-attribute of our model
$alphaPages = new ApPagination('title');
// Add search condition to the CDbCriteria (similar to using CPagination)
$alphaPages->applyCondition($criteria);
 
/*...*/
 
$this->render('myView',array(
        /*...*/
        'alphaPages'=>$alphaPages, // Just like passing e.g. $pages to your view
    ));

This will add a search condition like "AND title LIKE 'a%'" to the criteria if the button 'A' was clicked.

1.2 AlphaPager with a subpagination ¶

This is a little bit tricky because we always have to applyCondition() of AlphaPager BEFORE we're using the criteria in CPagination, otherwise the count result of Pagination would be wrong.

Yii::import('application.extensions.alphapager.ApPagination');
 
$criteria=new CDbCriteria;
// The constructor takes the name of the models attribute to which the condition should be applied when using applyCondition().
// Here we'll select the output by 'title'-attribute of our model
$alphaPages = new ApPagination('title');
 
$pages = $alphaPages->pagination; // Accessing the internal pagination will automatically create an instance of CPagination with itemCount = 0
 
// Add search condition to the CDbCriteria (similar to using CPagination)
$alphaPages->applyCondition($criteria);
 
// After applyCondition() is called we can set paginations itemCount.
$pages->setItemCount(myModel::model()->count($criteria));
$pages->applyLimit($criteria);

1.3 AlphaPager with a custom subpagination ¶

You may want to define the pagination object for subpagination by yourself (e.g. using a derived class of CPagination). Therefore you can also call AlphaPaginations constructor like this:

$alphaPages = new ApPagination('title', new MyPagination());
$pages = $alphaPages->pagination; // pagination will return the instance of MyPagination

Now MyPagination is used for the subpagination.

1.4 Including the widget ¶

After you have added something like the above code examples to your controller you can use the widget inside your view file as usual:

// A LinkPager
$this->widget('application.extensions.alphapager.ApAlphaLinkPager',array('pages'=>$alphaPages));
// or a ListPager
$this->widget('application.extensions.alphapager.ApAlphaListPager',array('pages'=>$alphaPages));

2. AlphaPager within a Grid- or ListView ¶

The 'standalone usage' as in 1. was mainly for the usage with yii 1.1, but now most people would use Grid- and ListViews in their yii applications. So, let's have a look at this.

2.1 AlphaPager with ListView/GridView ¶

To use AlphaPager with a Grid-/ListView you have to use extended versions of DataProviders and Grid-/ListViews. These are included in the package.

Furthermore AlphaPager also uses AJAX to update the List-/GridView if you've enabled AJAX for your List-/GridView (e.g. already using it for sort/search).

First you need to change the DataProvider inside your models search() function. Change CActiveDataProvider to ApActiveDataProvider or respectively CArrayDataProvider to ApArrayDataProvider. Afterwards specify the models attribute that AlphaPager should be used on.

Yii::import('application.extensions.alphapager.ApActiveDataProvider');
/* ... */
return new ApActiveDataProvider(get_class($this), array(
            /* ... */
            'alphapagination'=>array(
                'attribute'=>'surname',
            ),
        ));

or for ArrayDataProvider

Yii::import('application.extensions.alphapager.ApArrayDataProvider');
/* ... */
 $rawData=MyModel::model()->findAll();
 return $dataProvider=new ApArrayDataProvider($rawData, array(
            /* ... */
            'alphapagination'=>array(
                'attribute'=>'surname',
            ),
  ));

After this is done you just need to adjust the Grid-/ListView widget inside your viewfile and add the alphapager to it's template:

$this->widget('application.extensions.alphapager.ApLinkView', array(
    /* ... */
    'template'=>"{alphapager}\n{pager}\n{items}",
));

3. Some configuration examples ¶

Let's take a short inside look at AlphaPager.

3.1 Defining different character sets ¶

Since version 1.1 you're able to define different character sets by yourself. The following example shows how to cut the button range to be C to X and then only activate those buttons which have entries starting with this letter in your db (using mysql):

Yii::import('application.extensions.alphapager.ApPagination');
 
$criteria=new CDbCriteria;
$alphaPages = new ApAlphaPagination('title');
// Define the available character set. Here C-X instead of A-Z
$alphaPages->charSet = range('C','X');
 
$activeCharCriteria=new CDbCriteria;
// Select only the first letter of the attribute used for AlphaPager
$activeCharCriteria->select='DISTINCT(LEFT(`title`,1)) AS `title`'; 
$chars = Post::model()->findAll($activeCharCriteria);
 
// Add those characters to an array and assign them to activeCharSet
foreach($chars as $char)
    $activeChars[]=$char->title;
$alphaPages->activeCharSet=$activeChars;
 
$alphaPages->applyCondition($criteria);

As you can see the charSet property defines which characters are generally available for pagination, while activeCharSet property defines which characters are active in pagination (all non-active characters will have the css class 'HIDDEN' so they can be grayed-out or similar).

3.2 Activating '0-9'-button (for entries starting with numbers) ¶

You can add a button for entries starting with a numeric value to the pager. First make sure you have set showNumPage of AlphaLinkPager widget to true to make the button show up. By default it's a button with the label '0-9'. Using this button will match entries like '99_balloons', '21 Jump Street' or whatever. You may also what to disable/enable this button depending on whether there are entries starting with digits or not. This couldn't be done using the activeCharSet. Instead you could use the following code (for mysql):

// Keep in mind that activeNumbers is bool. Don't overlook '> 0' at the end of the line.
$alphaPages->activeNumbers = Post::model()->count("SUBSTRING(`title` FROM 1 FOR 1) BETWEEN '0' AND '9'") > 0;

3.3 Force case-insensitivity ¶

It could be a problem if you have e.g. a case-sensitive collation for your database table but you want AlphaPager to do a case-insensitive search (like finding attributes starting with 't' and 'T'). Therefore you can set forceCaseInsensitive property of ApPagination to TRUE. If set to TRUE the conditions in the DB Queries and the internal comparision between charsets are all generated lowercase.

Class Reference ¶

ApPagination Properties (different from CPagination)

• pageResetVar - string
  name of the GET variable which indicates that a controlled pagination should be reseted to the default page. Defaults to 'p_rst'.
• attribute - string
  the model attribute that the condition should be applied to.
• pagination - object
  the controlled Pagination object
• charSet - array
  character set for pagination. Defaults to characters A - Z. (Since v1.1)
• activeCharSet - array
  active character set. The buttons of all characters in charSet that are not in activeCharSet will have the css class 'HIDDEN'. Defaults to charSet if not set. (Since v1.1)
• dbCharSet - array
  characters used for database query condition. May contain equivalents of the characters in charSet which are used in condition Defaults to charSet if not set. (Since v1.1)
• activeNumbers - bool
  whether there are entries starting with digits or not. Hides the 'SHOW NUMERIC'-button of linkpager if false and showNumPage is true. Defaults to true. (Since v1.1)
• forceCaseInsensitive - bool
  set to true this will make cross charset comparison case-insensitive and also uses the LOWER-function to make the sql condition case-insensitive. Defaults to false. (Since v1.2)

ApLinkPager Properties (different from CLinkPager)

• allPageLabel - string
  the text label for the 'SHOW ALL'-button. Defaults to 'All'.
• numPageLabel - string
  the text label for the 'SHOW NUMERIC'-button. Defaults to '0-9'. (Since v1.1)
• showNumPage - bool
  show the 'SHOW NUMERIC'-button. Defaults to false. (Since v1.1)
• showAllPage - bool
  show the 'SHOW All'-button. Defaults to true. (Since v1.2)

ApListPager Properties (different from CListPager) Since v. 1.2

• allPageLabel - string
  the text label for the 'SHOW ALL'-button. Defaults to 'All'.
• numPageLabel - string
  the text label for the 'SHOW NUMERIC'-button. Defaults to '0-9'.
• showNumPage - bool
  show the 'SHOW NUMERIC'-button. Defaults to false.
• showAllPage - bool
  show the 'SHOW All'-button. Defaults to true.

ApActiveDataProvider Properties (different from CActiveDataProvider) Since v. 1.3

• alphapagination - ApPagination
  the alphapagination object

ApArrayDataProvider Properties (different from CArrayDataProvider) Since v. 1.3

• alphapagination - ApPagination
  the alphapagination object

ApGridView Properties (different from CGridView) Since v. 1.3

• enableAlphaPagination - bool
  whether to enable alphapagination.
• alphaPager - array
  the configuration for the alphapager. Defaults to array('class'=>'ApLinkPager').
• alphaPagerCssClass - string
  the CSS class name for the alphapager container. Defaults to 'alphapager'.

ApListView Properties (different from CListView) Since v. 1.3

• enableAlphaPagination - bool
  whether to enable alphapagination.
• alphaPager - array
  the configuration for the alphapager. Defaults to array('class'=>'ApLinkPager').
• alphaPagerCssClass - string
  the CSS class name for the alphapager container. Defaults to 'alphapager'.

Change Log ¶

Version 1.3.2 - March 2, 2011 ¶

• Bugfix: Predefined parameters for the subpagination of AlphaPager assigned as an array are ignored. (For more details see: discussion topic)

Version 1.3.1 - November 27, 2010 ¶

• Fixed 2 issues in ApArrayDataProvider (for more details see: discussion topic)

Version 1.3 - November 14, 2010 ¶

• ATTENTION: to avoid potential naming conflicts all files/classes now have the prefix 'Ap'!
  This needs code to be changed when updating to v. 1.3! (See included README_FIRST.txt)
• Added extended DataProviders: ApActiveDataProvider & ApArrayDataProvider
• Added extended widgets: ApListView & ApGridView

Version 1.2 - May 15, 2010 ¶

• Added AlphaListPager widget
• Added forced case-insensitivity

Version 1.1 - May 11, 2010 [Not backward compatible] ¶

• Customizable character sets added
• Active/Non-active state could be set for buttons (thanks to aztech)
• Different character set for database query
• 'SHOW NUMERIC'-button added to show all results starting with a digit

Version 1.0 - April 29, 2010 ¶

• Initial release.