Semantic UI Paginator for Laravel 4

So its been quite a while since I've written a blog post. I've been busy. With lots of things. One of those things has been playing around with Semantic UI, a web design framework in the same spirit as Bootstrap and Foundation.

Semantic UI is pretty cool. I'm not going to get into it too much at the moment (I've got plans for more stuff on Semantic UI, however). You can learn more about it at the website http://semantic-ui.com/ (opens in new window/tab). I will say however, that it is pretty cool.

In the past I've written a number of posts about pagination with Laravel. This post is another paginator post! But, we are going to make a paginator for Semantic UI. It will look like this:

#Step 0: The Semantic UI Markup

Step 0 is a thing right? It is on this website. The first thing we need to do is figure out exactly how you mark up a paginator in Semantic UI. This can be done by referring to the Semantic UI documentation for the menu collection, which can be found here: http://semantic-ui.com/collections/menu.html#pagination (opens in a new window).

 1<div class="ui pagination menu">
 2    <a class="icon item">
 3    <i class="left arrow icon"></i>
 4    </a>
 5    <a class="active item">
 6    1
 7    </a>
 8    <div class="disabled item">
 9        ...
10    </div>
11    <a class="item">
12    10
13    </a>
14    <a class="item">
15    11
16    </a>
17    <a class="item">
18    12
19    </a>
20    <a class="icon item">
21    <i class="right arrow icon"></i>
22    </a>
23</div>

From the docs, we can see that to represent a group of paginated links, we wrap the collection in an element with the ui, pagination and menu classes. Each item in the collection is just an anchor with the item class, so that is pretty easy. To represent a disabled item we add a disabled class. And similarity, to represent the active item we add an active class. Pretty simple.

Now that we are armed with some reference markup, we are now able to begin writing our custom paginator class and view. On to step 1!

#Step 1: The Presenter

First, we are going to write a SemanticPresenter class. This class is what Laravel 4 will use when constructing the links for the pagination elements. So let's start it.

Create a new file named SemanticPresenter.php somewhere where composer and your project can find it. It should look like this at the start:

1<?php
2 
3use Illuminate\Pagination\Presenter;
4 
5class SemanticPresenter extends Presenter {
6 
7}

Our class needs to extend Laravel's Presenter class. It will provide us some methods that we can override to tell Laravel how our pagination elements should be rendered. Basically, what the methods are going to do is take some pieces of data, such as the URL, page number, active status, etc, and return a piece of HTML with some CSS classes.

The first methods we are going to write are the getActivePageWrapper, getDisabledTextWrapper and getPageLinkWrapper methods.

#Step 1.1: The getActivePageWrapper Method

This method gets called by Laravel when it is rendering a link for whatever page the user is currently on. Our method for Semantic UI will look like this:

 1/**
 2 * Get HTML wrapper for active text.
 3 *
 4 * @param  string $text
 5 * @return string
 6 */
 7public function getActivePageWrapper($text)
 8{
 9    return '<div class="active item">' . $text . '</div>';
10}

It simply wraps the active page's name in a div with the CSS classes active and item.

#Step 1.2: The getDisabledTextWrapper

This method is used by Laravel for a few things. For example, when rendering the ellipsis and, of course, any disabled links, it calls this method to do it. So our code needs to return some HTML and CSS that will indicate to the user that the link is disabled. For Semantic UI, our implementation looks like this:

 1/**
 2 * Get HTML wrapper for disabled text.
 3 *
 4 * @param  string $text
 5 * @return string
 6 */
 7public function getDisabledTextWrapper($text)
 8{
 9    return '<div class="disabled item">' . $text . '</div>';
10}

#Step 1.3: The getPageLinkWrapper Method

This method is what Laravel calls when it is generating the links to the different pages a user can go to. It takes the page's URL, name and an option rel attribute and generates a link to it. Our Semantic UI version will look like this:

 1/**
 2 * Get HTML wrapper for a page link.
 3 *
 4 * @param  string $url
 5 * @param  int    $page
 6 * @param  string $rel
 7 * @return string
 8 */
 9public function getPageLinkWrapper($url, $page, $rel = null)
10{
11    $rel = is_null($rel) ? '' : ' rel="' . $rel . '"';
12 
13    return '<a class="item" href="' . $url . '"' . $rel . '>' . $page . '</a>';
14}

#Step 1.4 More Methods

Now that we have the first three methods implemented, we need to finish a few more: the getDots and render method.

The getDots method is responsible for rendering the ellipsis when there is a lot of links. For the Semantic paginator, we are going to use the ellipsis horizontal icon the framework provides:

1/**
2 * Get a pagination "dot" element.
3 *
4 * @return string
5 */
6public function getDots()
7{
8    return $this->getDisabledTextWrapper('<i class="ellipsis horizontal icon"></i>');
9}

Overall, its a pretty simple method. We pass our icon HTML and CSS through the getDisabledTextWrapper method so the end user sees a disabled ellipsis link. Now we have to implement the render method.

Typically, most custom presenters don't override the render method. But we are going to, mainly so that we can use Semantic's arrow icons for the next and previous links:

 1/**
 2 * Render the Pagination contents.
 3 *
 4 * @return string
 5 */
 6public function render()
 7{
 8    if ($this->lastPage < 13)
 9    {
10        $content = $this->getPageRange(1, $this->lastPage);
11    }
12    else
13    {
14        $content = $this->getPageSlider();
15    }
16    return $this->getPrevious('<i class="left arrow icon"></i>').$content.$this->getNext('<i class="right arrow icon"></i>');
17}

#Step 2: The Paginator View

Now we need to make a pagination view. This is the easy part. We simply create a new view in the views folder wherever you want. I named mine paginator.php in a folder that I named semantic. The paginator view looks like this:

1<?php
2    $presenter = new SemanticPresenter($paginator);
3?>
4 
5<?php if ($paginator->getLastPage() > 1): ?>
6    <div class="ui pagination menu">
7        <?php echo $presenter->render(); ?>
8    </div>
9<?php endif; ?>

The paginator view is responsible for taking a $paginator object from Laravel and rendering the paginator's HTML container. It also makes a call to a render() method that internally calls all the methods we implemented earlier on the links the paginator has.

#Step 3: Configuring Laravel

Now we need to configure Laravel to use our Semantic UI paginator view. Don't worry - this is really easy. Open up the config/view.php file and look for the pagination key within the array and change its value to the location of your Semantic paginator view. My pagination configuration entry looks like this:

1...
2'pagination' => 'semantic.paginator',
3...

Remember that when resolving the paths of views in Laravel, the 'dot' notation can be used to separate directories. So semantic.paginator would map to the directory 'semantic' and the file 'paginator.php'.

Now Laravel will use our fancy Semantic UI paginator view and presenter!

#Conclusion

There you have it. A custom paginator for Laravel 4 that generates Semantic UI compatible markup. Nifty. I hope you enjoyed this little tutorial about Semantic UI and Laravel.

∎