Yii 1.1: alphapager

Simple alphanumeric pager for paging through data by e.g. A-Z
34 followers

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.

alphapagerv11_screen.PNG

Resources

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

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.

Total 15 comments

#16074 report it
Ashish Rastogi at 2014/01/16 10:10pm
error in alphapager

include(ApAlphaPagination.php): failed to open stream: No such file or directory

please tell me how to fix this error..

#16073 report it
Ashish Rastogi at 2014/01/16 01:30pm
Geting a error

i got this type of error

include(ApAlphaPagination.php): failed to open stream: No such file or directory

could you tell why?

#10159 report it
karmraj at 2012/10/08 06:11am
Make this changes to view file.

In above instrunction, following line of code are given to use in view file. but in latest version there is no such file with name ApLinkView in extension. so please take care for display gridview with alphapager in view file.

Change code from this:

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

To :

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

#6635 report it
jmariani at 2012/01/23 02:45pm
How to hide/change "Go to letter" label?

My mistake. Thank you very much!

#6634 report it
yoshi at 2012/01/23 01:47pm
How to hide/change "Go to letter" label?

@jmariani

This question was already asked in the discussion thread. Take a look here.

If you still have problems changing the header text, please pm me.

Regards

#6633 report it
jmariani at 2012/01/23 01:31pm
How to hide/change "Go to letter" label?

Thank you in advance.

#6631 report it
jmariani at 2012/01/23 11:58am
Excellent!

Thank you very much.

#5612 report it
yeti999 at 2011/10/25 04:30am
@CeBe :

I need to display the record number inside the view file of 'itemView'. I mean the ranking of the record. Just to query like this: SET @rank=0; SELECT @rank:=@rank+1 AS rank, fruit, amount FROM sales ORDER BY amount DESC ;

And display that rank number in the view

#5611 report it
CeBe at 2011/10/25 04:24am
didn't get you...

@nisal: could you describe a bit more precise where the problem is? Better way might be asking in the forum...

#5609 report it
yeti999 at 2011/10/25 01:27am
Getting item index to itemView

How to get the record index/item index to itemView?

#4535 report it
Peter JK at 2011/07/18 07:43am
Wow Love it...

thank you, Yoshi... wonderfull extension...

#45 report it
aztech at 2010/10/05 06:55am
Great

I'm using this extension very hard and I've to say is really good. If you would like to see it in use visit this site.

#355 report it
samdark at 2010/07/01 07:01am
Good one

Useful extension with good enough documentation not to check its source code when you need something.

The only drawback is that its classes are not prefixed with E like EAlphaLinkPager that can possibly lead to naming conflicts.

#373 report it
Alex Muir at 2010/06/22 04:26am
Sweet extension

Great documentation makes this extension a breeze to use. Lots of thought has gone into it - well done, and thanks.

#532 report it
aztech at 2010/05/03 11:54am
Similar extension

Hi, I created similar extension for my own purpose and I planned to release it as a part of my already published AiiExtension. My code look quite similar beside one thing. I used different approach of displaying alpha characters. I'm using two variables: $php$alphaSet and $alpha. First one is a set of all characters (e.g. same as yours a-z range), latter is a set of characters which should be displayed. Why to differentiate this? This allows you to do two additional things to your extension 1) Display only those characters which are needed 2) Disable some characters grayed if there are no entries in db matching character selection. This is handy e.g. in case of filtering user names and there are e.g. no users starting with letter Z. Could you consider to update your extension with this feature? I can send you my extension code if you need. Cheers, aztech

Leave a comment

Please to leave your comment.

Create extension