How To Style Yii Pagination with Bootstrap

May 14
2013

Yii Framework + Pagination

I’m a big fan of the Yii Framework. I’ve been hacking on it since it released a few years ago, and it’s become one of my default frameworks for most my projects these days.

One nice feature you get out of the box, is a built-in Pagination class. However, the out of-the-box style doesn’t generally fit the projects I work on, which lately have used Twitter Bootstrap – which has a very nice pagination style.

For sake of completeness, here is example code you might include in a controller action that requires pagination and integrates with Yii’s Active Record methods:


function actionIndex(){
    $criteria=new CDbCriteria();
    $count=Article::model()->count($criteria);
    $pages=new CPagination($count);

    // results per page
    $pages->pageSize=10;
    $pages->applyLimit($criteria);
    $models=Article::model()->findAll($criteria);

    $this->render('index', array(
    'models' => $models,
        'pages' => $pages
    ));
}

And here is corresponding code for the view:

    <?php
    $this->widget('CLinkPager', array(
        'pages' => $pages,
    ))
    ?>

Pretty sweet huh? All of that, out of the box. Too bad it looks like this:

Yii pagination default look

It works… but it probably doesn’t match your project’s look and feel, and it’s just not bootstrap. Boo!

CLinkPager and Twitter Bootstrap

Ever wonder how to mesh Yii’s Pagination + Twitter Bootstrap’s styles? Gee, Me too!

I first googled around to see a quick way mesh the two, and was surprised to find that most examples try to extend CLinkPager widget. This didn’t seem right to me. Yii, is generally a pretty flexible when it comes to stylization and themes; I knew there must be a better way…

I dug into the CLinkPager class myself, and turns out, there is a much simpler way to make Yii’s pagination class styled like bootstrap, and it can be done entirely in the widget options in the view file, without extending anything. See the following:


<link href="//netdna.bootstrapcdn.com/twitter-bootstrap/2.3.1/css/bootstrap-combined.min.css" rel="stylesheet">

<div class="pagination">
    <?php
    $this->widget('CLinkPager', array(
        'pages' => $pages,
        'header' => '',
        'nextPageLabel' => 'Next',
        'prevPageLabel' => 'Prev',
        'selectedPageCssClass' => 'active',
        'hiddenPageCssClass' => 'disabled',
        'htmlOptions' => array(
            'class' => '',
        )
    ))
    ?>
</div>

And wallah! It looks like this:

Yii Pagination using Twitter Bootstrap

Configure Widgets Globally

Now that we know how to style our CLinkPager widget with bootstrap, one realizes that repeating those options for a site that has pagination all over the place in a copy paste fashion is sub optimal. What if I need to change a style slightly for several places?

No worries. Yii offers the ability to globally configure widgets, and further override global configuration as needed for specific widgets.

First, setup your global widget configuration in your config/main.php:


return array(
    'components' => array(
        'widgetFactory' => array(
            'widgets' => array(
                'CLinkPager' => array(
                    'header' => '<div class="pagination pagination-centered">',
                    'footer' => '</div>',
                    'nextPageLabel' => 'Next',
                    'prevPageLabel' => 'Prev',
                    'selectedPageCssClass' => 'active',
                    'hiddenPageCssClass' => 'disabled',
                    'htmlOptions' => array(
                        'class' => '',
                    )
                )
            )
        ),
    ),
);

With that in your config, your pagination inherits the correct styles for bootstrap, and you need only include the following where you need pagination:


    <?php
    $this->widget('CLinkPager', array(
        'pages' => $pages,
    ))
    ?>

In the event that you need to over ride something for a specific pager, you can do so by setting the option for that widget instance, like so:


    <?php
    $this->widget('CLinkPager', array(
        'pages' => $pages,
        'header' => "<div class='pagination pagination-right'>",
    ))
    ?>

Not too shabby.

You can read up a bit more on global widget configuration, as well as take it one more step into “skinning” on the Yii website.

Hosted Bootstrap

Also, little tip, for small projects, I tend to use a hosted bootstrap JS/CSS include – makes throwing up an experimental project, that much faster.

Visit Other Sites!

Find me on other sites...

Archives

All entries, chronologically...

Pages List

General info about this site...