Kalin’s Post List Help

-- Download Kalin's Post List Help as PDF --

Note: I have mostly discontinued support for this plugin. If you are having problems I recommend trying Advanced Post List, which is a different, more current version of this plugin.

Kalin’s Post List allows you to create dynamic, highly customizable lists of posts and pages that can be inserted into pages and posts through a shortcode, or added to your theme through a widget or PHP snippet.

There is a wonderful tutorial to get you started at …in some weird postmodern way… written by one of my users if you find everything here a little overwhelming.


To use one of the pre-defined Post List configurations, simply look at the table halfway down the page and copy one of the shortcodes into any page or post. When you view the post, the shortcode should be replaced with a list of posts that corresponds to the preset. You can then come back to this settings page and customize the preset, or save it as a new configuration under a different name.

    • Top Row Options
      1. Post Type: Choose to show pages, posts, custom posts, attachments or everything. Choosing ‘none’ will hide many of the list controls and allow you to use the plugin to insert HTML. All shortcodes in this mode will refer to the page you are currently viewing instead of list items. This will allow you to do things like put the same shortcode on multiple posts so you can change the content across all the posts in one edit.
      2. Show Count: The number of items that will be shown. Be sure to only insert integer numbers here. Use -1 (negative one) for no limit.
      3. Order by: Choose from 8 different ways to order the posts, then select ascending or descending. These will affect which posts are actually shown if the number of results is higher than the Show Count.
      4. Parent: This dropdown will appear if you select ‘page’, ‘all’ or a custom post type, allowing you to choose a page to show only the children of that page.


    • Categories and Tags
      1. Include current post categories/tags: Checking this for either categories or tags will extract the terms from the current page/post where you have applied the shortcode, and use them to determine which posts to pull into the list. This is how you can show “related posts”.
      2. Require all selected categories/tags: A normal WordPress post query returns posts that have any one of the selected tags or categories. Checking this box will tell Post List to ensure that every post contains every selected tag or category.
      3. Category/Tags: Your own categories and tags should show up in these two lists, allowing you to select any combination. If you selected “include current”, these will be added to the list.


    • Content
      1. Before list HTML: Insert any HTML to be displayed immediately before the actual post list. Shortcodes in this section refer to the main page you are currently viewing.
      2. List item content: This is the important one. This HTML represents the individual items within the list and will be repeated multiple times based on the “show count” and the number of results returned. You must use the shortcodes listed further down on the page to insert information about each post. Most common, of course would be [post_title] and [post_permalink] shortcodes, but you’ll see that there are many others, allowing you to customize the information displayed in the list. For examples on how these are used, click “load” on any preset in the preset table below.
      3. After list HTML: HTML content to insert after the list. Shortcodes refer to page you are sitting on just like Before list HTML.
      4. Exclude current post from results: Check this to exclude the page/post you are currently viewing from the list, since there’s usually no reason to link a page to itself.


    • Presets:
      1. Save to Preset: You can save a preset to any name you like, though avoid special characters. Once you save, the preset should immediately appear in the list below. You can save over the default presets, though you may be better off saving them as unique names to avoid confusion later.
      2. Post List Preview: If you select ‘show preview’, then save the preset, you will see the actual post list generated in the preview area so you can quickly see what your list will look like. Bear in mind that the CSS in your admin is different from your theme, so colors and other formatting may be a little different when placed within your theme or post. Also remember that the Post List admin page is not a post, so if you have selected ‘include current post categories/tags’ or ‘exclude current post’, the correct posts will not be shown in this preview.
      3. Preset List Table: The preset list table should show all of the presets you’ve entered as well as any remaining defaults that shipped with the plugin. You should see load and delete buttons for each. Clicking load should populate all the above fields to allow you to make adjustments and re-save. Delete will delete that preset. The right-most cell contains the shortcode itself for easy copy/pasting into your post.
      4. Restore Preset Defaults: To restore your original presets, click “Restore Preset Defaults” under the preset list. This will restore your original presets, overwriting any changes you have made to them. This will not, however, delete any new presets you’ve created using unique names. If I add new default presets to the plugin, such as the CSSTable preset added with version 3.0, you will need to click this button to see them.
      5. PHP code: For folks with a working knowledge of PHP or themes. When you click load on any preset, it will generate a simple PHP snippet that you can insert anywhere into your theme. Don’t forget the opening and closing PHP tags.


    • Shortcodes:This is a reference list of the shortcodes that can be used within the “List item content” input field. They will refer to each respective post in the generated list. If used within the Before or after list HTML fields, these shortcodes will refer to the page you are currently viewing.
      • Note that some shortcodes have optional parameters, offering greater customization.
      • The [post_pdf] shortcode will give you the url to create a PDF file of the appropriate page. This requires Kalin’s PDF Creation Station WordPress plugin to be installed and activated to function properly. The url generated runs through the PDF creation script. If you want the URL directly to the PDF simply do something like this {hard coded path to pdf folder}[post_name].pdf or {hard-coded-base-path}[ID].pdf, depending on how you have your PDF filenames set up.


  • Plugin deactivation:At the bottom of the page, you can select whether or not to save all your values when deactivating this plugin. If you have lots of custom presets that you don’t want to lose, you may want to turn this off. Otherwise the default is to clean up everything upon plugin deactivation.

90 thoughts on “Kalin’s Post List Help”

  1. I use Kalin’s post list with Two bite Language.
    I see some ? or � on the page, and I can’t get rid of them.
    Could you please help me?

    1. Sorry, I have no idea from the limited info you gave and I would have no idea how my plugin could be messing with your fonts like that.

  2. Hi Kalin,

    I have been using extensively this plugin, literally a whole site was built around it. I made a site migration to AWS hosting using a bitnami stack and since then the plugin is broken.

    The funny thing is that the site works ok, as soon as I try to access the plugin admin panel, I get a blank screen and the site content collapses.

    Tried several reinstalls, checked database entries, nothing seems to work.

    Found some older installation (still shows 3.1) and copied the files on top, now the site does not collapse, still shows the post lists, however I can not access the admin options. Admin page loads slowly and when it finishes, it diplays only the first row of the dropdown selectors.


    1. Oh, crap – I’m sorry I missed this for so long. Did you happen to figure out the problem? I don’t have any idea what it would be off the top of my head, though I have this feeling that the PHP is throwing some kind of errors that is preventing things from showing up.

  3. I made the mistake of deactivating the plugin and lost my lists. I have a backup of my site, so I’d like to restore it, but I don’t know where the data is stored.

    Which file has all of my plugins stored? I’d like to restore that file.

    1. Sorry, I don’t know off the top of my head. I remember I put them in the standard place we’re supposed to put them, so you could look up on the wordpress documentation to find out where that is or do a search for post*list, or you could look through my sourcecode and see where I’m putting it.

  4. This is a great plug-in.

    Just what I was looking for.

    I never thought I would find such a flexible plug-in.

    Thanks to your plug-ins flexibility I managed to get exactly what I had planned in my mind.

    I cant thank you more.

    Thanks a lot!


  5. Hi Kalin and others. I’ve inserted the [post_thumb] command and it works. It shows the location of the image http://blah.com/image.jpg. But when I insert it doesn’t show anything:( Any idea why it’s not showing the post image. Thanks so much!

  6. Hello, wanted to say great plugin! I also have a question.

    I’m working on a website for someone, and this is currently their article page, which uses your plugin.

    It can be seen here: http://mindfuseproductions.com/insightconsultant/articles/

    I currently have “show posts” set to 5, but he has about 40 articles he wants posted, and will post more in the future. Would it be possible to show 5.. and then have pages, each with 5? Or maybe a “show more” code.. that when clicked will show more links? My thought is having 40 articles on one page would be a lot.. and make the blog very very long. Breaking them up into pages or something I think would be good, but I have no clue how to do so.

    If you have any suggestion / idea I would be very grateful. Thanks!

    1. Hi, sorry it took me so dang long to get back to you. My life has been crazy lately 🙂
      Pagination isn’t possible out of the box. What you could do is use the PHP function injection feature to apply a different CSS class to the first five items, so that the rest of the items are only shown when you hit a toggle link. It would take a bit of creative Javascript, CSS and PHP work, but probably wouldn’t take much actual code.

  7. Hi Kalin, sweet plugin,
    just noticed that after i make a new post list, changing the post count doesn’t seem to affect it. is this a big and if so is there a way fro me to get around it?

    1. Hmmm… I can’t seem to reproduce the error. Are you sure you have enough posts to fill out the list? Did you remember to save the preset? If it’s still a problem, can you give specific steps for me to reproduce the error?

  8. Hi Kalin,

    Just sent you an email, but thought that I would ask here too just in case.

    I want to be able to display the first thumb only when calling it using the short codes.. Is there an easy way to do this at all?

    1. Not directly through the interface there’s no way to do it but if you know PHP it should be pretty simple to use the [php_function name=”function_name” param=””] shortcode. You’d just have to write a function that returns the image wrapped in an image tag when it’s the first item in the list and an empty string if it’s not. You can refer to this post for instructions on using the php_function shortcode.

      1. Thanks very much for this Kalin 🙂 I’ll have a go at it today / tomorrow 🙂 Thanks again for all your help and for a great plugin 🙂

  9. Great plugin–I love the customizability, and your responsiveness! I successfully added custom post metadata shortcodes to generate citation information and so on, but now I am trying to remove the share buttons at the bottom of my posts when they are PDF-ified. I cannot seem to find any information about this; can you help? Here’s my website (some posts/pages haven’t been updated fully): http://aphrabehn.org/ABO. Thanks so much!

    1. Well the “share this:” this is probably being put in there by a plugin. You can either uncheck “run other plugin shortcodes” or possibly “content filters”, or, if you have other plugins running that you do want to affect the PDF, then you can take whatever that share plugin is doing and copy it into your theme so that the share buttons are not considered part of the content.

  10. Hi,

    I am wondering how to get the plugin to work with custom taxonomies. I am thinking of adding another category taxonomy and use the plugin to filter items using a combination of the standard category and the custom category.


    1. Sorry, I never got around to making this plugin work with custom taxonomies before I stopped development. It probably wouldn’t be too hard to hack the source to get it to work, but I don’t have the time or energy to do that myself.

      1. I rearranged the custom taxonomy as standard categories and tags. I started using the lists, they seem OK with categories, however I get a strange behavior when trying to combine a single category selection and some tags as a filter. It seems that the tags are ignored. Could it be that the tags are not in English? I use Greek UTF8 tags.

      2. Hmm… I’m not sure. Have you tried doing the same thing will all-english tags? Can you send me a list of the different tags and categories you’re trying to use and I can hopefully look into it later this week.

  11. Hi,
    I love this plugin, but the problem I am getting is that each post has an image in the custom field how can I get that printed in the pdf verison as well

    1. For either PDF Creation Station or Post List you would use the [post_meta name=”custom_field_name”] shortcode and wrap it in an image tag, assuming the custom field is just a url to the image.

      1. Oh yes I figured this out yesterday only but the problem is I have a number of custom fields, so I need to put a check if the field is available then show the custom field along with its heading like there is a custom field “Group discussions” which is present in few of the posts but I need to put a heading before the custom field value comes… so there has to be a way of adding an if this value exists then put the custom field value.

      2. Okay, so now you’re getting a little bit more complex, but this can be done in Post List if you’re willing to write a little PHP code. You should be able to use the [php_function name=”function_name” param=””] shortcode and refer to a PHP function you write yourself which can decide whether or not to output the custom field. You can refer to this post for a little more information about the php_function shortcode. Unfortunately I never did put this feature into PDF Creation Station.

      3. So we are talking about the Creation Station? I think we’re on the wrong page 🙂 this post talks about how to use different fonts with TCPDF for foreign characters but you should be able to do the same thing to swap out fonts. Or you could look on the TCPDF documentation.
        You could also do it with old-fashioned HTML. I think TCPDF is better about rendering old HTML as it is about CSS. You could maybe wrap the whole pages in a font tag.

      4. Ohh nothing is working I tried the TCPDF method also :/.. I also want the link of download pdf option at the end of the post, because I have customized my code and I have custom fields already after the post so this download option comes in the middle of the post. So can you please tell me a way out.

        Between I just love your plugin and the support you are giving 🙂

      5. Yeah, TCPDF is kinda wonky sometimes and difficult to deal with, but I have been able to switch out fonts with it. I’m not sure what other advice I can give you with that though.
        As for getting the link to show up in different places you’ll probably need to make adjustments to your theme. This post should give you an idea how to do that.
        Tonight I’m gonna see if I can move this conversation to my Creation Station page since this page is about a totally different plugin so if you can’t find your comments, that’s where they’ve gone.

    2. Heyy thanks a lottt, i tried pposting first on that page but I did not get good response… i did figure out the font problem i hv defined a div with font family and its working perfectly but now the problem I am getting too mucn unnecessary space in the document :S What could be done for that..

      Urgent answer would be appreciated and thanksss a million for all your hellpp.. just love your services and plugin :)))

      1. Yeah, I sometimes go out of town for the weekend and don’t have internet access so I often wait until monday or tuesday to reply to everything. I replied to the whitespace and error things on the Creation Station page where you posted earlier.

  12. Hi. I love this plugin! 🙂

    I want to generate a list of my posts ordered by category, so all the posts in the “A” category are listed under the title “A”, then the posts in “B” are under “B”, etc. Do I need to create a preset for every single category and then put them all in a page, or is there an easier way to do all this with a single preset? I would hope you’re willing to tell me how to do this exactly because I’m not a coding genius at all.

    Thanks for all your hard work on this plugin!

    1. Hi Cesar – no, sorry. I think you’ll need to make a separate list for each category. I attempted to do this once using the PHP shortcode then ordering by category. With each post, it would check if the category was the same as the previous, and if not, it would put up a different line of HTML to serve as a category header. If I remember correctly, I couldn’t get it to work because order by category no longer worked in the WordPress core. Anyone know if they’ve fixed that?

  13. I asked this question somewhere else as well, but not sure where now. Might as well try again just in case…

    I’m trying to replace my theme’s list shortcode with your plugin. I already use this plugin for some stuff and love it, but hope I can replicate what I do with the shortcode.

    I create pages that display thumbnail, title and excerpt by category in groups of 25. I can do exactly the same thing as my theme shortcode with your plugin until I have to go to the second group of 25 (and beyond).

    I know there is an “offset” function, but it’s not clear to me how I’d use it in this instance. How can I display just items 26-50 of a particular tag or category?

    Many thanks for your help!

      1. Oh yes I figured this out yesterday only but the problem is I have a number of custom fields, so I need to put a check if the field is available then show the custom field along with its heading like there is a custom field “Group discussions” which is present in few of the posts but I need to put a heading before the custom field value comes… so there has to be a way of adding an if this value exists then put the custom field value. 🙂

  14. Hi Kalin…thanks for such a wonderful plugin. I swear I had everything working correctly, then suddenly, after a refresh, the last item/post is showing up at the top of the list AND the bottom of the list. I only want it at the bottom.

    Any suggestions?

    Many blessings

    1. Okay, I added this feature to my list of wants for this plugin, though I don’t have any plans right now to return to development on this, so it really is a “wish” list.

  15. Hi there,

    I’ve deactivated the plugin without saving the values (as I didn’t know it would clean them by default). Is there a way to restore those values outside of the plugin? I’d appreciate that as I had a lot of custom values 🙁

    Thanks for your help.


    1. Oh, I’m sorry that happened. Unfortunately there’s nothing you can do unless you have database backups. I use WordPress Database Backup to send me a copy of my database every week. If you have something like that you could certainly copy over the old plugin data from the wp_options table, though I don’t know off the top of my head how to do that.

      This is kind of an issue in WP plugin development as officially, WordPress wants developers to clear all traces of their plugin from the database whenever it’s deactivated, but many developers don’t bother to do this so many people get used to having their settings saved even after deactivation. The problem with this is that it can cause bloating or other problems in the database if you don’t do a cleanup. I had to learn the hard way to always install plugins in a local testing environment, test them, then install on my live site.

      At the bottom of the Post List Plugin settings page, I have an option called, “Upon plugin deactivation clean up all database entries.” You can turn this off and it won’t run the cleanup on deactivation… for next time anyway.

      Sorry I couldn’t be more help 🙁

      1. Thanks for the quick response. I should have a backup of the DB, so will try to retrieve it. Fingers crossed…

  16. Hi! A great Plugin that saved me tons of time. But one question (maybe a stupid one): how can I display a “no record”-message when there are no posts matching the defined criterias?

    1. Good question. I never thought of that. It would have been easy to implement, but alas I’ve finished forward development on this. In the meantime you can change it in the code. Go to line 627 in kalins-post-list.php, located in your plugins folder. this sets the output to “” if there is no posts. Simply add whatever statement you want between the “”.

      if(count($posts) == 0){//return nothing if no results
      return "";

  17. This is awesome! I was overwhelmed at first, but after going through the tutorial it’s some pretty powerful stuff.

    One problem… What about if I want to display this content in the body of the home page — not a post or page? Is there a way to do that? I’d assume that would be with PHP. If you explain this somewhere, I apologize.


  18. I’ve just added Kalin’s Posts to a website that is in development (sorry not visible on the web yet). This website will have a custom post type (“property”) in addition to regular posts. I would like to do the following, but am unable to make it work:

    On a custom “property” post with say, “tag1”, have the Kalin’s Post widget list out the regular posts with the same tag. When I try this, it acts as if the custom property post has no tags and lists the beginning of an unlimited list of posts. If I “hard code” a tag by checking the box on the Kalin’s Post admin screen for a particular tag, it works just fine. But if I check only the “Include current post tags” nothing happens.

    As an aside, if I put the widget on a regular post page, it works just fine (listing out other regular posts with the same tag).

    Am I doing something wrong? Is this something this plug-in should do or am I trying to get it to do something it wasn’t intended to do?

    I’m running WP 3.2.1, with Light House 1.1.3 theme by templatesquare.

    Any help/guidance would be appreciated.

      1. Hi Wayne; sorry I don’t know what’s going on. I tried it out and it seems to work fine for me. I figured you’d found a bug, but I can’t seem to reproduce the error. Tried with both a shortcode and the widget. Are you sure there isn’t something else going on? Maybe the custom post type isn’t set up quite right in your theme or something. Sorry I couldn’t be of more help.

  19. Can you use your plug in to generate custom tag or category clouds? I noticed you could list related cats/tags after your list. I am trying to generate a very simple client list using tags to open a page to list all client related posts. Love your plugin, btw! Not being a programmer, it been my training wheels into new uses of taxonomy and short code:P

    1. No there isn’t any way to generate tag or category clouds 🙁 that’s not a bad idea though. I wanted to add a feature to display comments through the same system as though they were posts. I suppose that could be done similarly with tags and cats. Unfortunately I quit dev on this plugin and now I’m making a facebook mmo 🙂

    1. Sorry, I don’t really recall. I do remember seeing an issue with apostrophes showing as code and I intended to fix it with the last release, but I couldn’t seem to reproduce the error once I came back to it. It seemed like it was happening on rollover when I used excerpts as link titles, or something like that. Can you tell me where and how you’re seeing it?
      It could also be that the apostrophe is actually code in the post itself?

      1. It turns out to have been issues with the data following an import.

        Another question: Is it possible to sort my output by one of the custom fields?

      2. No, I don’t believe you can sort by a custom field through my interface. It might be simple to do by hacking the PHP, though I can’t remember very well as I haven’t worked in WordPress in a while.

  20. I’ve got an issue with the plugin no longer displaying the admin page, when I lick on the admin link it displays everything but the post lists. I looked at the source of the page an its getting an out of memory error on line 1400 of wp-db.php and thats part of the get_results function. I’m guessing I have too many post lists from what I’m seeing? I’ve added a set_ini for the memory in the top of the plugin.php file and it did not help. This is obviously causing me some problems, any sight would be most appreciated, thanks!

    1. Hi, sorry it’s taken so long to respond. I’m not sure what’s happening. I haven’t seen this error before. I suppose it’s possible you have too many presets, but I would think it would take 50 to 100 or more to cause real problems with the database… or maybe not. Does wordpress put a limit on the size of a plugin option entry?
      My first guess is that something got confused in the JSON that’s actually being saved to the database, like maybe you’ve got some characters in your presets that aren’t being processed properly.
      Have you tried uninstalling and re-installing the plugin?
      If you could send me a list of the presets and the code you’re using for each, that may illuminate something, like maybe the JSON string. If you look at the source for the admin page, it should include the entire JSON string that comes from the database in a javascript variable.
      Sorry I can’t be of more help 🙁

  21. The [/caption] came from the image attached. I think it means that it doesn’t strip correctly the image’s caption.
    Also if the post has an excerpt the length doesn’t work
    [post_excerpt length="250"]

    Any ideas?

    1. I actually wrote the code to get the length param to work in case of an excerpt that’s explicitly set on a post. But then I thought better about it and realized most people are not going to want the length param to work in that case. I certainly don’t because sometimes I have a list that has posts with and without excerpts and I want the entire excerpt to be used.
      However, I kept the code in tact and just commented it out. If you want the length param to work, just go into kalins-post-list.php and uncomment the block of code from line 333 to 338 within the postExcerptCallback function.

      1. It works but there are a couple of things to notice:

        1. If you have an actual excerpt it ignores the length parameter

        2. If you don’t have an excerpt the length parameter work but if there’s an image with caption it doesn’t strip the caption info:
        [caption id="attachment_1175" align="alignleft" wi...

        Do you know how can I resolve that?

        Thank you very much this plugin is the best I have found so far.

  22. A little side note: if you don’t set the Show Count to -1 for unlimited, and put no number in there at all, then the number of listed posts is limited by the setting “Blog pages show at most X posts” (Settings > Reading). 🙂

  23. Very helpful plugin, thank you for creating it.

    Is there a way to grab a thumbnail version (WP-downsampled) of the [post_thumb]? These get named with the dimensions appended to the image name, which can vary. As it is, [post_thumb] drops in the full size version of the image and I am able to scale it down (miraculously, retaining aspect), but it’s of course slow loading.

    1. Hi Greg.
      In fact you can change this to be either the thumbnail size or your custom made ones as read in http://codex.wordpress.org/Function_Reference/get_the_post_thumbnail

      Just look in kalins-post-list.php Line 282
      and change this line
      $arr = wp_get_attachment_image_src( get_post_thumbnail_id( $page->ID ), 'single-post-thumbnail' );

      to add the 'thumbnail' parameter wich must look like this
      $arr = wp_get_attachment_image_src( get_post_thumbnail_id( $page->ID ), 'thumbnail', 'single-post-thumbnail' );

      Now I get a [/caption] at the end of each element.
      Trying to solve that.


  24. I’ve created a dropdown list of sub-categories, styled using CSS, but cannot figure out why the hover is still the default blue bar. Any suggestions??

    1. Hi, sorry it took so long to respond. I’m not really sure about custom CSS stuff. I’m still a bit of a CSS novice 🙂 I don’t think I’ve ever tried to style a dropdown before.

  25. Thanks for the plug-in, just what I was looking for. I’m trying to change the color of the hover in the drop down menu, it’s currently blue. Can’t seem to find it in the editor. Thanks!

  26. Great plugin.
    I’m just havin a bit trouble using the [post_content] shortcode.
    It seems to maak my html br(eaks) disappear.
    Is there a solution for that?

    1. Not without hacking a little into the source. If you know PHP it should be relatively easy to make an adjustment in the internalShortcodeReplace function but right now all its doing is displaying the raw post content without making any adjustments to it.

      1. Thanks, I’ll look into that.

        I still don’t understand why single posts work OK and in the list they lose their breaks.

        I’ll be back 🙂

      2. I’m slightly confused by that too. It seems like WordPress handles them differently than normal HTML, like the theme searches out the line breaks then inserts its own HTML to display it. If you look at the HTML in the post edit page, there’s no P or BR tags.

Leave a Reply

Your email address will not be published. Required fields are marked *

KalinBooks.com is the ramblings of Kalin Ringkvist, a science fiction author with a passion for peace and freedom.