Building on Movable Type Part 3: Creating Pagination Controls

In last week’s installment of “Building on MovableType," I described how to reuse the display options widget for the storage of your own user preferences. While Movable Type uses this mechanism for display preferences (i.e. the number of items to display on a page, the sort order, etc.), technically it can be used to store any user preference. This week we learn how to reuse the pagination controls widget.

If you are a developer like me you have probably written and re-written the application logic for displaying pagination controls about a million times. When I first wrote Media Manager, I fell prey to re-inventing of the wheel once more and created yet another implementation of “next page" and “previous page" links for displaying items on your queue.

Then one day, while thumbing through the Movable Type source code, I saw how pagination was implementednoting that it was abstracted out into a template file. A couple minutes later I had ripped out my own somewhat fragile pagination control implementation and replaced it with Movable Type’s. Doing so was easy and now my implementation is much more reliable, flexible and portable.

Hacking Pagination Controls

Pagination controls are sufficiently ubiquitous that our own developers saw the value in creating a reusable mechanism for creating the links developers should all be too familiar with: “next page," “previous page," “last page," “first page" and “you are viewing results X to Y out of Z." This reusable framework is not only accessible within Movable Type, but by plugins as well.

To reuse Movable Type’s pagination controls, begin by copying pager.tmpl, found in the tmpl/cms directory into your plugin’s local tmpl directory. Then use the following line of code to insert your pagination controls into the appropriate location in your application template:

<TMPL_INCLUDE NAME="pager.tmpl">

Copying the pager.tmpl template is necessary, as it requires just a small tweak to eliminate some HTML that is typically unnecessary for most plugins.

Once you have included pager.tmpl into your plugin’s template file, all that's left is populating your template context with a small handful of parameters. These parameters are:

In Summary

Aside from learning how to hack your own pagination controls, there are two key lessons to take away from this installment:

Don’t re-invent the wheel.

This is a cornerstone of good software development. Make your code modular enough so that is easily reused. Nothing says “ugly hack" like code that has been copy-and-pasted around a million times. If you ever you catch yourself hitting “Control-C, Control-V," ask yourself, “Can I write this code so that copy and paste isn't necessary?"

The Movable Type team has tried to adhere to this principal as best it can. Most of the code has been abstracted out into its own template files and subroutines so that it can be reused within Movable Type. One very nice consequence is that Movable Type’s code is easily reused by plugins.

Browse Movable Type’s Source Code

One huge benefit of Movable Type is that the source is available for anyone to browse and inspect. No de-compilers are necessary to learn how Six Apart did something. This makes Movable Type an excellent source for good ideas, tips and tricks, and even example code.

So if you are in need of a feature that is similar to one found in Movable Type, open up a text editor and see how it was done by the Movable Type experts and creators. I know that every time I do I've learned something, and I bet you will too.