Howto use: Mephisto article list pagination plugin

posted: April 3rd, 2007 · by: Sven

in: Programming · tagged as: , , , , , ·  17 comments »

I’ve been asked for instructions on how to use the Mephisto pagination plugin that I’ve published last week. Well, that makes sense :-) So there you go.

The plugin allows you to add very basic pagination functionality to your article section pages (that is, pages like your blog homepage, sub-section pages etc.). Right now, there are only means to add a “older posts” and “newer posts” links to access the previous and next paginated articles list’s pages - you can see this at the bottom of my blog’s homepage.

Update: The following information is most probably outdated. Please refer to the Mephisto Plugin: Paged Article Lists project page.

The plugin adds three new liquid filters for you to use. They all take the current section and pages array as a parameter. Also, you can specify different optional parameters …

The all-in-one filter

There’s a quick all-in-one filter that simply adds one or two links depending on the context (i.e. if there are older posts or not, newer posts or not):


{{ section | prev_next_section_page_links: pages }}

Use this filter to automatically output contextually “correct” links like the following:


<a class="prev" href="/page/3">&laquo; older posts</a>
<a class="next" href="/">newer posts &raquo;</a>

… you can then use the HTML class attributes to let the links float to the left and right side of the page respectively - like you can see on my blog homepage.

Also, you can define a separator as a third parameter:


{{ section | prev_next_section_page_links: pages, '&middot;' }}

… which will be inserted between the both links, if both are present.


<a class="prev" href="/page/3">&laquo; older posts</a> &middot;
<a class="next" href="/">newer posts &raquo;</a>

More power to the people

These automatic links might not always be what you want. Maybe you need another link text. Or you want to enclose the links in some other tags …

You might then want to use the following filters that each just generate one link according to the context:


{{ section | link_to_prev_section_page: pages }}    
{{ section | link_to_next_section_page: pages }}

… which again will get you the same output as above. But this time you can better control the placement of your tags:


<a class="prev" href="/page/3">&laquo; older posts</a>
<a class="next" href="/">newer posts &raquo;</a>

Also, you can now specify the link text as the third parameter:


{{ section | link_to_prev_section_page: pages, "silence is foo!" }}
{{ section | link_to_next_section_page: pages, "where there's foo, there's fire" }}

How to install

You can install this by using Rails’ script/plugin installer. Standing in your application’s root directory do:


script/plugin install http://svn.artweb-design.de/stuff/mephisto/mephisto_paged_article_list

That should suffice :-)

Don’t forget to restart your webserver after messing with your plugins!

Leave a comment

17 Comments

  1. W. Andrew Loe III said May 19th, 2007 at 01:14 AM  

    Excellent plugin.

    Is there a way to force this to allow pagination for a specific section? I’m using your template and it properly generates mysite.com/section/page/2 links but that doesn’t paginate the section, it pulls up page 2 of everything.

  2. W. Andrew Loe III said May 19th, 2007 at 02:26 AM  

    I should clarify that comment. I think I may have an issue with how my sections are setup. I have every article in my “Home” section which has a path of nothing (so it shows up at mysite.com/). Is this correct?

    When I go to mysite.com/section/page/2 I get exactly the same as mysite.com/page/2 its not filtering to just the section. Though this works for archives without any problem.

    Ideas?

  3. Sven said May 19th, 2007 at 02:46 AM  

    Hey!

    As far as I understand what you mean this behaviour can be seen here: http://journal.andrewloe.com/computers-and-technology/page/2 Right? Even worse: if you look at the “older posts” link at the bottom of that page you see that it points to http://journal.andrewloe.com/page/3 (and not page 3 of that section)!

    So that’s severely foobared :-/ I vaguely remember that I’ve seen this behaviour myself. I just can’t remember what I’ve done to solve it. (It’s not here on my own blog. See: http://localhost:3000/programming/page/2)

    Hum. Are you sure that you have the latest version of the plugin? I guess I’ve probably forgot to check in my latest fixes or so.

  4. Sven said May 19th, 2007 at 03:05 AM  

    Please update (or reinstall) the plugin. I’ve just checked in a change that I’ve obviously forgot about.

    http://stuff.artweb-design.de/trac/changeset/38

    My shame. Big sorry for the inconvenience!

    Please email me if that doesn’t fix your problem (don’t forget to restart your server if needed).

  5. W. Andrew Loe III said May 21st, 2007 at 04:41 AM  

    Awesome! It works fantastically now, thank you for your work.

  6. Will Duncan said June 21st, 2007 at 12:28 PM  

    I spent like 3 hours searching the documentation and then the google group and came up empty handed (no thanks to google thinking I was a bot while searching the group).

    It blew my mind when I noticed that there was no pagination built into Mephisto. I was sure I was missing something till I went to about 20 fully populated Mephisto powered blogs/sites only to realize that if you went to a category that didn’t list everything you were screwed if they didn’t have an Archive section.

    But even if they did have an archive section it meant clicking individual articles and backing out. Not much for for someone browsing through a blog.

    This worked right out of the box. Thanks so much.

  7. Sven said June 26th, 2007 at 02:09 PM  

    Hey Will, I believe that the decision to omit pagination from Mephisto by default has several negative consequences: not only regarding SEO and spiders but also humans who simply searching for a specific article. (This once drove me crazy on Jamis Buck’s blog.)

  8. zerohalo said August 4th, 2007 at 10:11 PM  

    Finally, sanity! Thank you, Sven.

  9. zerohalo said August 4th, 2007 at 11:02 PM  

    Sven, does this work on Mephisto trunk? I’ve tried it (rev 2920) and it throws an exception on line 20 with NameError (uninitialized constant ActionController::Pagination).

    It does work with an older installation of Mephisto (rev 2561) that I have.

  10. zerohalo said August 4th, 2007 at 11:42 PM  

    PS. Sorry, I should have dug around a bit more before posting that last note.

    The problem is not with a change in the Mephisto trunk, but rather in Rails edge, which the latest Mephisto pulls in. ActionController::Pagination is no more (I had heard they were going to pull it from Rails and have it as a plugin). I couldn’t find the new pagination plugin, but maybe it’s yet to come.

  11. Sven said August 11th, 2007 at 06:31 PM  

    zerohalo, thanks for tracking that down.

    Actually I haven’t even noticed that change as I’ve frozen my Mephisto/Rails installation and haven’t touched it for the last two months or so.

    Please let me know if you find a solution for this. I’ll want to update the plugin accordingly of course.

  12. Mika Tuupola said August 22nd, 2007 at 10:57 AM  

    Would it be possible to expand this plugin to support paged tag pages. If I understood correctly now it pages only sections.

    Thanks for great plugin!

  13. Sven said August 23rd, 2007 at 11:12 PM  

    Mika,

    this should be possible, yes. I vaguely recall that there’s been some Mephisto bug with tags and tag pages. I promise I’ll have a look at it within the next days. Thanks for the hint!

  14. Sven said September 7th, 2007 at 08:17 PM  

    Hey Mika,

    I just wanted to drop you the note that the current version in SVN will page your tag pages. You’ll need to switch to Mephisto Edge though … which hopefully won’t be an issue for you. Otherwise just contact me by mail. I guess that functionality can be backported easily.

  15. Mark Guzman said September 11th, 2007 at 06:39 AM  

    Hi Sven, I love the plugin. I just got it setup on my blog. I noticed that the main pagination call doesn’t limit the dataset to published articles. Just a heads up, I’ve fixed it on my end. Thanks for the plugin.

  16. Sven said September 11th, 2007 at 12:33 PM  

    Hey Mark,

    thanks for the heads up! That’s fixed. I would have never noticed that myself as the unpublished articles were sorted to the very end of the paged lists.

    On a sidenote: are you fine with these pagination links (“older/newer posts”) as they are? Otherwise I’d suggest to float these links to the left and right side … something like this:

    .next {
    float: left;
}
.prev {
    float: right;
}

  17. Matthew said September 20th, 2007 at 05:07 PM  

    Great plugin thanks a lot.

Leave a comment

Name required
E-Mail and Website optional

If you can read this, you don't use a typical webbrowser that plays nice with CSS.
Please do not fill in anything here!

Hint: Markdown will be applied to your comment. If you post any code, be sure to escape underscores (like so: \_) if you do not want them to be converted to an <em>phasis.

artweb design
Sven Fuchs
Grünberger Str. 65
10245 Berlin, Germany


http://www.artweb-design.de

Fon +49 (30) 47 98 69 96
Fax +49 (30) 47 98 69 97