How to use:

INSTRUCTIONS on how to use the plugin „List Category Posts“

Selecting the category

The plugin can figure out the category from which you want to list posts in several ways. You should use only one of these methods since these are all mutually exclusive, weird results are expected when using more than one:

  • Using the category id.
    • id – To display posts from a category using the category’s id. Ex: ]catlist id=24].
  • The category name or slug.
    • name – To display posts from a category using the category’s name or slug. Ex: ]catlist name=mycategory]
  • Detecting the current post’s category. You can use the categorypage parameter to make it detect the category id of the current posts, and list posts from that category.
    • categorypage – Set it to „yes“ if you want to list the posts from the current post’s category. ]catlist categorypage=“yes“]

When using List Category Posts whithout a category id, name or slug, it will post the latest posts from every category.

Using several categories

  • include posts from several categories with AND relationship, posts that belong to all of the listed categories (note this does not show posts from any children of these categories): ]catlist id=17+25+2] – ]catlist name=sega+nintendo].
  • include posts from several categories with OR relationship, posts that belong to any of the listed categories: ]catlist id=17,24,32] – ]catlist name=sega,nintendo].
  • exclude a category with the minus sign (-): ]catlist id=11,-32,16], ]catlist id=1+2-3]. Important: When using the and relationship, the order must be categories you want to include first, and exclude after. So ]catlist id=1+2-3] will work, but ]catlist id=1+2-3+4] won’t.

Pagination

To use pagination, you need to set the following parameters:

  • pagination set it to yes.
  • numberposts – Posts per page are set with the numberposts parameter.
  • instance (only necessary when using the shortcode with pagination more than once in the same page/post) – a number or name to identify the instance where you are using pagination. Since you can use the shortcode several times in the same page or post, you need to identify the instance so that you paginate only that instance.

Example:

]catlist id=3 numberposts=5 pagination=yes instance=1]
]catlist id=5 numberposts=15 pagination=yes instance=2]

You can customize what to show for the „next“ and „previous“ buttons in the pagination navigation. Use the following params:

  • pagination_prev – Replace the „<<“ characters in the „previous“ button in the pagination navigation with a custom text.
  • pagination_next – Replace the „>>“ characters in the „next“ button in the pagination navigation with a custom text.

Changing the pagination CSS

If you want to customize the way the pagination is displayed, you can copy the lcp_paginator.css file from the plugin’s directory to your theme’s directory and customize it. Do not customize the file on the plugin’s directory since this file will be overwritten every time you update the plugin.

Other parameters

  • tags – Tag support, you can display posts from a certain tag.
  • exclude_tags – Exclude posts from one or more tags: ]catlist tags=“videogames“ exclude_tags=“sega,sony“]
  • orderby – To customize the order. Valid values are:
    • author – Sort by the numeric author IDs.
    • category – Sort by the numeric category IDs.
    • content – Sort by content.
    • date – Sort by creation date.
    • ID – Sort by numeric post ID.
    • menu_order – Sort by the menu order. Only useful with pages.
    • mime_type – Sort by MIME type. Only useful with attachments.
    • modified – Sort by last modified date.
    • name – Sort by stub.
    • parent – Sort by parent ID.
    • password – Sort by password.
    • rand – Randomly sort results.
    • status – Sort by status.
    • title – Sort by title.
    • type – Sort by type. Ex: ]catlist name=mycategory orderby=date]
  • customfield_orderby – You can order the posts by a custom field. For example: ]catlist numberposts=-1 customfield_orderby=Mood order=desc] will list all the posts with a „Mood“ custom field. Remember the default order is descending, more on order:
  • order – How to sort orderby. Valid values are:
    • ASC – Ascending (lowest to highest).
    • DESC – Descending (highest to lowest). Ex: ]catlist name=mycategory orderby=title order=asc]
  • numberposts – Number of posts to return. Set to 0 to use the max number of posts per page. Set to -1 to remove the limit. Ex: ]catlist name=mycategory numberposts=10] You can set the default number of posts globally on the options page on your Dashboard in Settings / List Category Posts.
  • no_posts_text – Text to display when no posts are found. If you don’t specify it, nothing will get displayed where the posts should be.
  • monthnum and year – List posts from a certain year or month. You can use these together or independently. Example: ]catlist year=2015] will list posts from the year 2015. ]catlist monthnum=8] will list posts published in August of every year. ]catlist year=2012 monthnum=12] will list posts from December 2012.
  • search – List posts that match a search term. ]catlist search=“The Cake is a lie“]
  • date – Display post’s date next to the title. Default is ’no‘, use date=yes to activate it.
  • author – Display the post’s author next to the title. Default is ’no‘, use author=yes to activate it.
  • dateformat – Format of the date output. The default format is the one you’ve set on your WordPress settings. Example: ]catlist id=42 dateformat=“l F dS, Y“] would display the date as „Monday January 21st, 2013“. Check http://codex.wordpress.org/Formatting_Date_and_Time for more options to display date.
  • excerpt – Display the post’s excerpt. Default is ’no‘, use excerpt=yes to activate it. If you don’t have an excerpt in your post, the plugin will fetch this text from the content, striping its images, shortcodes and HTML tags. The limit is set by the excerpt_size parameter (55 words by default). If you want the automatically generated excerpt to respect your theme’s allowed HTML tags, you should use excerpt_strip=no. If the post has an excerpt, the HTML tags are automatically stripped. If you want to overwrite the post’s excerpt with an automatically generated one (may be usefull to allow HTML tags), use excerpt_overwrite=yes. I added this last parameter to have consistency across excerpts.
  • excerpt_size – Set the number of words to display from the excerpt. Default is 55. Eg: excerpt_size=30
  • excerpt_strip – Set it to yes to strip the excerpt’s HTML tags.
  • excludeposts – IDs of posts to exclude from the list. Use ‚this‘ to exclude the current post. Ex: ]catlist excludeposts=this,12,52,37]
  • offset – You can displace or pass over one or more initial posts which would normally be collected by your query through the use of the offset parameter.
  • content – Show the full content of the post. If there’s a <!–more–> tag in the post, then it will behave just as WordPress does: only show the content previous to the more tag. Default is ’no‘. Ex: ]catlist content=yes]
  • catlink – Show the title of the category with a link to the category. Use the catlink_string option to change the link text. Default is ’no‘. Ex: ]catlist catlink=yes]. The way it’s programmed, it should only display the title for the first category you chose, and include the posts from all of the categories. I thought of this parameter mostly for using several shortcodes on one page or post, so that each group of posts would have the title of that group’s category. If you need to display several titles with posts, you should use one ]catlist] shortcode for each category you want to display.
  • category_count – Shows the posts count in that category, only works when using the catlink option: ]catlist name=nintendo catlink=yes category_count=yes]
  • comments – Show comments count for each post. Default is ’no‘. Ex: ]catlist comments=yes].
  • thumbnail – Show post thumbnail (http://markjaquith.wordpress.com/2009/12/23/new-in-wordpress-2-9-post-thumbnail-images/). Default is ’no‘. Ex: ]catlist thumbnail=yes].
  • thumbnail_size – Either a string keyword (thumbnail, medium, large or full) or 2 values representing width and height in pixels. Ex: ]catlist thumbnail_size=32,32] or ]catlist thumbnail_size=thumbnail]
  • thumbnail_class – Set a CSS class for the thumbnail.
  • post_type – The type of post to show. Available options are: post – Default, page, attachment, any – all post types.
  • post_status – use post status, default value is ‚publish‘. Valid values:
    • publish – a published post or page.
    • pending – post is pending review.
    • draft – a post in draft status.
    • auto-draft – a newly created post, with no content.
    • future – a post to publish in the future.
    • private – not visible to users who are not logged in.
    • inherit – a revision. see get_children.
    • trash – post is in trashbin (available with Version 2.9).
    • any – retrieves any status except those from post types with ‚exclude_from_search‘ set to true.
  • show_protected – Show posts protected by password. By default they are not displayed. Use: ]catlist show_protected=yes]
  • post_parent – Show only the children of the post with this ID. Default: None.
  • post_suffix – Pass a String to this parameter to display this String after every post title.
    Ex: ]catlist numberposts=-1 post_suffix=“Hello World“] will create something like:<ul id=lcp_instance_0> <li> <a href=“http://127.0.0.1:8080/wordpress/?p=42″ title=“WordPress“> WordPress </a> Hello World </li>
  • class – CSS class for the default UL generated by the plugin.
  • custom fields – To use custom fields, you must specify two values: customfield_name and customfield_value. Using this only show posts that contain a custom field with this name and value. Both parameters must be defined, or neither will work.
  • customfield_display – Display custom field(s). You can specify many fields to show, separating them with a coma. If you want to display just the value and not the name of the custom field, use customfield_display_name and set it to no. By default, the custom fields will show inside a div with a specific class: <div>. You can customize this using the customfield_tag and customfield_class parameters to set a different tag (instead of the div) and a specific class (instead of lcp-customfield).
  • customfield_display_name – To use with customfield_display. Use it to just print the value of the Custom field and not the name. Example:
]catlist numberposts=-1 customfield_display="Mood"
    customfield_display_name="no"]

Will print the value of the Custom Field „Mood“ but not the text „Mood: [value]“.

  • template – File name of template from templates directory without extension. Example: For ‚template.php‘ value is only ‚template‘. Default is ‚default‘, which displays an unordered list (ul html tag) with a CSS class. This class can be passed as a parameter or by default it’s: ‚lcp_catlist‘. You can also use the default ‚div‘ value. This will output a div with the ‚lcp_catlist‘ CSS class (or one you pass as parameter with the class argument). The inner items (posts) will be displayed between p tags.
  • morelink – Include a „more“ link to access the category archive for the category. The link is inserted after listing the posts. It receives a string of characters as a parameter which will be used as the text of the link. Example: ]catlist id=38 morelink=“Read more“]
  • posts_morelink – Include a „read more“ link after each post. It receives a string of characters as a parameter which will be used as the text of the link. Example: ]catlist id=38 posts_morelink=“Read more about this post“]
  • link_target – Select the target attribute for links to posts (target=_blank, _self, _parent, _top, *framename*). Example: [catlink id=3 link_target=_blank] will create: <a href=“http://localhost/wordpress/?p=45″ title=“Test post“ target=“_blank“>Test post</a>

HTML & CSS Customization

You can customize what HTML tags different elements will be sorrounded with and a CSS class for this element, or just a CSS class which will wrap the element with a span tag.

The customizable elements (so far) are: author, catlink (category link), comments, date, excerpt, morelink („Read More“ link), thumbnail and title (post title).

The parameters are:

autor_tag, author_class, catlink_tag, catlink_class, comments_tag,
comments_class, date_tag, date_class, excerpt_tag, excerpt_class,
morelink_class, thumbnail_class, title_tag, title_class,
posts_morelink_class, customfield_tag, customfield_class

So let’s say you want to wrap the displayed comments count with the p tag and a „lcp_comments“ class, you would do:

]catlist id=7 comments=yes comments_tag=p comments_class=lcp_comments]

This would produce the following code:

<p> (3)</p>

Or you just want to style the displayed date, you could wrap it with a span tag:

]catlist name=blog date=yes date_tag=span date_class=lcp_date]

This would produce the following code:

<span>March 21, 2011</span>

Elements without a specified tag, but a specified class, will be wrapped with a span tag and its class. For example this:

]catlist id=7  date=yes date_class="lcp_date"]

Will produce the following:

<span>October 23, 2013</span>

The only exceptions here are the title_tag and title_class parameters. If you only use the title_class parameter, the CSS class will be assigned to the a tag like this:

]catlist id=1 title_class="lcp_title"]

Will produce:

<a href="http://127.0.0.1/wordpress/?p=38" title="Test">Test</a>

But if you use both:

]catlist numberposts=5 title_class=lcp_title tag=h4]

You will get:

<h4>
    <a title="Hipchat" href="http://127.0.0.1:8080/wordpress/?p=40"></a>
</h4>

Template System

Templates for the List Category Plugin are searched for in your WordPress theme’s folder. You should create a folder named list-category-posts under ‚wp-content/themes/your-theme-folder‘. Template files are .php files.

You can use the included template as an example to start. It’s in the plugin’s template folder under the name default.php. To use a template, use this code:

]catlist id=1 template=templatename]

If the template file were templatename.php.

You can have as many different templates as you want, and use them in different pages and posts. The template code is pretty well documented, so if you’re a bit familiar with HTML and PHP, you’ll have no problems creating your own template. I’m planning on reworking the template system in order to have a really user friendly way to create templates.