=== List category posts === Contributors: fernandobt Donate Link: http://picandocodigo.net/programacion/wordpress/list-category-posts-wordpress-plugin-english/#support Tags: list, categories, posts, cms Requires at least: 3.3 Tested up to: 4.0 Stable tag: 0.51 License: GPLv2 or later License URI: http://www.gnu.org/licenses/gpl-2.0.html == Description == List Category Posts allows you to list posts by category in a post/page using the [catlist] shortcode. When you're editing a page or post, directly insert the shortcode in your text and the posts will be listed there. The **basic** usage would be something like this: `[catlist id=1]` `[catlist name="news"]` The shortcode accepts a category name or id, the order in which you want the posts to display, and the number of posts to display. You can also display the post author, date, excerpt, custom field values, even the content! The [catlist] shortcode can be used as many times as needed with different arguments on each post/page. You can add a lot more parameters according to what and how you want to show your post's list: `[catlist id=1 numberposts=10]` There's an options page with only one option -for the moment-, new options will be implemented on demand. **[Please read the instructions](http://wordpress.org/extend/plugins/list-category-posts/other_notes/)** to learn which parameters are available and how to use them. If you want to **List Categories** instead of posts you can use my other plugin **[List categories](http://wordpress.org/plugins/list-categories/)**. You can find **Frequently Asked Questions** [here](https://github.com/picandocodigo/List-Category-Posts/blob/master/doc/FAQ.md#frequently-asked-questions). **Customization** The different elements to display con be styled with CSS. you can define an HTML tag to wrap the element with, and a CSS class for this tag. Check [Other Notes](http://wordpress.org/extend/plugins/list-category-posts/other_notes/) for usage. Great to use WordPress as a CMS, and create pages with several categories posts. **Widget** The plugin includes a widget which works pretty much the same as the plugin. Just add as many widgets as you want, and select all the available options from the Appearence > Widgets page. Please, read the information on [Other Notes](http://wordpress.org/extend/plugins/list-category-posts/other_notes/) and [Changelog](http://wordpress.org/extend/plugins/list-category-posts/changelog/) to be aware of new functionality, and improvements to the plugin. **Videos** Some users have made videos on how to use the plugin, (thank you! you people are awesome!). Check them out here: * [Manage WordPress Content with List Category Posts Plugin](http://www.youtube.com/watch?v=kBy_qoGKpdo) * [Build A Start Here Page with List Category Posts](http://www.youtube.com/watch?v=9YJpZfHIwIY) * [WordPress: How to List Category Posts on a Page](http://www.youtube.com/watch?v=Zfnzk4IWPNA) **Support the plugin** If you've found the plugin useful, consider making a [donation via PayPal](http://picandocodigo.net/programacion/wordpress/list-category-posts-wordpress-plugin-english/ "Donate via PayPal") or visit my Amazon Wishlist for [books](http://www.amazon.com/gp/registry/wishlist/2HU1JYOF7DX5Q/ref=wl_web "Amazon Wishlist") or [comic books](http://www.amazon.com/registry/wishlist/1LVYAOJAZQOI0/ref=cm_wl_rlist_go_o) :). **Development** I've moved the development to [GitHub](https://github.com/picandocodigo/List-Category-Posts). Fork it, code, make a pull request, suggest improvements, etc. over there. I dream of the day all of the WordPress plugins will be hosted on Github :) ==Installation== * Upload listcat directory into your wp-content/plugins/ directory. * Login to your WordPress Admin menu, go to Plugins, and activate it. * You can find the List Category Posts widget in the Appearence > Widgets section on your WordPress Dashboard. * If you want to customize the way the plugin displays the information, check the section on Templates on this documentation. ==Other notes== ==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. ==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== * **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. * **currenttags** - Display posts from the current post's tags (won't work on pages since they have no tags). * **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]` * **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. * **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. 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 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. * **title_limit** - Set the limit of characters for the title. Ex: `[catlist id=2 title_limit=50]` will show only the first 50 characters of the title and add "…" at the end. * **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** - **WARNING**: If you want to show the content on your listed posts, you might want to do this from a new [Page Template](http://codex.wordpress.org/Page_Templates) or a [Custom Post Type](http://codex.wordpress.org/Post_Types#Custom_Post_Type_Templates) template. Using this parameter is discouraged, you can have memory issues as well as infinite loop situations when you're displaying a post that's using List Category Posts. You have been warned. Usage: 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. * **catname** - Show the title of the category (or categories), works exactly as `catlink`, but it doesn't add a link to the category. * **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: ```