Since the documentation on how to use the plugin has passed wordpress.org’s character limit, the text was cut. I’ve since started using a wiki for more comfortable reading and maintaining. Please check it out, suggestions are welcome on GitHub issues!
Instructions on how to use the plugin
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 post, 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 MORE THAN ONE CATEGORY
Posts from several categories with an 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].
Posts from several categories with an 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, you should write the categories you want to include first, and then the ones you want to exclude. So [catlist id=1+2-3] will work, but [catlist id=1+2-3+4] won’t.
Other ways of selecting what posts to show
child_categories – Exclude/include posts from the child categories. By default they are included. If you have a “Parent Category” and you use: [catlist name=”Parent Category”], you’ll see posts from it’s child categories as if they were posts from the same category. You can use this parameter to exclude these posts: [catlist name=”Parent Category” child_categories=false].
author_posts – Get posts by author. Use ‘user_nicename’ (NOT name). Example: [catlist author_posts=”fernando”]
tags – Tag support, display posts from a certain tag. You can use an “OR” relationship [catlist tags=”nintendo,sega”] or “AND” relationship (posts that belong to all of the listed tags): [catilst tags=”nintendo+sega”].
taxonomy – You can select posts using custom taxonomies. You need to set the taxonomy and the terms: [catlist taxonomy=’person’ terms=’bob’].
currenttags – Display posts from the current post’s tags (won’t work on pages since they have no tags). Pass it the ‘yes’ string for it to work: [catlist currenttags=”yes”]
exclude_tags – Exclude posts from one or more tags: [catlist tags=”videogames” exclude_tags=”sega,sony”]
starting_with – Get posts whose title starts with a certain letter. Example: [catlist starting_with=”l”] will list all posts whose title starts with L. You can use several letters: [catlist starting_with=”m,o,t”].
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.
date ranges – You can also use date ranges for listing posts. For example “list every post after March 14th, 2005″. The parameters are: after, after_year, after_month, after_day, before, before_year, before_month, before_day. These parameters are used to specify data_query arguments (see: the codex).
If you want to list all the posts before a given date, say Jun 17th, 2007 you can use these two options:
[catlist before_year=2007 before_month=06 before_day=17]
Or you can use the before parameter with a strtotime()-compatible string:
The same works for posts after a given date, you can use:
[catlist after_year=2007 after_month=06 after_day=17]
Or just after with a strtotime()-compatible string:
after takes priority over after_year, after_month, and after_day.
before takes priority over before_year, before_month, and before_day.
search – List posts that match a search term. [catlist search=”The Cake is a lie”]
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.
post_type – The type of post to show. Available options are: post – Default, page, attachment, any – all post types. You can use several types, example: [catlist post_type=”page,post” numberposts=-1]
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. You can use several post statuses. Example: [catlist post_status=”future, publish” excludeposts=this]
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.
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.
conditional_title – Display a custom title before the posts list. The title is not displayed if the list is empty. Set to the empty string (default value) to disable. Example: [catlist conditional_title=”Other posts”].
conditional_title_tag – Specify the tag used for the conditional title. Defaults to ‘h3’.
conditional_title_class – Specify the class used for the conditional title. Defaults to the empty string (no special class).
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.
date – Display post’s date next to the title. Default is ‘no’, use date=yes to activate it. You can set a css class and an html tag to wrap the date in with date_class and date_tag (see HTML & CSS Customization further below).
date_modified – Display the date a post was last modified next to the title. You can set a css class and an html tag to wrap the date in with date_modified_class and date_modified_tag (see HTML & CSS Customization further below).
author – Display the post’s author next to the title. Default is ‘no’, use author=yes to activate it. You can set a css class and an html tag to wrap the author name in with author_class and author_tag (see HTML & CSS Customization further below).
When displaying the post author, you can also display a link to the author’s page. The following parameter only works if author=yes is present in the shortcode:
author_posts_link – Gets the URL of the author page for the author. The HTML and CSS customization are the ones applied to author.
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 a plain text excerpt of the post. Default is ‘no’, use excerpt=yes or excerpt=full to activate it. If you have a separate excerpt in your post, this text will be used. If you don’t have an explicit excerpt in your post, the plugin will generate one from the content, striping its images, shortcodes and HTML tags. If you want to overwrite the post’s separate excerpt with an automatically generated one (may be useful to allow HTML tags), use excerpt_overwrite=yes.
If you use excerpt=yes, the separate excerpt or content will be limited to the number of words set by the excerpt_size parameter (55 words by default).
If you use excerpt=full the plugin will act more like WordPress. If the post has a separate excerpt, it will be used in full. Otherwise if the content has a Continue reading “Tag list plugin.”